定義您的代理

代理是一種可重複使用、具版本控制的設定，用於定義角色與能力。它將模型、系統提示、工具、MCP 伺服器和技能整合在一起，這些元素決定了 Claude 在工作階段中的行為方式。

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

代理設定欄位

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

建立代理

以下範例定義了一個程式設計代理，它使用最新的 Claude Opus 模型，並可存取預建代理工具集。此工具集讓代理能夠撰寫程式碼、讀取檔案、搜尋網路等。如需支援工具的完整清單，請參閱代理工具參考。

範例使用 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": "medium" },
    "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 設定中，代理的固定設定以及 subagents 或 workflows 的 predefined_agents 清單中列出的每個代理的固定設定，必須全部設為相同的值或全部不設定；請參閱多代理協調。若之後要變更或清除固定設定，請更新代理的 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：

unconditional_agent = client.beta.agents.update(
    agent.id,
    description="Writes and reviews code.",
)

print(f"New version: {unconditional_agent.version}")

更新語意

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

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

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

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

• multiagent 在更新保留 multiagent_20261001 類型時，會逐層合併至已儲存的區塊。您省略的設定會保留其已儲存的值，而您傳送的 predefined_agents 清單會取代已儲存的清單。任何其他傳送 multiagent 的更新都會整體取代已儲存的區塊，而其省略的設定會採用預設值。傳入 multiagent=None 可清除整個區塊。在區塊內，null 會將設定重設為其預設值，因此將 workflows 設為 null 會開啟動態工作流程。請參閱開啟動態工作流程。

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

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

• 其他代理的 predefined_agents 清單不會被更新。 在 subagents 或 workflows 的 predefined_agents 清單中列出此代理的代理，會保留其建立時或上次更新傳送該清單時所固定的版本，即使參照省略了 version 也是如此。若要委派給新版本，請更新列出它的代理，使清單參照新版本。

以下更新會清除說明、從 metadata 中刪除 team 鍵，並將 workflows 設為 null，從而開啟動態工作流程：

ant apply code-reviewer.md

---
name: Code Reviewer
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
metadata:
  owner: docs
multiagent:
  type: multiagent_20261001
  workflows: null
---

You are a helpful coding agent.

代理生命週期

列出版本

擷取完整的版本歷史，以追蹤代理隨時間的變化。結果會分頁，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()}")

後續步驟