Create an agent - - Alibaba Cloud Documentation Center

Create a new agent configuration.

Request headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT>`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Idempotency key that prevents duplicate creation.

Request body

Field	Type	Required	Description
`name`	string	Yes	Agent name, 1-256 characters.
`model`	string\|object	Yes	Model identifier. Either a string such as `"ultimate"`, or an object.
`instructions`	string	No	System prompt.
`description`	string	No	Agent description.
`tools`	array	No	Tool configuration list. See the `tools` element structure below.
`mcp_servers`	array	No	MCP server configuration list, in the form `[{"name":"[name]","type":"http","url":"[mcp_server_url]"}]`. Authentication is configured through Vault.
`skills`	array	No	Skill bindings, in the form `[{"type":"custom","skill_id":"[skill_id]"}]`. Up to 20 entries.
`metadata`	object	No	Custom metadata key-value pairs.

`tools` element structure

{
  "type": "agent_toolset_20260401",
  "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
}

Field	Type	Required	Description
`type`	string	Yes	Toolset type identifier.
`enabled_tools`	array	No	Allowlist of atomic tools to enable. Omitting the field or passing an empty array `[]` enables all built-in tools. A non-empty array acts as a strict allowlist; tools outside the list are not visible to the model.

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",
    "instructions": "You are a documentation test 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/sse"
      }
    ]
  }'

Example response

HTTP 201 Created

{
  "type": "agent",
  "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "name": "doc-test-agent",
  "description": "",
  "model": "ultimate",
  "system": "You are a documentation test assistant.",
  "instructions": "You are a documentation test 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/sse"
    }
  ],
  "default_environment": "",
  "version": 1,
  "archived": false,
  "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	Always `"agent"`.
`id`	string	Unique agent identifier, prefixed with `"agent_"`.
`name`	string	Agent name.
`description`	string	Agent description.
`model`	string	Model identifier.
`instructions`	string	System prompt.
`system`	string	Alias of `instructions` (deprecated; use `instructions` instead).
`tools`	array	Tool configuration list.
`mcp_servers`	array	MCP server configuration.
`default_environment`	string	Default runtime environment.
`version`	integer	Current version number, starting at 1.
`archived`	boolean	Whether the agent is archived.
`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).

Errors

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`	`mcp_servers` or `skills` configuration is malformed.
400	`invalid_request_error`	`skills` exceeds the maximum of 20 entries.
401	`authentication_error`	PAT is invalid or has expired.
403	`permission_error`	Caller is not authorized for this operation.

Error response example:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "name must be between 1 and 256 characters"
  }
}

For the full error envelope, see Errors.

Request headers

Request body

tools element structure

Example request

Example response

Response fields

Errors

`tools` element structure