代理設定

建構定義您的代理

定義您的代理

建立可重複使用、版本化的代理配置。

代理是一個可重複使用、版本化的配置，定義了人設和功能。它將模型、系統提示、工具、MCP 伺服器和技能整合在一起，形成 Claude 在會話期間的行為方式。

建立代理一次作為可重複使用的資源，並在每次開始會話時按 ID 參考它。代理是版本化的，更容易在許多會話中管理。

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

代理配置欄位

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

建立代理

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

ant beta:agents create \
  --name "Coding Assistant" \
  --model '{id: claude-opus-4-7}' \
  --system "You are a helpful coding agent." \
  --tool '{type: agent_toolset_20260401}'

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

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

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

更新代理

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

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

更新語義

省略的欄位會被保留。 您只需要包含要變更的欄位。
純量欄位（model、system、name 等）會被替換為新值。system 和 description 可以透過傳遞 null 來清除。model 和 name 是必需的，無法清除。
陣列欄位（tools、mcp_servers、skills、callable_agents）會被新陣列完全替換。若要完全清除陣列欄位，請傳遞 null 或空陣列。
中繼資料在鍵級別進行合併。您提供的鍵會被新增或更新。您省略的鍵會被保留。若要刪除特定鍵，請將其值設定為空字串。
無操作偵測。 如果更新相對於目前版本不產生任何變更，則不會建立新版本，並傳回現有版本。

代理生命週期

操作	行為
更新	產生新的代理版本。
列出版本	取得完整版本歷史記錄以追蹤一段時間內的變更。
封存	代理變成唯讀。新會話無法參考它，但現有會話繼續執行。

列出版本

取得完整版本歷史記錄以追蹤代理一段時間內的變更方式。

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

封存代理

封存使代理變成唯讀。現有會話繼續執行，但新會話無法參考該代理。回應將 archived_at 設定為封存時間戳記。

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

後續步驟

配置工具以自訂代理可以使用的功能。
附加技能以獲得特定領域的專業知識。
開始會話，參考您的代理。

Was this page helpful?

建構定義您的代理

定義您的代理

建立可重複使用、版本化的代理配置。

建立代理一次作為可重複使用的資源，並在每次開始會話時按 ID 參考它。代理是版本化的，更容易在許多會話中管理。

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

代理配置欄位

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

建立代理

ant beta:agents create \
  --name "Coding Assistant" \
  --model '{id: claude-opus-4-7}' \
  --system "You are a helpful coding agent." \
  --tool '{type: agent_toolset_20260401}'

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

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

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

更新代理

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

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

更新語義

省略的欄位會被保留。 您只需要包含要變更的欄位。
純量欄位（model、system、name 等）會被替換為新值。system 和 description 可以透過傳遞 null 來清除。model 和 name 是必需的，無法清除。
陣列欄位（tools、mcp_servers、skills、callable_agents）會被新陣列完全替換。若要完全清除陣列欄位，請傳遞 null 或空陣列。
中繼資料在鍵級別進行合併。您提供的鍵會被新增或更新。您省略的鍵會被保留。若要刪除特定鍵，請將其值設定為空字串。
無操作偵測。 如果更新相對於目前版本不產生任何變更，則不會建立新版本，並傳回現有版本。

代理生命週期

操作	行為
更新	產生新的代理版本。
列出版本	取得完整版本歷史記錄以追蹤一段時間內的變更。
封存	代理變成唯讀。新會話無法參考它，但現有會話繼續執行。

列出版本

取得完整版本歷史記錄以追蹤代理一段時間內的變更方式。

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

封存代理

封存使代理變成唯讀。現有會話繼續執行，但新會話無法參考該代理。回應將 archived_at 設定為封存時間戳記。

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

後續步驟

配置工具以自訂代理可以使用的功能。
附加技能以獲得特定領域的專業知識。
開始會話，參考您的代理。

Was this page helpful?