Agent object
Returned by create, list, update, archive, andGET /v1/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 | Model identifier. Requests and responses use a string value |
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 {} |
version | integer | Current Agent version, starting at 1 |
archived | boolean | Whether the Agent is archived |
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 byGET /v1/agents/{agent_id} when version is provided, and by GET /v1/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 | Model identifier |
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 |
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 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" |
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 intools[].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 inmcp_servers[].
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Unique MCP server name within this Agent |
type | string | Yes | Supported value: "http" |
url | string | Yes | Streamable HTTP MCP endpoint URL |
Skill binding
Used inskills[].
| 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 |
Related
Agent setup
Create a reusable, versioned agent configuration.