定義 Agent - AI Coding Assistant Lingma

Agent 是 Qoder Cloud Agents 的核心配置模板，描述了 AI 代理的能力邊界 —— 模型、行為指令、可用工具。一個 Agent 可被多個 Session 複用；修改 Agent 不影響已啟動並執行 Session。

核心要素

可以把 Agent 理解為一份”崗位說明書”：

要素	含義
模型	Agent 的智力水平
系統提示詞	Agent 的管理辦法
工具集	Agent 能執行的操作
Skills	Agent 可調用的進階技能

Agent 本身不執行任務，它只是配置。真正執行任務的是綁定該 Agent 的 Session。

欄位參考

欄位	類型	必填	說明
`id`	string	—	系統產生，`agent_` 首碼 + 32 字元十六進位（小寫）
`type`	string	—	固定為 `"agent"`
`name`	string	是	Agent 名稱，建議用英文虛線命名（≤ 64 字元）
`description`	string	否	描述資訊，預設 `""`
`model`	string	是	模型標識，詳見下文
`system`	string	否	系統提示詞，預設 `""`
`instructions`	string	否	追加在系統提示詞後的行為指令
`tools`	array	否	可用工具列表，詳見下文
`skills`	array	否	關聯的 Skill ID 列表
`mcp_servers`	array	否	MCP 伺服器配置列表，預設 `[]`
`default_environment`	string	否	該 Agent 的預設 Environment ID，預設 `""`
`metadata`	object	否	自訂索引值對，用於標記和篩選
`version`	integer	—	版本號碼，從 1 開始遞增
`archived`	boolean	—	是否已歸檔，預設 `false`
`archived_at`	string\|null	—	歸檔時間（ISO 8601），未歸檔時為 `null`
`created_at`	string	—	建立時間，ISO 8601 格式
`updated_at`	string	—	最後更新時間

model

model 為字串類型，指定 Agent 使用的模型：

值	說明
`"ultimate"`	最強模型，適合複雜推理和長任務
`"auto"`	自動選擇性價比最優的模型

tools

tools 是工具對象數組，當前僅支援單一對象 agent_toolset_20260401，通過 enabled_tools 數組按需開啟原子工具：

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

可用的 enabled_tools 值（首字母大寫）：

工具名	說明
`Bash`	執行 shell 命令
`Read`	讀取檔案內容
`Write`	建立或覆蓋檔案
`Edit`	局部編輯檔案
`Glob`	萬用字元列檔案
`Grep`	檔案內容搜尋
`WebFetch`	HTTP GET 單頁面
`WebSearch`	連網搜尋

更多工具配置參見 Agent 工具配置。

管理 Agent

完整的 CRUD 介面請參考 API Reference / Agents。下面是常用工作流程樣本。

建立

curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-reviewer",
    "model": "ultimate",
    "instructions": "你是代碼審查專家。逐行審查代碼並以 Markdown 輸出問題與改進建議。",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write"]
      }
    ],
    "metadata": {
      "team": "backend",
      "purpose": "code-review"
    }
  }' | jq .

成功返回 201 Created，version 從 1 開始。

查詢

# 擷取單個 Agent
curl -s https://api.qoder.com.cn/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_PAT"

# 分頁列表
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=20" \
  -H "Authorization: Bearer $QODER_PAT"

更新

更新 Agent 必須攜帶當前 version，詳見下文「版本管理」。

curl -s -X PUT https://api.qoder.com.cn/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-reviewer",
    "model": "ultimate",
    "instructions": "你是資深代碼審查專家，專註安全性漏洞和效能問題。",
    "version": 1
  }' | jq .

成功返回 200 OK，version 自動 +1。

刪除

curl -s -X DELETE https://api.qoder.com.cn/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_PAT"

刪除 Agent 不會終止已綁定該 Agent 的活躍 Session。Session 在建立時已快照了 Agent 配置。

版本管理

Agent 採用開放式並行存取控制（OCC）機制：

建立時 version 從 1 開始
每次成功更新，version 自動 +1
更新要求必須攜帶當前 version。兩種失敗情形：
- 缺少 version 欄位 — 返回 400 invalid_request_error（"Field 'version' is required."）
- version 存在但與服務端不一致 — 返回 409 conflict_error

這避免了多人 / 多系統並發修改時互相覆蓋。

處理 409 衝突

當持有的版本已到期時：

{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "Version conflict. Expected version 2, got 1."
  }
}

恢複步驟：

GET 最新 Agent 拿到當前 version
合并自己的變更
用新 version 重新 PUT

最佳實務

命名規範 — 用 團隊-用途 格式，如 backend-code-review、frontend-test-gen
提示詞精鍊 — system 欄位寫清角色、輸出格式、限制條件
最小工具集 — 只配置任務所需的工具，減少誤操作風險
善用 metadata — 用標籤分類管理，方便後續篩選和審計
生產環境鎖版本 — 建立 Session 時用 {"id": ..., "version": ...} 形式鎖定 Agent 版本，避免新版本影響線上行為

常見問題

Q：更新 Agent 後，正在啟動並執行 Session 會受影響嗎？不會。Session 在建立時綁定了 Agent 的特定版本，後續修改不影響已存在的 Session。Q：tools 數組為空白可以嗎？可以。不帶工具的 Agent 只能進行純文字對話，無法執行任何操作。Q：name 欄位有長度限制嗎？建議控制在 64 字元以內，使用小寫字母、數字和虛線。Q：如何復原到舊版本的 Agent？目前不支援自動復原。建議在更新前記錄舊配置，需要時手動 PUT 回舊配置（攜帶最新 version）。