智能体默认使用全局配置的模型，即通过环境变量或 config.yaml 设置的模型（参见快速开始）。也可以在创建智能体时为其单独指定模型。
为单个智能体指定模型
通过 model_name 与 model_provider 覆盖全局默认模型：
未显式传入时，model_provider、model_api_base、model_api_key 均沿用全局配置。
按名称选择火山方舟 API Key
当同一账号下配置了多个火山方舟 API Key 时，可通过 MODEL_AGENT_API_KEY_NAME 指定要使用的 Key 名称。VeADK 会在运行时按名称获取对应的 Key 值，无需把密钥写入配置文件。
也可以为单个智能体设置 model_api_key_name：
密钥的选择优先级如下：
Agent(model_api_key=...) 显式传入的 Key 值；MODEL_AGENT_API_KEY 环境变量；Agent(model_api_key_name=...) 或 MODEL_AGENT_API_KEY_NAME 指定的 Key 名称；- 当前账号下可用的默认火山方舟 API Key。
配置回退模型
model_name 也接受一个列表：第一个为主模型，其余作为回退模型；当主模型不可用时，依次尝试后续模型。
Responses API
Responses API 是火山方舟推出的接口，原生支持高效的上下文管理，输入输出格式更简洁，并具备更强的工具调用与多模态能力。在 VeADK 中启用后，智能体的每一轮对话都会经由该接口，从而获得原生的上下文缓存与图片、视频、文档理解能力。
在创建智能体时设置 enable_responses=True：
启用 Responses API 要求 google-adk>=1.21.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 模式下默认开启会话缓存：系统自动存储初始上下文，并在每轮对话中动态更新，后续请求会将缓存内容与新输入合并后再送入模型。这对多轮对话、复杂工具调用等长上下文场景可显著降低重复 token 的开销。
缓存命中情况可通过返回事件的 usage_metadata 查看，其中 cached_content_token_count 为命中缓存的 token 数，prompt_token_count 为输入总 token 数，缓存命中率即两者之比。
当智能体设置了 output_schema 时，该字段与缓存机制冲突，VeADK 会自动关闭上下文缓存。
