> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Model

By default an agent uses the globally configured model — the one set via
environment variables or `config.yaml` (see the [Quickstart](/productions/veadk/archives/1.0.1/en/get-started/quickstart)).
You can also set a model per agent when you create it.

In a Volcengine environment, version 1.0.1 defaults to `doubao-seed-1-8-251228` with provider `openai` and endpoint `https://ark.cn-beijing.volces.com/api/v3/`. When `CLOUD_PROVIDER=byteplus`, it defaults to `seed-1-6-250915` at `https://ark.ap-southeast.bytepluses.com/api/v3`.

## Set the model for a single agent

Override the global default with `model_name` and `model_provider`:

```python lines theme={null}
from veadk import Agent

agent = Agent(
    model_name="doubao-seed-1-8-251228",
    model_provider="openai",
)
```

When omitted, `model_provider`, `model_api_base`, and `model_api_key` fall back
to the global configuration.

## Configure fallback models

`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.

```python lines theme={null}
agent = Agent(
    model_name=["doubao-seed-1-8-251228", "deepseek-r1-250528"],
)
```

<Note>
  In VeADK 1.0.1, model fallback applies only to the default model API. When the Responses API is enabled, pass a single string to `model_name`.
</Note>

## 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:

```python lines theme={null}
from veadk import Agent

agent = Agent(enable_responses=True)
```

Enabling the Responses API requires `google-adk>=1.21.0`, and the model must
support the interface (doubao models after version 0615 support it by default).

### Multimodal input

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:

```python lines theme={null}
import os
from google.genai import types
from google.genai.types import FileData

local_path = os.path.abspath("example.png")
message = types.UserContent(
    parts=[
        types.Part(text="Describe this image."),
        types.Part(
            file_data=FileData(
                file_uri=f"file://{local_path}",
                mime_type="image/png",
            )
        ),
    ],
)
```

For video, `FileData` may include `video_metadata` with `fps` to control the
frame-sampling rate (default 1, adjustable between 0.2 and 5).

### 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.

<Warning>
  When the agent sets `output_schema`, that field conflicts with the caching
  mechanism, so VeADK automatically disables context caching.
</Warning>