All Products
Search
Document Center

:Create an agent

Last Updated:Oct 16, 2026

Create a new Agent configuration.

Important

The new Qoder CN documentation site is now available. Content on this site may not reflect the latest product features and changes. Visit docs.qoder.cn for the latest product documentation.

POST /api/v1/cloud/agents

Create a new Agent configuration.

Request headers

Header

Required

Description

Authorization

Yes

Bearer <PAT>

Content-Type

Yes

application/json

Idempotency-Key

No

Idempotency key to prevent duplicate creation

Request body

Field

Type

Required

Description

name

string

Yes

Agent name, 1-256 characters

model

string | object

Yes

Model identifier. Pass a string (e.g. "ultimate"), or pass an Agent model object to also configure effort or context_window. Query available values via List models

system

string

No

System prompt, up to 100000 characters

description

string

No

Agent description, up to 2048 characters

tools

Agent tool array

No

Tool configuration list, up to 128 items

mcp_servers

MCP server array

No

MCP server configuration list, up to 20 items. Authentication is configured via Vault

skills

Skill binding array

No

Skill binding list, up to 20 items

metadata

Metadata object

No

Custom metadata. Defaults to {} when omitted

multiagent

Multiagent

No

Multi-agent configuration. When set, the agent_toolset_20260401 tool must also be configured

Example request

curl -X POST "https://api.qoder.com.cn/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "doc-test-agent",
    "model": "ultimate",
    "system": "You are a documentation testing assistant",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
      }
    ],
    "mcp_servers": [
      {
        "type": "url",
        "name": "weather-service",
        "url": "https://mcp.example.com/mcp"
      }
    ]
  }'

To configure reasoning effort or context window, pass model as an object:

curl -X POST "https://api.qoder.com.cn/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "doc-test-agent-tuned",
    "model": {
      "id": "ultimate",
      "effort": "high",
      "context_window": 400000
    },
    "system": "You are a documentation testing assistant"
  }'

Example response

HTTP 200 OK

{
  "type": "agent",
  "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "name": "doc-test-agent",
  "description": "",
  "model": "ultimate",
  "system": "You are a documentation testing assistant",
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
    }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "name": "weather-service",
      "url": "https://mcp.example.com/mcp"
    }
  ],
  "skills": [],
  "metadata": {},
  "multiagent": null,
  "version": 1,
  "archived_at": null,
  "created_at": "2026-05-18T15:26:39.61669Z",
  "updated_at": "2026-05-18T15:26:39.61669Z"
}

Response fields

Field

Type

Description

type

string

Fixed value "agent"

id

string

Unique Agent identifier, prefixed with "agent_"

name

string

Agent name

description

string

Agent description

model

string | object

Model identifier. See Agent model for details

system

string

System prompt

tools

Agent tool array

Tool configuration list

mcp_servers

MCP server array

MCP server configuration

skills

Skill binding array

Skill binding list

metadata

Metadata object

Custom metadata

multiagent

Multiagent | null

Multi-agent configuration. null when not set

version

integer

Current version number, starts at 1 and increments

archived_at

string|null

Archive timestamp (ISO 8601). null when not archived

created_at

string

Creation timestamp (ISO 8601)

updated_at

string

Last updated timestamp (ISO 8601)

Errors

HTTP

type

Condition

400

invalid_request_error

Missing required field name

400

invalid_request_error

name is not a string; the error message is Field 'name' must be a string.

400

invalid_request_error

name exceeds 256 characters

400

invalid_request_error

Missing required field model

400

invalid_request_error

model.effort is not one of none, low, medium, high, xhigh, max

400

invalid_request_error

model.context_window is not a positive integer

400

invalid_request_error

model.speed was provided; use model.effort instead

400

invalid_request_error

tools exceeds the 128-item limit

400

invalid_request_error

mcp_servers or skills configuration format is invalid

400

invalid_request_error

skills exceeds the 20-item limit

400

invalid_request_error

multiagent.type is not "coordinator"

400

invalid_request_error

multiagent.agents is empty or exceeds the 20-item limit

400

invalid_request_error

multiagent is set but tools is missing agent_toolset_20260401

400

invalid_request_error

An Agent ID referenced in multiagent.agents does not exist

401

authentication_error

PAT is invalid or expired

403

permission_error

Insufficient permissions for this operation

Error response example:

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "invalid_request_error",
    "message": "name must be between 1 and 256 characters"
  }
}

For the full error envelope specification, see Errors.