定義您的 Agent

Agent 是一種可重複使用、具版本控制的配置，用於定義角色與能力。它將模型、系統提示、工具、MCP 伺服器和技能整合在一起，塑造 Claude 在工作階段中的行為方式。

只需建立一次 Agent 作為可重複使用的資源，並在每次開始工作階段時透過 ID 引用它。Agent 具有版本控制功能，更易於跨多個工作階段進行管理。

所有 Managed Agents API 請求都需要 managed-agents-2026-04-01 beta 標頭。SDK 會自動設定 beta 標頭。

Agent 配置欄位

欄位	說明
`name`	必填。Agent 的人類可讀名稱。
`model`	必填。驅動 Agent 的 Claude 模型。支援所有 Claude 4.5 及更新版本的模型。
`system`	定義 Agent 行為和角色的系統提示。系統提示與使用者訊息不同，使用者訊息應描述需要完成的工作。
`tools`	Agent 可用的工具。結合了預建 Agent 工具、MCP 工具和自訂工具。
`mcp_servers`	提供標準化第三方功能的 MCP 伺服器。
`skills`	透過漸進式揭露提供特定領域情境的技能。
`callable_agents`	此 Agent 可呼叫的其他 Agent，用於多 Agent 協作。這是研究預覽功能；申請存取權限以試用。
`description`	Agent 功能的說明。
`metadata`	用於自訂追蹤的任意鍵值對。

建立 Agent

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

若要搭配快速模式使用 Claude Opus 4.6，請將 model 作為物件傳入：{"id": "claude-opus-4-6", "speed": "fast"}。

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

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-sonnet-4-6",
    "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
}

更新 Agent

更新 Agent 會產生新版本。傳入目前的 version 以確保您是從已知狀態進行更新。

更新語意

省略的欄位將被保留。 您只需包含想要變更的欄位。
純量欄位（model、system、name 等）將以新值取代。system 和 description 可透過傳入 null 來清除。model 和 name 為必填欄位，無法清除。
陣列欄位（tools、mcp_servers、skills、callable_agents）將完全由新陣列取代。若要完全清除陣列欄位，請傳入 null 或空陣列。

Agent 生命週期

操作	行為
更新	產生新的 Agent 版本。
列出版本	擷取完整版本歷史記錄以追蹤隨時間的變更。
封存	Agent 變為唯讀。新工作階段無法引用它，但現有工作階段可繼續執行。

列出版本

擷取完整版本歷史記錄以追蹤 Agent 隨時間的變更情況。

封存 Agent

封存使 Agent 變為唯讀。現有工作階段可繼續執行，但新工作階段無法引用該 Agent。回應會將 archived_at 設定為封存時間戳記。

後續步驟

配置工具以自訂 Agent 可使用的功能。
附加技能以獲得特定領域的專業知識。
開始工作階段以引用您的 Agent。

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -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 '{
    "name": "Coding Assistant",
    "model": "claude-sonnet-4-6",
    "system": "You are a helpful coding agent.",
    "tools": [{"type": "agent_toolset_20260401"}]
  }')

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

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 @- <<EOF
{
  "version": $AGENT_VERSION,
  "system": "You are a helpful coding agent. Always write tests."
}
EOF
)

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

curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID/versions" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "Version \(.version): \(.updated_at)"'

archived=$(curl -fsSL -X POST "https://api.anthropic.com/v1/agents/$AGENT_ID/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")

echo "Archived at: $(jq -r '.archived_at' <<< "$archived")"