Create an agent - Qoder CN

POST /api/v1/cloud/agents Creates 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 (such as `"ultimate"`), or an Agent model object to configure `effort` or `context_window` at the same time. Use List models to query available values
`system`	string	No	System prompt, at most 100000 characters
`description`	string	No	Agent description, at most 2048 characters
`tools`	array of Agent tool	No	Tool configuration list, up to 128 entries
`mcp_servers`	array of MCP server	No	MCP server configuration list, up to 20 entries. Authentication is configured through Vaults
`skills`	array of Skill binding	No	Skill binding list, up to 20 entries
`metadata`	Metadata object	No	Custom metadata; defaults to `{}` when omitted
`multiagent`	Multiagent	No	Agents configuration. When set, an `agent_toolset_20260401` tool entry 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 the 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	Agent unique identifier with the `"agent_"` prefix
`name`	string	Agent name
`description`	string	Agent description
`model`	string \| object	Model identifier. See Agent model
`system`	string	System prompt
`tools`	array of Agent tool	Tool configuration list
`mcp_servers`	array of MCP server	MCP server configuration
`skills`	array of Skill binding	Skill binding list
`metadata`	Metadata object	Custom metadata
`multiagent`	Multiagent \| null	Agents configuration; `null` when not set
`version`	integer	Current version, starting at 1
`archived_at`	string\|null	Archive time (ISO 8601); `null` when not archived
`created_at`	string	Creation time (ISO 8601)
`updated_at`	string	Last update time (ISO 8601)

Error Codes

HTTP	type	Trigger
400	`invalid_request_error`	Missing required field `name`
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 supplied; use `model.effort` instead
400	`invalid_request_error`	`tools` exceeds the maximum of 128 entries
400	`invalid_request_error`	Invalid `mcp_servers` or `skills` configuration
400	`invalid_request_error`	`skills` exceeds the maximum of 20 entries
400	`invalid_request_error`	`multiagent.type` is not `"coordinator"`
400	`invalid_request_error`	`multiagent.agents` is empty or exceeds the maximum of 20 entries
400	`invalid_request_error`	`multiagent` is set but `tools` is missing `agent_toolset_20260401`
400	`invalid_request_error`	Agent ID referenced in `multiagent.agents` does not exist
401	`authentication_error`	PAT invalid or expired
403	`permission_error`	Not authorized 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"
  }
}

See Errors for the full error envelope.

​Request Headers

​Request Body

​Example Request

​Example Response