模型 - AgentKit 文档

模型负责理解输入、选择工具并生成回答。智能体默认读取环境变量或 config.yaml 中的全局模型配置，也可以通过 Agent 参数为不同智能体分别配置模型、端点和凭证

为单个智能体指定模型

先完成安装，并选择以下一种平台配置。模型需已在对应账号中开通；也可以将名称替换为有权访问的模型或推理接入点

火山引擎
BytePlus

export CLOUD_PROVIDER="volcengine"
export MODEL_AGENT_NAME="doubao-seed-2-1-pro-260628"
export MODEL_AGENT_API_BASE="https://ark.cn-beijing.volces.com/api/v3/"
export MODEL_AGENT_API_KEY="<model-api-key>"

export CLOUD_PROVIDER="byteplus"
export MODEL_AGENT_NAME="seed-2-0-lite-260228"
export MODEL_AGENT_API_BASE="https://ark.ap-southeast.bytepluses.com/api/v3"
export MODEL_AGENT_API_KEY="<model-api-key>"

在同一终端运行以下 main.py：

main.py

import asyncio
import os
from veadk import Agent, Runner

agent = Agent(
    name="assistant",
    model_name=os.environ["MODEL_AGENT_NAME"],
    model_provider="openai",
    model_api_base=os.environ["MODEL_AGENT_API_BASE"],
    model_api_key=os.environ["MODEL_AGENT_API_KEY"],
)

async def main():
    print(await Runner(agent=agent).run(
        messages="Explain what an AI agent does in one paragraph.",
        session_id="model-demo",
    ))

if __name__ == "__main__":
    asyncio.run(main())

执行 python main.py 后会输出模型回答。若所有智能体共用上述配置，可以直接使用 Agent(name="assistant")

模型参数与全局配置

显式构造参数覆盖对应的全局配置；未传入的字段沿用全局值。config.yaml 从当前目录向上查找，已有环境变量优先于配置文件中的同名设置。配置文件写法见快速开始

参数	类型	默认值	对应环境变量或说明
`model_name`	`str \| list[str]`	平台默认模型	`MODEL_AGENT_NAME`；列表用于模型回退
`model_provider`	`str`	`"openai"`	`MODEL_AGENT_PROVIDER`；LiteLLM 提供商标识，兼容 OpenAI 协议的方舟端点使用 `openai`
`model_api_base`	`str`	平台默认端点	`MODEL_AGENT_API_BASE`
`model_api_key`	`str`	`""`，初始化时解析	`MODEL_AGENT_API_KEY`
`model_api_key_name`	`str`	`""`	`MODEL_AGENT_API_KEY_NAME`；按名称查询方舟 API Key
`model_fallbacks`	`list[str \| ModelFallbackEndpoint]`	`[]`	追加的回退模型或端点，也接受匹配字段的字典
`model_extra_config`	`dict`	`{}`	模型请求的额外配置；可用字段取决于所用接口
`enable_responses`	`bool`	`False`	启用火山方舟 Responses API
`enable_responses_cache`	`bool`	`True`	Responses 模式下的缓存开关

未覆盖全局默认值时，火山引擎使用 doubao-seed-2-1-pro-260628 和 https://ark.cn-beijing.volces.com/api/v3/；设置 CLOUD_PROVIDER=byteplus 后使用 seed-2-0-lite-260228 和 https://ark.ap-southeast.bytepluses.com/api/v3。切换平台前请同时检查原有 MODEL_AGENT_* 环境变量，避免继续使用另一平台的配置

按名称解析 API Key

API Key 的解析顺序为：非空 model_api_key、MODEL_AGENT_API_KEY、model_api_key_name 或 MODEL_AGENT_API_KEY_NAME 指定的名称，最后使用账号中默认查询到的 Key

export MODEL_AGENT_API_KEY_NAME="production-key"

按名称查询需要有权读取方舟 API Key 的账号凭证；该名称不是密钥值。已有 Key 值时不会再按名称查询。该能力从 VeADK 1.0.2 开始提供

限流重试

默认 adk 运行时、未启用 Responses 且未传入自定义 model 时，VeADK 会对尚未产生任何模型响应的 HTTP 429 错误重试一次。延迟取有效的 Retry-After 数值，上限为 2 秒；缺失或无效时使用 0.5 秒。已开始输出的请求不会由这层重试重新执行

配置回退模型

在前面的示例中额外设置 BACKUP_MODEL_NAME，并将 agent 定义替换为：

agent = Agent(
    name="assistant",
    model_name=[os.environ["MODEL_AGENT_NAME"], os.environ["BACKUP_MODEL_NAME"]],
)

列表第一项为主模型，其余按顺序作为回退候选，共用提供商、端点和凭证。也可以使用 model_fallbacks=["备用模型名称"] 追加同提供商模型；若两处均有配置，先尝试 model_name 列表中的候选，再尝试 model_fallbacks 默认模型接口与 Responses API 均可配置同提供商名称回退，候选模型必须支持同一请求所用的工具、多模态或输出格式。回退用于处理请求失败，不会因回答质量不佳自动切换模型

配置跨提供商回退模型

备用模型使用不同提供商、端点或凭证时，使用 ModelFallbackEndpoint。运行前除主模型配置外，还需设置 BACKUP_MODEL_NAME、BACKUP_MODEL_PROVIDER、BACKUP_MODEL_API_BASE 和 BACKUP_MODEL_API_KEY 为备用服务的实际配置

fallback.py

import asyncio
import os
from veadk import Agent, ModelFallbackEndpoint, Runner

agent = Agent(
    name="assistant",
    model_fallbacks=[
        ModelFallbackEndpoint(
            model_name=os.environ["BACKUP_MODEL_NAME"],
            model_provider=os.environ["BACKUP_MODEL_PROVIDER"],
            model_api_base=os.environ["BACKUP_MODEL_API_BASE"],
            model_api_key_env="BACKUP_MODEL_API_KEY",
        ),
    ],
)

async def main():
    print(await Runner(agent=agent).run(
        messages="Explain model fallback briefly.", session_id="fallback-demo"
    ))

if __name__ == "__main__":
    asyncio.run(main())

`ModelFallbackEndpoint` 参数

参数	类型	默认值	说明
`model_name`	`str`	必填	模型名称；不带前缀且未指定提供商时使用主模型提供商
`model_provider`	`str \| None`	`None`	备用提供商；使用不同提供商时不会沿用主模型端点和凭证
`model_api_base`	`str \| None`	`None`	备用端点；跨提供商未设置时由 LiteLLM 使用提供商默认地址，并非所有提供商都有默认地址
`model_api_key`	`str \| None`	`None`	备用 Key 值，优先于 `model_api_key_env`
`model_api_key_env`	`str \| None`	`None`	保存备用 Key 的环境变量名称，创建智能体时读取；缺失时由 LiteLLM 尝试提供商默认凭证
`model_extra_config`	`dict`	`{}`	备用请求配置；显式提供的 `extra_headers`、`extra_body` 字典与主模型对应字典按键合并，备用值覆盖同名键，不递归合并嵌套对象

可以使用字典代替对象，支持 model、provider、api_base 或 base_url、api_key、api_key_env、extra_config 别名。跨提供商时建议明确填写 model_provider、端点和凭证，避免继承不适用的配置

回退限制

enable_responses=True 只接受字符串形式的同提供商回退；端点对象或字典会导致初始化失败
codex 和 piagent 运行时忽略回退链；需要该能力时使用 adk，参见运行时
在默认运行时显式传入自定义 model 对象时，model_fallbacks 不生效，应在该对象上配置回退

Responses API

Responses API 提供多轮上下文衔接、多模态输入和结构化输出。使用前确认目标端点与模型支持火山方舟 Responses 协议；普通的 OpenAI 兼容端点不代表支持本节全部能力

启用

需要 google-adk>=1.34.0。在模型已经配置好的基础上设置 Agent(enable_responses=True)；默认关闭该功能。BytePlus 应使用该账号可用且明确支持对应能力的模型与端点，不能仅通过切换开关获得支持

多模态理解

FileData.file_uri 支持以下来源，mime_type 应与文件内容一致：

来源	写法	使用条件
本地文件	`file:///绝对路径/example.png`	运行进程可读取文件；VeADK 通过 Files API 上传
已上传文件	`file_id://文件标识`	文件属于可访问的 Files API 资源
网络地址	`https://...`	模型服务可访问该地址

本地文件会发送到模型服务。运行前确认文件内容适合上传，并检查服务支持的格式与大小限制

将一张 PNG 图片保存为当前目录的 example.png，然后运行 python image_reader.py：

image_reader.py

import asyncio
from pathlib import Path
from google.genai import types
from veadk import Agent, Runner

async def main():
    image_path = Path("example.png").resolve(strict=True)
    agent = Agent(name="image_reader", enable_responses=True)
    runner = Runner(agent=agent, app_name="image_demo", user_id="demo-user")
    await runner.session_service.create_session(
        app_name="image_demo", user_id="demo-user", session_id="image-session"
    )
    message = types.Content(role="user", parts=[
        types.Part(text="Describe this image."),
        types.Part(file_data=types.FileData(
            file_uri=image_path.as_uri(), mime_type="image/png"
        )),
    ])
    async for event in runner.run_async(
        user_id="demo-user", session_id="image-session", new_message=message
    ):
        if event.is_final_response() and event.content:
            print("".join(part.text or "" for part in event.content.parts or []))

if __name__ == "__main__":
    asyncio.run(main())

视频元数据应设置在 types.Part 上，与 file_data 并列。以下片段可替换图片 Part，抽帧频率的可用范围以模型服务为准：

video_part = types.Part(
    file_data=types.FileData(
        file_uri=Path("example.mp4").resolve(strict=True).as_uri(),
        mime_type="video/mp4",
    ),
    video_metadata=types.VideoMetadata(fps=1),
)

配置方舟上下文管理

对于支持 context_management 的模型，可通过 model_extra_config 提供配置。以下片段请求清理较早的思维内容，仅保留最近一个思维轮次：

agent = Agent(
    enable_responses=True,
    model_extra_config={
        "context_management": {
            "edits": [{
                "type": "clear_thinking",
                "keep": {"type": "thinking_turns", "value": 1},
            }],
        },
    },
)

上下文缓存

Responses 模式默认启用缓存。缓存命中取决于服务及请求内容，不保证每次都降低用量。可设置 enable_responses_cache=False 关闭返回事件的 usage_metadata.cached_content_token_count 表示缓存命中的 token 数，prompt_token_count 表示输入 token 总数；后者大于零时才可计算两者之比。使用 Runner.run_async 读取事件以检查用量配置 output_schema 时，VeADK 会移除与结构化输出冲突的缓存设置，示例见结构化输出

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

模型

为单个智能体指定模型

模型参数与全局配置

按名称解析 API Key

限流重试

配置回退模型

配置跨提供商回退模型

`ModelFallbackEndpoint` 参数

回退限制

Responses API

启用

多模态理解

配置方舟上下文管理

上下文缓存

​为单个智能体指定模型

​模型参数与全局配置

​按名称解析 API Key

​限流重试

​配置回退模型

​配置跨提供商回退模型

​ModelFallbackEndpoint 参数

​回退限制

​Responses API

​启用

​多模态理解

​配置方舟上下文管理

​上下文缓存

为单个智能体指定模型

模型参数与全局配置

按名称解析 API Key

限流重试

配置回退模型

配置跨提供商回退模型

`ModelFallbackEndpoint` 参数

回退限制

Responses API

启用

多模态理解

配置方舟上下文管理

上下文缓存