Create a new Agent configuration.
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 |
| Yes |
|
| Yes |
|
| No | Idempotency key to prevent duplicate creation |
Request body
Field | Type | Required | Description |
| string | Yes | Agent name, 1-256 characters |
| string | object | Yes | Model identifier. Pass a string (e.g. |
| string | No | System prompt, up to 100000 characters |
| string | No | Agent description, up to 2048 characters |
| Agent tool array | No | Tool configuration list, up to 128 items |
| MCP server array | No | MCP server configuration list, up to 20 items. Authentication is configured via Vault |
| Skill binding array | No | Skill binding list, up to 20 items |
| Metadata object | No | Custom metadata. Defaults to |
| Multiagent | No | Multi-agent configuration. When set, the |
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 |
| string | Fixed value |
| string | Unique Agent identifier, prefixed with |
| string | Agent name |
| string | Agent description |
| string | object | Model identifier. See Agent model for details |
| string | System prompt |
| Agent tool array | Tool configuration list |
| MCP server array | MCP server configuration |
| Skill binding array | Skill binding list |
| Metadata object | Custom metadata |
| Multiagent | null | Multi-agent configuration. |
| integer | Current version number, starts at 1 and increments |
| string|null | Archive timestamp (ISO 8601). |
| string | Creation timestamp (ISO 8601) |
| string | Last updated timestamp (ISO 8601) |
Errors
HTTP | type | Condition |
400 |
| Missing required field |
400 |
|
|
400 |
|
|
400 |
| Missing required field |
400 |
|
|
400 |
|
|
400 |
|
|
400 |
|
|
400 |
|
|
400 |
|
|
400 |
|
|
400 |
|
|
400 |
|
|
400 |
| An Agent ID referenced in |
401 |
| PAT is invalid or expired |
403 |
| 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.