AI Coding Assistant 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"
  }
}

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