创建 Agent

创建一个新的 Agent 配置。

POST /api/v1/cloud/agents

创建一个新的 Agent 配置。

​

请求头

头部	必选	说明
Authorization	是	Bearer <PAT>
Content-Type	是	application/json
Idempotency-Key	否	幂等键，防止重复创建
x-qoder-beta	使用 Browser Use 时	当 tools 中配置了 browser_toolset_20260714 时，请求头 x-qoder-beta 必须包含 browser-use-2026-07-14。详见 Browser Use（Beta）

​

请求体

字段	类型	必选	说明
name	string	是	Agent 名称，长度 1-256 字符
model	string | object	是	模型标识。可传 string（如 "ultimate"），或传 Agent model 对象以同时配置 effort 或 context_window。可通过 列出模型 查询可用值
system	string	否	系统提示词（System Prompt），最长 100000 字符
description	string	否	Agent 描述，最长 2048 字符
tools	Agent tool 数组	否	工具配置列表，最多 128 个
mcp_servers	MCP server 数组	否	MCP 服务器配置列表，最多 20 个。鉴权通过 Vault 配置
skills	Skill binding 数组	否	Skill 绑定列表，最多 20 个
metadata	Metadata 对象	否	自定义元数据，省略时为 {}
multiagent	Multiagent	否	Agents 配置。设置后需同时配置 agent_toolset_20260401 工具

​

示例请求

curl -X POST "https://api.qoder.com/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/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"
}

​

响应字段

字段	类型	说明
type	string	固定值 "agent"
id	string	Agent 唯一标识，前缀 "agent_"
name	string	Agent 名称
description	string	Agent 描述
model	string | object	模型标识，详见 Agent model
system	string	系统提示词
tools	Agent tool 数组	工具配置列表
mcp_servers	MCP server 数组	MCP 服务器配置
skills	Skill binding 数组	Skill 绑定列表
metadata	Metadata 对象	自定义元数据
multiagent	Multiagent | null	Agents 配置，未设置时为 null
version	integer	当前版本号，从 1 开始递增
archived_at	string|null	归档时间（ISO 8601），未归档时为 null
created_at	string	创建时间（ISO 8601）
updated_at	string	最后更新时间（ISO 8601）

​

错误码

HTTP	type	触发条件
400	invalid_request_error	缺少必填字段 name
400	invalid_request_error	name 不是字符串；错误消息为 Field 'name' must be a string.
400	invalid_request_error	name 长度超过 256 字符
400	invalid_request_error	缺少必填字段 model
400	invalid_request_error	model.effort 不在 none、low、medium、high、xhigh、max 之内
400	invalid_request_error	model.context_window 不是正整数
400	invalid_request_error	传入了 model.speed，请改用 model.effort
400	invalid_request_error	tools 数量超过 128 个上限
400	invalid_request_error	mcp_servers 或 skills 配置格式错误
400	invalid_request_error	skills 数量超过 20 个上限
400	invalid_request_error	multiagent.type 不是 "coordinator"
400	invalid_request_error	multiagent.agents 为空或超过 20 个上限
400	invalid_request_error	设置 multiagent 但 tools 缺少 agent_toolset_20260401
400	invalid_request_error	multiagent.agents 中引用的 Agent ID 不存在
400	invalid_request_error	使用 browser_toolset_20260714 但未携带 Browser Use Beta 请求头
401	authentication_error	PAT 无效或过期
403	permission_error	无权限执行此操作
503	feature_not_available	Browser Use 暂时不可用

错误响应示例：

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

完整错误信封说明详见 错误参考。

​

相关

定义 Agent

创建可复用、可版本化的 Agent 配置。