By default an agent uses the globally configured model — the one set via
environment variables or config.yaml (see the Quickstart).
VeADK uses doubao-seed-2-1-pro-260628 as the default inference model.
You can also set a model per agent when you create it.
Set the model for a single agent
Override the global default with model_name and model_provider:
When omitted, model_provider, model_api_base, and model_api_key fall back
to the global configuration.
Resolve an API key by name
In addition to setting MODEL_AGENT_API_KEY directly, set
MODEL_AGENT_API_KEY_NAME to resolve an Ark API key by name. An explicit key
always takes precedence:
You can also pass model_api_key_name to Agent. This capability is available
in VeADK 1.0.2 and later.
model_name also accepts a list: the first entry is the primary model and the
rest are fallbacks, tried in order when the primary model is unavailable.
Fallbacks apply to both the default model interface and the Responses API when
enable_responses=True.
Responses API
The Responses API is a Volcengine Ark interface with native, efficient context
management, a simpler I/O format, and stronger tool-calling and multimodal
capabilities. Once enabled in VeADK, every turn of the agent’s conversation goes
through this interface, giving it native context caching and image, video, and
document understanding.
Enable
Set enable_responses=True when creating the agent:
Enabling the Responses API requires google-adk>=1.34.0, and the model must
support the interface (doubao models after version 0615 support it by default).
Beyond text, the Responses API understands images, video, and documents. Pass
multimodal data with google.genai.types.FileData; file_uri accepts three
sources:
- Local file path:
file://{local_path} — uploaded automatically via the Files API.
- Files API resource:
file_id://{file_id} — for already-uploaded files.
- Web URL: a plain
https:// link, typed by its mime_type.
For a local image:
For video, FileData may include video_metadata with fps to control the
frame-sampling rate (default 1, adjustable between 0.2 and 5).
Configure Ark context management
When the Responses API is enabled, pass Ark-supported context_management
settings through model_extra_config. This example clears older thinking
content and keeps the most recent thinking turn:
Context caching
In Responses API mode, session caching is on by default: the initial context is
stored and updated each turn, and later requests merge the cached content with
the new input before calling the model. This significantly reduces repeated-token
cost in long-context scenarios such as multi-turn conversations and complex tool
calls.
Cache hits are visible in the returned event’s usage_metadata, where
cached_content_token_count is the number of tokens served from cache and
prompt_token_count is the total input tokens; the hit rate is their ratio.
When the agent sets output_schema, that field conflicts with the caching
mechanism, so VeADK automatically disables context caching.
