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

​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