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 | Multiagent orchestration 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 | Multiagent orchestration 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 |
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.
tools[] is a union distinguished by type.
| Field | Type | Applies to | Description |
|---|
type | string | All | Required. Valid values: agent_toolset_20260401, browser_toolset_20260714, 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.
Browser Use is currently in Beta, and its capabilities and API will continue to improve. See Browser Use (Beta) for the status notice and a complete enablement example.
To enable Browser Use for an Agent when creating or updating it:
- Add
x-qoder-beta: browser-use-2026-07-14 to the request headers.
- Add this entry to the
tools array in the request body:
{
"type": "browser_toolset_20260714"
}
browser_* tools and Session live preview for the Agent. It accepts only the type field and does not support selecting individual Browser tools through enabled_tools.
When updating an Agent, providing tools replaces its existing tool configuration. Include any tools you want to keep.
Use these built-in tool names:
| Tool name |
|---|
Bash |
DeliverArtifacts |
Edit |
Glob |
Grep |
ImageGen |
ImageSearch |
Read |
WebFetch |
WebSearch |
Write |
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 |
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 roster that a coordinator can delegate to. See Multiagent orchestration for the complete workflow.
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 Agents available for delegation, containing 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 |
{"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"
]
}
