定義您的代理程式

代理程式（agent）是一種可重複使用且具版本控制的配置，用於定義角色與能力。它將模型、系統提示、工具、MCP 伺服器和技能打包在一起，以塑造 Claude 在工作階段期間的行為方式。

只需建立一次代理程式作為可重複使用的資源，之後每次啟動工作階段時透過 ID 引用它即可。代理程式具有版本控制，更易於在多個工作階段中管理。



代理程式配置欄位

您也可以針對單一工作階段覆寫 model、system、tools、mcp_servers 和 skills，而無需變更代理程式本身。請參閱為工作階段覆寫代理程式配置。



建立代理程式

以下範例定義了一個使用 Claude Opus 4.8 並可存取預建代理程式工具集的程式碼編寫代理程式。該工具集讓代理程式能夠編寫程式碼、讀取檔案、搜尋網路等。請參閱代理程式工具參考以取得支援工具的完整清單。

這些範例使用 curl、ant CLI 或其中一個 SDK。如果您尚未設定，快速入門涵蓋了安裝和用戶端設定。

agent=$(ant beta:agents create \
  --name "Coding Assistant" \
  --model '{id: claude-opus-4-8}' \
  --system "You are a helpful coding agent." \
  --tool '{type: agent_toolset_20260401}' \
  --format json)

AGENT_ID=$(jq -r '.id' <<< "$agent")
AGENT_VERSION=$(jq -r '.version' <<< "$agent")

回應會回傳您的配置，並新增 id、type、version、created_at、updated_at 和 archived_at 欄位。version 從 1 開始，每次更新變更代理程式時遞增。

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-4-8",
    "speed": "standard"
  },
  "system": "You are a helpful coding agent.",
  "description": null,
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "default_config": {
        "permission_policy": { "type": "always_allow" }
      }
    }
  ],
  "skills": [],
  "mcp_servers": [],
  "metadata": {},
  "version": 1,
  "created_at": "2026-04-03T18:24:10.412Z",
  "updated_at": "2026-04-03T18:24:10.412Z",
  "archived_at": null
}

工具集上的 default_config 顯示其預設的權限政策 always_allow，除非您另行配置，否則將套用此政策。



更新代理程式

當配置變更時，更新代理程式會產生新版本。version 欄位為必填，且必須與代理程式的目前版本相符，以確保您始終從已知狀態進行更新。版本不符會回傳 409 錯誤，且對已封存代理程式的更新會被拒絕。

ant beta:agents update \
  --agent-id "$AGENT_ID" \
  --version "$AGENT_VERSION" \
  --system "You are a helpful coding agent. Always write tests."



更新語意

• 省略的欄位會被保留。 您只需包含想要變更的欄位。

• 純量欄位（model、system、name、description）會被新值取代。system 和 description 可透過傳遞 null 來清除。model 和 name 為必填欄位，無法清除。

• 陣列欄位（tools、mcp_servers、skills）會被新陣列完全取代。若要完全清除陣列欄位，請傳遞 null 或空陣列。

• multiagent 會作為整體被取代，包括其 agents 名單。傳遞 null 可將其清除。

• Metadata 會在鍵層級進行合併。您提供的鍵會被新增或更新。您省略的鍵會被保留。若要刪除特定鍵，請將其值設為 null。

• 無操作偵測。 如果更新相對於目前版本沒有產生任何變更，則不會建立新版本，並回傳現有版本。

• 協調者名單不會被更新。 在其 multiagent.agents 名單中引用此代理程式的協調者，會保留在協調者建立或上次更新時所固定的版本，即使該引用省略了 version 也是如此。若要委派給新版本，請更新協調者，使其名單引用新版本。



代理程式生命週期



列出版本

擷取完整的版本歷史記錄，以追蹤代理程式隨時間的變更。結果會分頁顯示，SDK 範例會自動擷取每一頁。

ant beta:agents:versions list --agent-id "$AGENT_ID"



封存代理程式

封存會使代理程式變為唯讀，且無法復原。現有的工作階段會繼續執行，但新的工作階段無法引用該代理程式。回應會將 archived_at 設為封存時間戳記。

ant beta:agents archive --agent-id "$AGENT_ID"



後續步驟