Create an agent

Tools to attach, one binding object per tool — the only attachment field. An entry is either a reference ({ "tool_id": … }) or an inline definition ({ "tool": … }). See Tool Bindings.

Conditions that end the agent's work early, on top of max_steps. Two scopes:

{"type": "has_tool_call", "tool_name": "<resolved tool name>"} ends the turn after the step that calls the named tool. It narrows when the loop ends — it never lets it run past max_steps.

{"type": "max_chain_generations", "max_generations": <n>} bounds the continuation chain instead: once the chain has spawned that many generations, further resumptions stop with chain_limit rather than extending it. It never shortens a turn. The effective ceiling is the smaller of this and the deployment's MAX_CONTINUATION_CHAIN_GENERATIONS, so an agent can be stricter than the platform but never looser.

An unknown type, a has_tool_call without a tool_name, a max_chain_generations whose max_generations is not a positive integer, or a non-object entry is rejected with 400.

Per-step overrides of tool_choice and active_tool_ids, numbered from the first step of the turn. See Step Rules.

Restricts which runtime actions the agent may invoke. Evaluated as the intersection with the caller's own policy, so it can only narrow.

Knowledge search run before every generation; its matches are prepended as reference context. See Knowledge Config.

Prompt caching for this agent's turns. {"enabled": true} marks two cache breakpoints: the end of the system block, which covers the tool definitions and the instructions, and the last message of each step, which covers the conversation so far. A provider that caches by explicit breakpoint then reads, on every later step and every later turn of the session, the whole prefix the previous one sent, and writes only what was appended. Null or omitted is off: a cache write costs more than an uncached token, so an agent whose prefix is never re-read would pay for the privilege. A prefix below the model's minimum cacheable length is not cached. Cache reads are reported as cached_tokens and cache writes as cache_write_tokens on usage; a write with no cache_write_tokens price bills at the input rate.

How much the model reasons before answering. Translated per provider (Anthropic thinking, Gemini thinking config, OpenAI reasoning effort) against what the model supports; a model that cannot reason ignores it. none turns reasoning off where the model allows it. Reasoning tokens are metered as output. Null leaves the model's default.

Tools attached to this agent, one binding object per tool — the canonical attachment field. See Tool Bindings.

Knowledge retrieval config injected before every generation

Prompt caching for this agent's turns. {"enabled": true} marks two cache breakpoints: the end of the system block, which covers the tool definitions and the instructions, and the last message of each step, which covers the conversation so far. A provider that caches by explicit breakpoint then reads, on every later step and every later turn of the session, the whole prefix the previous one sent, and writes only what was appended. Null or omitted is off: a cache write costs more than an uncached token, so an agent whose prefix is never re-read would pay for the privilege. A prefix below the model's minimum cacheable length is not cached. Cache reads are reported as cached_tokens and cache writes as cache_write_tokens on usage; a write with no cache_write_tokens price bills at the input rate.

How much the model reasons before answering. Translated per provider (Anthropic thinking, Gemini thinking config, OpenAI reasoning effort) against what the model supports; a model that cannot reason ignores it. none turns reasoning off where the model allows it. Reasoning tokens are metered as output. Null leaves the model's default.

A staged rollout splitting traffic between two archived versions. See Versioning and Staged Rollout.