Agent schemas

Agent object

Returned by create, list, update, archive, and GET /api/v1/cloud/agents/{agent_id} when version is omitted.

Field	Type	Description
`id`	string	Agent ID with the `agent_` prefix
`type`	string	Always `"agent"`
`name`	string	Agent name, 1-256 characters
`description`	string	Agent description, at most 2048 characters
`model`	string \| object	Model identifier. Pass a string for the model ID, or an Agent model object to also configure `effort` and `context_window`
`system`	string	System prompt, at most 100000 characters
`tools`	array of Agent tool	Tool configuration list, up to 128 entries. Defaults to `[]`
`mcp_servers`	array of MCP server	MCP server list, up to 20 entries. Defaults to `[]`
`skills`	array of Skill binding	Skill bindings, up to 20 entries. Defaults to `[]`
`metadata`	object	Metadata object. Defaults to `{}`
`multiagent`	Multiagent \| null	Agents configuration. Returned as `null` when not set
`version`	integer	Current Agent version, starting at `1`
`archived_at`	string \| null	Archive time in UTC, or `null` when not archived
`created_at`	string	Creation time in UTC
`updated_at`	string	Last update time in UTC

Agent version snapshot

Returned by GET /api/v1/cloud/agents/{agent_id} when version is provided, and by GET /api/v1/cloud/agents/{agent_id}/versions.

Field	Type	Description
`id`	string	Agent ID with the `agent_` prefix
`type`	string	Always `"agent"`
`name`	string	Agent name
`description`	string	Agent description
`model`	string \| object	Model identifier. Same shape as on the Agent object; see Agent model
`system`	string	System prompt
`tools`	array of Agent tool	Tool configuration list
`mcp_servers`	array of MCP server	MCP server list
`skills`	array of Skill binding	Skill bindings
`metadata`	object	Metadata object
`multiagent`	Multiagent \| null	Agents configuration
`version`	integer	Version number for this snapshot
`archived_at`	string \| null	Archive time in UTC, or `null` when not archived in the snapshot
`created_at`	string	Agent creation time in UTC
`updated_at`	string	Last update time for this snapshot in UTC

Agent model

The model field on an Agent accepts two equivalent shapes:

String shorthand: the model ID, for example "ultimate".
Object form: an object with id and optional tuning fields.

Field	Type	Required	Description
`id`	string	Yes	Model identifier. Use List models to discover available values
`effort`	string	No	Reasoning effort level. Valid values: `none`, `low`, `medium`, `high`, `xhigh`, `max`. See the model’s `efforts` array in List models for the levels a given model advertises
`context_window`	integer	No	Desired context window in tokens (positive integer). Choose from the model’s `available_context_windows` in List models

Responses echo whichever shape was submitted: string requests return model as a string, object requests return model as an object with the tuning fields preserved. Version snapshots (GET /api/v1/cloud/agents/{agent_id}?version=N) return the same shape. Session responses embed the Agent with an additional read-only effective_context_window inside agent.model; see Session schemas.

Agent tool

tools[] is a union distinguished by type.

Field	Type	Applies to	Description
`type`	string	All	Required. Valid values: `agent_toolset_20260401`, `mcp_toolset`, `custom`
`enabled_tools`	array of string	`agent_toolset_20260401`	Built-in tool allowlist. A non-empty array is a strict allowlist. Omit it or pass `[]` to use the default built-in toolset, with `disallowed_tools` and `configs[].enabled` still applied. Values must use one of the built-in tool names below
`disallowed_tools`	array of string	`agent_toolset_20260401`	Built-in tools to hide and deny. Values must use one of the built-in tool names below. A tool cannot appear in both `enabled_tools` and `disallowed_tools`
`configs`	array of Tool config	`agent_toolset_20260401`, `mcp_toolset`	Per-tool enablement and permission rules. This is where per-tool permissions are configured
`mcp_server_name`	string	`mcp_toolset`	Required. Must match one `mcp_servers[].name` value
`name`	string	`custom`	Required custom tool name. It must not collide with a built-in tool name and must not start with `mcp__`
`description`	string	`custom`	Required custom tool description
`input_schema`	object	`custom`	Required JSON Schema object. `input_schema.type` must be `"object"`

Custom tools do not support permission_policy; configure permissions through configs[].permission_policy on agent_toolset_20260401 or mcp_toolset entries.

Built-in tool names

Use these built-in tool names:

Tool name
`Bash`
`DeliverArtifacts`
`Edit`
`Glob`
`Grep`
`ImageGen`
`ImageSearch`
`Read`
`WebFetch`
`WebSearch`
`Write`

Tool config

Used in tools[].configs[].

Field	Type	Required	Description
`name`	string	Yes	Tool name to configure. For `agent_toolset_20260401`, use one built-in tool name. For `mcp_toolset`, use the raw tool name exposed by that MCP server
`enabled`	boolean	No	`false` hides and denies the named tool. `true` explicitly enables the named tool
`permission_policy`	Permission policy	No	Runtime permission behavior for this tool

Permission policy

Field	Type	Required	Description
`type`	string	Yes	Valid values: `always_allow`, `always_ask`, `always_deny`

always_allow executes without pausing, always_ask pauses for a user.tool_confirmation event, and always_deny returns a denied tool result.

MCP server

Used in mcp_servers[].

Field	Type	Required	Description
`name`	string	Yes	Unique MCP server name within this Agent
`type`	string	Yes	Supported value: `"url"`
`url`	string	Yes	Streamable HTTP MCP endpoint URL

Authentication for MCP servers is configured through Vaults.

Skill binding

Used in skills[].

Field	Type	Required	Description
`type`	string	Yes	Valid values: `qoder`, `custom`
`skill_id`	string	Yes	Skill identifier
`version`	string	No	Optional non-empty version string

Multiagent

Used in the Agent’s multiagent field to configure the Agents capability. When set, coordinator control tools (create_agent, send_to_agent, list_agents, Agent) are automatically injected at runtime.

When using multiagent, the tools array must include an agent_toolset_20260401 type entry.

Field	Type	Required	Description
`type`	string	Yes	Must be `"coordinator"`
`agents`	array of Multiagent agent entry	Yes	Roster of delegatable Agents, 1-20 unique entries

Multiagent agent entry

multiagent.agents[] supports three formats: Object format:

Field	Type	Required	Description
`type`	string	Yes	`"agent"` references another Agent; `"self"` references the coordinator itself
`id`	string	Conditional	Agent ID. Required when `type` is `"agent"`
`version`	integer	No	Specific Agent version. When omitted, uses the latest active version. Supports positive integers or positive integer strings
`name`	string	No	Display name for the child Agent

String shorthand: Pass an Agent ID string directly, equivalent to {"type": "agent", "id": "<value>"}. Example:

{
  "type": "coordinator",
  "agents": [
    {"type": "agent", "id": "agent_019f00000001", "name": "Research Agent"},
    {"type": "agent", "id": "agent_019f00000002", "version": 3},
    {"type": "self"},
    "agent_019f00000003"
  ]
}

Agent setup

Create a reusable, versioned agent configuration.

First steps

Define your agent

Configure agent environment

Delegate work to your agent

Manage agent context

Best Practices

API reference

Agent schemas

Agent object

Agent version snapshot

Agent model

Agent tool

Built-in tool names

Tool config

Permission policy

MCP server

Skill binding

Multiagent

Multiagent agent entry

Agent setup

​Agent object

​Agent version snapshot

​Agent model

​Agent tool

​Built-in tool names

​Tool config

​Permission policy

​MCP server

​Skill binding

​Multiagent

​Multiagent agent entry

​Related

Agent setup

Agent object

Agent version snapshot

Agent model

Agent tool

Built-in tool names

Tool config

Permission policy

MCP server

Skill binding

Multiagent

Multiagent agent entry

Related