> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent schemas
> Agent object, tool, MCP server, and skill binding structures.
## 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](#agent-model) object to also configure `effort` and `context_window` |
| `system` | string | System prompt, at most 100000 characters |
| `tools` | array of [Agent tool](#agent-tool) | Tool configuration list, up to 128 entries. Defaults to `[]` |
| `mcp_servers` | array of [MCP server](#mcp-server) | MCP server list, up to 20 entries. Defaults to `[]` |
| `skills` | array of [Skill binding](#skill-binding) | Skill bindings, up to 20 entries. Defaults to `[]` |
| `metadata` | object | [Metadata object](/cloud-agents/api/conventions/schemas#metadata-object). Defaults to `{}` |
| `multiagent` | [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](#agent-object); see [Agent model](#agent-model) |
| `system` | string | System prompt |
| `tools` | array of [Agent tool](#agent-tool) | Tool configuration list |
| `mcp_servers` | array of [MCP server](#mcp-server) | MCP server list |
| `skills` | array of [Skill binding](#skill-binding) | Skill bindings |
| `metadata` | object | [Metadata object](/cloud-agents/api/conventions/schemas#metadata-object) |
| `multiagent` | [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](/cloud-agents/api/models/list) 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](/cloud-agents/api/models/list) 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](/cloud-agents/api/models/list) |
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](/cloud-agents/api/sessions/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](#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](#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](/cloud-agents/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](#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": ""}`.
Example:
```json theme={null}
{
"type": "coordinator",
"agents": [
{"type": "agent", "id": "agent_019f00000001", "name": "Research Agent"},
{"type": "agent", "id": "agent_019f00000002", "version": 3},
{"type": "self"},
"agent_019f00000003"
]
}
```
## Related
Create a reusable, versioned agent configuration.