创建一个新的 Agent 配置。
Qoder CN 系列全新文档站点现已上线。当前站点的文档内容可能无法反映产品的最新功能与变化,请访问 docs.qoder.cn获取最新产品文档。
POST /api/v1/cloud/agents
创建一个新的 Agent 配置。
请求头
|
头部 |
必选 |
说明 |
|
|
是 |
|
|
|
是 |
|
|
|
否 |
幂等键,防止重复创建 |
请求体
|
字段 |
类型 |
必选 |
说明 |
|
|
string |
是 |
Agent 名称,长度 1-256 字符 |
|
|
string | object |
是 |
模型标识。可传 string(如 |
|
|
string |
否 |
系统提示词(System Prompt),最长 100000 字符 |
|
|
string |
否 |
Agent 描述,最长 2048 字符 |
|
|
Agent tool 数组 |
否 |
工具配置列表,最多 128 个 |
|
|
MCP server 数组 |
否 |
MCP 服务器配置列表,最多 20 个。鉴权通过 Vault 配置 |
|
|
Skill binding 数组 |
否 |
Skill 绑定列表,最多 20 个 |
|
|
Metadata 对象 |
否 |
自定义元数据,省略时为 |
|
|
Multiagent |
否 |
Agents 配置。设置后需同时配置 |
示例请求
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": "你是文档测试助手",
"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"
}
]
}'
如需配置 reasoning effort 或上下文窗口,将 model 以对象形式传入:
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": "你是文档测试助手"
}'
示例响应
HTTP 200 OK
{
"type": "agent",
"id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"name": "doc-test-agent",
"description": "",
"model": "ultimate",
"system": "你是文档测试助手",
"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"
}
响应字段
|
字段 |
类型 |
说明 |
|
|
string |
固定值 |
|
|
string |
Agent 唯一标识,前缀 |
|
|
string |
Agent 名称 |
|
|
string |
Agent 描述 |
|
|
string | object |
模型标识,详见 Agent model |
|
|
string |
系统提示词 |
|
|
Agent tool 数组 |
工具配置列表 |
|
|
MCP server 数组 |
MCP 服务器配置 |
|
|
Skill binding 数组 |
Skill 绑定列表 |
|
|
Metadata 对象 |
自定义元数据 |
|
|
Multiagent | null |
Agents 配置,未设置时为 |
|
|
integer |
当前版本号,从 1 开始递增 |
|
|
string|null |
归档时间(ISO 8601),未归档时为 |
|
|
string |
创建时间(ISO 8601) |
|
|
string |
最后更新时间(ISO 8601) |
错误码
|
HTTP |
type |
触发条件 |
|
400 |
|
缺少必填字段 |
|
400 |
|
|
|
400 |
|
|
|
400 |
|
缺少必填字段 |
|
400 |
|
|
|
400 |
|
|
|
400 |
|
传入了 |
|
400 |
|
|
|
400 |
|
|
|
400 |
|
|
|
400 |
|
|
|
400 |
|
|
|
400 |
|
设置 |
|
400 |
|
|
|
401 |
|
PAT 无效或过期 |
|
403 |
|
无权限执行此操作 |
错误响应示例:
{
"type": "error",
"request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
"error": {
"type": "invalid_request_error",
"message": "name must be between 1 and 256 characters"
}
}
完整错误信封说明详见 错误参考。