config.yaml 设置的模型（参见快速开始）。当前默认推理模型为 doubao-seed-2-1-pro-260628。也可以在创建智能体时为其单独指定模型。
为单个智能体指定模型
通过model_name 与 model_provider 覆盖全局默认模型：
model_provider、model_api_base、model_api_key 均沿用全局配置。
使用非原生模型接口（即设置了 model_provider）时，VeADK 会在模型尚未输出任何内容的阶段自动对 HTTP 429 限流错误重试一次。重试延迟优先读取响应头中的 Retry-After，上限为 2 秒，未提供时使用 0.5 秒。一旦模型已经开始输出内容，不再进行重试，以避免重复输出。
按名称解析 API Key
除直接设置MODEL_AGENT_API_KEY 外，还可以设置 MODEL_AGENT_API_KEY_NAME，让 VeADK 按名称获取火山方舟 API Key。显式提供的 Key 始终优先：
model_api_key_name。该能力从 VeADK 1.0.2 开始提供。
配置回退模型
model_name 也接受一个列表：第一个为主模型，其余作为回退模型；当主模型不可用时，依次尝试后续模型。
enable_responses=True 的 Responses API。
配置跨提供商回退模型
model_name 列表只能指定同一提供商下的回退模型。当回退模型使用不同的提供商、API 地址或 API Key 时，通过 model_fallbacks 参数指定。model_fallbacks 接受字符串或 ModelFallbackEndpoint 对象的列表，VeADK 会将其与 model_name 列表中的回退条目合并后一并传给 LiteLLM。
字符串条目按主模型的 model_provider 自动添加提供商前缀，等价于在 model_name 列表中追加同提供商模型名称：
ModelFallbackEndpoint 为每个回退端点单独指定提供商、API 地址与凭证。ModelFallbackEndpoint 已从 veadk 顶层包导出：
ModelFallbackEndpoint 字段匹配的字典。VeADK 同时接受完整字段名与 LiteLLM 风格的别名：
ModelFallbackEndpoint 参数
ModelFallbackEndpoint 同时接受 LiteLLM 风格的别名：model、provider、api_base（或 base_url）、api_key、api_key_env、extra_config。在
codex 或 piagent 运行时中配置 model_fallbacks 时，回退链会被忽略，因为外部运行时不构建 LiteLLM 客户端。如需回退能力，请使用默认的 ADK 运行时。详见运行时。当同时传入
model（自定义 LiteLLM 客户端）与 model_fallbacks 时，model_fallbacks 不会生效；请在自定义模型对象上配置回退。Responses API
Responses API 是火山方舟推出的接口，原生支持高效的上下文管理，输入输出格式更简洁，并具备更强的工具调用与多模态能力。在 VeADK 中启用后，智能体的每一轮对话都会经由该接口，从而获得原生的上下文缓存与图片、视频、文档理解能力。启用
在创建智能体时设置enable_responses=True：
google-adk>=1.34.0，且所用模型需支持该接口（豆包系列 0615 版本之后默认支持）。
多模态理解
除文本外，Responses API 还支持图片、视频与文档理解。通过google.genai.types.FileData 传入多模态数据，file_uri 支持三种来源：
- 本地文件路径：
file://{本地路径}，底层自动经 Files API 上传。 - Files API 资源：
file_id://{file_id}，用于已上传的文件。 - 网络地址：直接传入
https://链接，按mime_type识别类型。
FileData 中附带 video_metadata，用 fps 控制抽帧频率（默认 1，可在 0.2–5 之间调整）。
配置方舟上下文管理
启用 Responses API 时，可通过model_extra_config 传入方舟支持的 context_management 配置。以下示例会清理较早的思维内容，仅保留最近一个思维轮次：
上下文缓存
Responses API 模式下默认开启会话缓存：系统自动存储初始上下文，并在每轮对话中动态更新，后续请求会将缓存内容与新输入合并后再送入模型。这对多轮对话、复杂工具调用等长上下文场景可显著降低重复 token 的开销。 缓存命中情况可通过返回事件的usage_metadata 查看，其中 cached_content_token_count 为命中缓存的 token 数，prompt_token_count 为输入总 token 数，缓存命中率即两者之比。