创建 Agent-Qoder CN 系列(Lingma)-阿里云帮助中心

创建一个新的 Agent 配置。

请求头

头部	必选	说明
`Authorization`	是	`Bearer <PAT>`
`Content-Type`	是	`application/json`
`Idempotency-Key`	否	幂等键，防止重复创建

请求体

字段	类型	必选	说明
`name`	string	是	Agent 名称，长度 1-256 字符
`model`	string/object	是	模型标识，可以是字符串（如 `"ultimate"`）或对象
`instructions`	string	否	系统提示词（System Prompt）
`description`	string	否	Agent 描述
`tools`	array	否	工具配置列表，元素结构见下方”`tools` 元素结构”。完整说明见 Agent 工具配置
`mcp_servers`	array	否	MCP 服务器配置列表，格式 `[{"name":"<name>","type":"http","url":"<mcp_server_url>"}]`。鉴权通过 Vault 配置
`skills`	array	否	Skill 绑定列表，格式 `[{"type":"custom","skill_id":"<skill_id>"}]`，最多 20 个
`metadata`	object	否	自定义元数据键值对

`tools` 元素结构

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

字段	类型	必选	说明
`type`	string	是	工具集类型标识符。当前可用值与最新版本见 Agent 工具配置。
`enabled_tools`	array	否	启用的原子工具白名单。省略或填空数组 `[]` 等同启用全部内置工具；填非空数组则严格按白名单限制，列表外的工具模型层完全不可见。详见 Agent 工具配置。

示例请求

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": "你是文档测试助手",
    "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"
      }
    ]
  }'

示例响应

HTTP 201 Created

{
  "type": "agent",
  "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "name": "doc-test-agent",
  "description": "",
  "model": "ultimate",
  "system": "你是文档测试助手",
  "instructions": "你是文档测试助手",
  "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"
}

响应字段

字段	类型	说明
`type`	string	固定值 `"agent"`
`id`	string	Agent 唯一标识，前缀 `"agent_"`
`name`	string	Agent 名称
`description`	string	Agent 描述
`model`	string	模型标识
`instructions`	string	系统提示词
`system`	string	`instructions` 的别名（已弃用，建议使用 `instructions`）
`tools`	array	工具配置列表
`mcp_servers`	array	MCP 服务器配置
`default_environment`	string	默认运行环境
`version`	integer	当前版本号，从 1 开始递增
`archived`	boolean	是否已归档
`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` 长度超过 256 字符
400	`invalid_request_error`	缺少必填字段 `model`
400	`invalid_request_error`	`mcp_servers` 或 `skills` 配置格式错误
400	`invalid_request_error`	`skills` 数量超过 20 个上限
401	`authentication_error`	PAT 无效或过期
403	`permission_error`	无权限执行此操作

错误响应示例：

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

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

请求头

请求体

tools 元素结构

示例请求

示例响应

响应字段

错误码

`tools` 元素结构