建立 Agent - - 阿里雲

建立一個新的 Agent 配置。

重要

Qoder CN 系列全新文檔網站現已上線。當前網站的文檔內容可能無法反映產品的最新功能與變化，請訪問 docs.qoder.cn擷取最新產品文檔。

POST /api/v1/cloud/agents

建立一個新的 Agent 配置。

要求標頭

頭部	必選	說明
`Authorization`	是	`Bearer <PAT>`
`Content-Type`	是	`application/json`
`Idempotency-Key`	否	等冪鍵，防止重複建立

請求體

欄位	類型	必選	說明
`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.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"
}

響應欄位

欄位	類型	說明
`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 不存在
401	`authentication_error`	PAT 無效或到期
403	`permission_error`	無許可權執行此操作

錯誤響應樣本：

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

完整錯誤信封說明詳見錯誤參考。