定義您的代理

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

只需將代理建立一次作為可重複使用的資源，之後每次啟動工作階段時以 ID 參照它即可。代理具有版本控制，更易於在眾多工作階段之間管理。

代理設定欄位

您也可以針對單一工作階段覆寫 model、system、tools、mcp_servers 和 skills，而不變更代理本身。model 覆寫會完整取代代理的 model 物件，因此代理本身的 effort 不會被沿用。若要以特定 effort 等級執行工作階段，請在覆寫的 model 物件中設定 effort。請參閱為工作階段覆寫代理設定。

建立代理

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

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

ant apply coding-assistant.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful coding agent.

回應會回傳您的設定，並新增 id、type、version、created_at、updated_at 與 archived_at 欄位，同時以預設值填入您省略的 model 欄位，例如 effort。version 從 1 開始，每當更新變更了代理時便會遞增。

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-5-5",
    "effort": { "type": "high" },
    "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": [],
  "multiagent": null,
  "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，除非您另行設定，否則將套用此政策。

固定推論地理區域

與 speed 和 effort 相同，inference_geo 是透過 model 的物件形式設定的：以物件形式傳入 model，並在 id 旁設定 inference_geo。此欄位接受 "us" 或 "global"。未設定時，每個模型請求會遵循其被處理當下工作區的預設推論地理區域。請參閱資料駐留以了解工作區層級的地理區域控制與定價。

以下範例將代理程式固定為美國推論，並印出代理程式 model 物件中的 inference_geo 值：

ant apply geo-pinned-assistant.md

---
name: Geo-pinned assistant
model:
  id: claude-opus-5-5
  inference_geo: us
---

You are a helpful assistant.

inference_geo 固定值會在代理儲存時、從其建立工作階段時，以及工作階段處理的每一輪中，對照工作區的 allowed_inference_geos 進行驗證。如果工作區允許清單縮減，導致某個固定值不再被允許，則無法再從該代理建立新的工作階段，且執行中的工作階段會拒絕後續輪次；固定值永遠不會被豁免，因為工作區仰賴它們來達成合規與資料駐留。

在不支援地理推論固定的模型上設定 inference_geo 會回傳 400 錯誤；請參閱模型可用性以了解支援的模型。在 multiagent 設定中，協調者的固定值與每個名冊成員的固定值必須全部設為相同的值，或全部不設定；請參閱多代理協作編排。若要稍後變更或清除固定值，請更新代理的 model 物件；提供不含 inference_geo 的 model 會將其清除，如更新語意中所述。

更新代理

當設定變更時，更新代理會產生新版本。version 欄位為選填：提供它以進行樂觀並行控制（不相符時回傳 409），或省略它以無條件套用更新（最後寫入者勝出）。對已封存代理的更新會被拒絕。

使用 CLI 時，請編輯代理程式的檔案並再次執行 ant apply；apply 會為您提供 version。

ant apply coding-assistant.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful coding agent. Always write tests.

前述範例提供了來自建立回應的 version，因此只有在您讀取代理之後沒有其他操作變更過它時，更新才會套用。若要無條件套用更新，請在請求中省略 version：

updated_agent=$(curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "description": "Writes and reviews code."
  }')

echo "New version: $(jq -r '.version' <<< "$updated_agent")"

更新語意

• version 為選填，提供時必須至少為 1。提供時，若與代理目前的版本不相符，請求會回傳 409，即使您傳送的欄位已與儲存的值相符亦然；請重新讀取代理並重試。省略時，更新會無條件套用，且最近一次的更新會靜默取代任何並行的更新，雙方呼叫者都不會收到錯誤。對於互動式呼叫者，建議預設提供 version；而省略它則適合宣告式套用迴圈，例如同步已簽入之代理定義的 CI 作業，此時由該迴圈擁有代理。

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

• 純量欄位（model、system、name、description）會被新值取代。system 與 description 可透過傳入 null 清除。model 與 name 為必填，無法清除。在您提供的 model 物件中，effort 是唯一的例外：若模型 id 未變更，省略 effort 會讓儲存的 effort 等級維持不變。若您變更了模型 id，省略的 effort 會重設為新模型的預設值。其他 model 欄位會隨物件一併被取代：提供不含 inference_geo 的 model 會清除代理的推論地理區域固定值。

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

• multiagent 會整體被取代，包括其 agents 名冊。傳入 null 可將其清除。

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

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

• 協調者名冊不會被更新。 在其 multiagent.agents 名冊中參照此代理的協調者，會保留在協調者建立或上次更新時所固定的版本，即使該參照省略了 version 亦然。若要委派至新版本，請更新協調者，使其名冊參照新版本。

代理生命週期

列出版本

擷取完整的版本歷史，以追蹤代理隨時間的變更情形。結果會分頁，而 SDK 範例會自動擷取每一頁。

for version in client.beta.agents.versions.list(agent.id):
    print(f"Version {version.version}: {version.updated_at.isoformat()}")

封存代理

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

archived = client.beta.agents.archive(agent.id)

print(f"Archived at: {archived.archived_at.isoformat()}")

後續步驟