--- title: 定義您的代理 url: https://platform.claude.com/docs/zh-TW/managed-agents/agent-setup description: 建立可重複使用、具版本控制的代理設定。 featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- 代理是一種可重複使用、具版本控制的設定，用於定義角色與能力。它將模型、系統提示、工具、MCP 伺服器和技能整合在一起，這些元素決定了 Claude 在工作階段中的行為方式。 只需將代理建立一次作為可重複使用的資源，之後每次[啟動工作階段](https://platform.claude.com/docs/zh-TW/managed-agents/sessions)時透過 ID 參照它即可。代理具有版本控制，更容易在多個工作階段之間進行管理。 ## 代理設定欄位 | 欄位 | 說明 | | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` (csharp, go: `Name`) | 必填。代理的人類可讀名稱。 | | `model` (csharp, go: `Model`) | 必填。驅動代理的 Claude [模型](https://platform.claude.com/docs/zh-TW/models/overview)。接受模型 ID 字串或物件，例如 `{"id": "claude-opus-5-5"}`。支援 Claude 4.5 及更新的模型。物件形式也接受 `speed`、`effort` 和 `inference_geo` 欄位；請參閱[建立代理](https://platform.claude.com/docs/zh-TW/managed-agents/agent-setup#create-an-agent)下的提示、[Effort 等級](https://platform.claude.com/docs/zh-TW/build-with-claude/effort#effort-levels)以及[固定推論地理區域](https://platform.claude.com/docs/zh-TW/managed-agents/agent-setup#pin-the-inference-geo)。 | | `system` (csharp, go: `System`; ruby: `system_`) | 定義代理行為與角色的[系統提示](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role)。系統提示與[使用者訊息](https://platform.claude.com/docs/zh-TW/managed-agents/reference#event-types)不同，後者應描述要完成的工作。 | | `tools` (csharp, go: `Tools`) | 代理可使用的工具。結合了[預建代理工具](https://platform.claude.com/docs/zh-TW/managed-agents/tools)、[MCP 工具](https://platform.claude.com/docs/zh-TW/managed-agents/mcp-connector)和[自訂工具](https://platform.claude.com/docs/zh-TW/managed-agents/tools#custom-tools)。 | | `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) | 提供標準化第三方能力的 [MCP 伺服器](https://platform.claude.com/docs/zh-TW/managed-agents/mcp-connector)。 | | `skills` (csharp, go: `Skills`) | 以漸進式揭露方式提供特定領域上下文的[技能](https://platform.claude.com/docs/zh-TW/managed-agents/skills)。 | | `multiagent` (csharp, go: `Multiagent`) | 讓代理將工作交給其他代理（作為子代理或在[動態工作流程](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#dynamic-workflows)中），並可選擇諮詢[顧問](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#give-the-session-an-advisor)模型。使用 `multiagent_20261001` 類型時，除非您停用，否則動態工作流程預設為開啟。請參閱[多代理協調](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration)。 | | `description` (csharp, go: `Description`) | 代理功能的說明。 | | `metadata` (csharp, go: `Metadata`) | 供您自行追蹤使用的任意鍵值對。 | 您也可以針對單一工作階段覆寫 `model` (csharp, go: `Model`)、`system` (csharp, go: `System`; ruby: `system_`)、`tools` (csharp, go: `Tools`)、`mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) 和 `skills` (csharp, go: `Skills`)，而不變更代理本身。`model` (csharp, go: `Model`) 覆寫會完整取代代理的 `model` (csharp, go: `Model`) 物件，因此代理本身的 `effort` (csharp, go: `Effort`) 不會被沿用。若要以特定 effort 等級執行工作階段，請在覆寫的 `model` (csharp, go: `Model`) 物件中設定 `effort` (csharp, go: `Effort`)。請參閱[為工作階段覆寫代理設定](https://platform.claude.com/docs/zh-TW/managed-agents/sessions#override-agent-configuration-for-a-session)。 ## 建立代理 以下範例定義了一個程式設計代理，它使用最新的 Claude Opus 模型，並可存取預建代理工具集。此工具集讓代理能夠撰寫程式碼、讀取檔案、搜尋網路等。如需支援工具的完整清單，請參閱[代理工具參考](https://platform.claude.com/docs/zh-TW/managed-agents/tools)。 範例使用 curl、`ant` CLI 或其中一個 SDK。如果您尚未設定，[快速入門](https://platform.claude.com/docs/zh-TW/managed-agents/quickstart#install-the-cli)涵蓋了安裝與用戶端設定。 ```bash cURL 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-opus-5-5", "system": "You are a helpful coding agent.", "tools": [{"type": "agent_toolset_20260401"}] }' ``` ```bash CLI ant apply coding-assistant.md ``` ```markdown --- name: Coding Assistant model: claude-opus-5-5 tools: - type: agent_toolset_20260401 --- You are a helpful coding agent. ``` [`ant apply`](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/apply) 會從 `coding-assistant.md` 建立代理、印出其 ID，並將其記錄在 `claude-lock.json` 中。請提交 `claude-lock.json`，這樣下一次執行 `ant apply` 時會更新此代理，而不是建立第二個代理。 ```python Python agent = client.beta.agents.create( name="Coding Assistant", model="claude-opus-5-5", system="You are a helpful coding agent.", tools=[ {"type": "agent_toolset_20260401"}, ], ) ``` ```typescript TypeScript const agent = await client.beta.agents.create({ name: "Coding Assistant", model: "claude-opus-5-5", system: "You are a helpful coding agent.", tools: [{ type: "agent_toolset_20260401" }] }); ``` ```csharp C# var agent = await client.Beta.Agents.Create(new() { Name = "Coding Assistant", Model = BetaManagedAgentsModel.ClaudeOpus5_5, System = "You are a helpful coding agent.", Tools = [ new BetaManagedAgentsAgentToolset20260401Params { Type = "agent_toolset_20260401", }, ], }); ``` ```go Go agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "Coding Assistant", Model: anthropic.BetaManagedAgentsModelConfigParams{ ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5, }, System: anthropic.String("You are a helpful coding agent."), Tools: []anthropic.BetaAgentNewParamsToolUnion{{ OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, }, }}, }) if err != nil { panic(err) } ``` ```java Java var agent = client.beta().agents().create( AgentCreateParams.builder() .name("Coding Assistant") .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5) .system("You are a helpful coding agent.") .addTool( BetaManagedAgentsAgentToolset20260401Params.builder() .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) .build() ) .build() ); ``` ```php PHP $agent = $client->beta->agents->create( name: 'Coding Assistant', model: 'claude-opus-5-5', system: 'You are a helpful coding agent.', tools: [ BetaManagedAgentsAgentToolset20260401Params::with( type: 'agent_toolset_20260401', ), ], ); ``` ```ruby Ruby agent = client.beta.agents.create( name: "Coding Assistant", model: "claude-opus-5-5", system_: "You are a helpful coding agent.", tools: [{type: "agent_toolset_20260401"}] ) ``` 回應會回傳您的設定，並加上 `id`、`type`、`version`、`created_at`、`updated_at` 和 `archived_at` 欄位，同時以預設值填入您省略的 `model` 欄位（例如 `effort`）。`version` 從 1 開始，每次更新變更代理時都會遞增。 ```json { "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` 顯示其預設的[權限政策](https://platform.claude.com/docs/zh-TW/managed-agents/permission-policies) `always_allow`，除非您另行設定，否則會套用此政策。 若要搭配[快速模式](https://platform.claude.com/docs/zh-TW/build-with-claude/fast-mode)使用 Claude Opus 5.5、Claude Opus 5 或 Claude Opus 4.8，請將 `model` 以物件形式傳入，例如：`{"id": "claude-opus-5-5", "speed": "fast"}`。請參閱快速模式頁面的[支援模型](https://platform.claude.com/docs/zh-TW/build-with-claude/fast-mode#supported-models)。 若要設定模型的 effort 等級，請將 `model` 以物件形式傳入，例如：`{"id": "claude-opus-5-5", "effort": "high"}`。`effort` 欄位接受等級字串（`low`、`medium`、`high`、`xhigh` 或 `max`）或物件，例如 `{"type": "high"}`。如需了解各等級的作用，請參閱 [Effort 等級](https://platform.claude.com/docs/zh-TW/build-with-claude/effort#effort-levels)。 ### 固定推論地理區域 與 `speed` (csharp, go: `Speed`) 和 `effort` (csharp, go: `Effort`) 一樣，`inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) 是透過 `model` (csharp, go: `Model`) 的物件形式設定：將 `model` (csharp, go: `Model`) 以物件形式傳入，並在 `id` (csharp, go: `ID`) 旁設定 `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`)。此欄位接受 `"us"` 或 `"global"`。未設定時，每個模型請求會依照提供服務當下工作區的預設推論地理區域處理。如需工作區層級的地理區域控制與定價，請參閱[資料駐留](https://platform.claude.com/docs/zh-TW/manage-claude/data-residency)。 以下範例將代理固定於美國推論，並印出代理 `model` (csharp, go: `Model`) 物件中的 `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) 值： ```bash cURL 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": "Geo-pinned assistant", "model": {"id": "claude-opus-5-5", "inference_geo": "us"}, "system": "You are a helpful assistant." }' ``` ```bash CLI ant apply geo-pinned-assistant.md ``` ```markdown --- name: Geo-pinned assistant model: id: claude-opus-5-5 inference_geo: us --- You are a helpful assistant. ``` ```python Python agent = client.beta.agents.create( name="Geo-pinned assistant", model={ "id": "claude-opus-5-5", "inference_geo": "us", }, system="You are a helpful assistant.", ) print(f"Inference geo: {agent.model.inference_geo}") ``` ```typescript TypeScript const agent = await client.beta.agents.create({ name: "Geo-pinned assistant", model: { id: "claude-opus-5-5", inference_geo: "us" }, system: "You are a helpful assistant." }); console.log(`Inference geo: ${agent.model.inference_geo}`); ``` ```csharp C# var agent = await client.Beta.Agents.Create(new() { Name = "Geo-pinned assistant", Model = new BetaManagedAgentsModelConfigParams { ID = BetaManagedAgentsModel.ClaudeOpus5_5, InferenceGeo = "us", }, System = "You are a helpful assistant.", }); Console.WriteLine($"Inference geo: {agent.Model.InferenceGeo}"); ``` ```go Go agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "Geo-pinned assistant", Model: anthropic.BetaManagedAgentsModelConfigParams{ ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5, InferenceGeo: anthropic.String("us"), }, System: anthropic.String("You are a helpful assistant."), }) if err != nil { panic(err) } fmt.Printf("Inference geo: %s\n", agent.Model.InferenceGeo) ``` ```java Java var agent = client.beta().agents().create( AgentCreateParams.builder() .name("Geo-pinned assistant") .model( BetaManagedAgentsModelConfigParams.builder() .id(BetaManagedAgentsModel.CLAUDE_OPUS_5_5) .inferenceGeo("us") .build() ) .system("You are a helpful assistant.") .build() ); IO.println("Inference geo: " + agent.model().inferenceGeo().orElseThrow()); ``` ```php PHP $agent = $client->beta->agents->create( name: 'Geo-pinned assistant', model: BetaManagedAgentsModelConfigParams::with( id: 'claude-opus-5-5', inferenceGeo: 'us', ), system: 'You are a helpful assistant.', ); echo "Inference geo: {$agent->model->inferenceGeo}\n"; ``` ```ruby Ruby agent = client.beta.agents.create( name: "Geo-pinned assistant", model: {id: "claude-opus-5-5", inference_geo: "us"}, system_: "You are a helpful assistant." ) puts "Inference geo: #{agent.model.inference_geo}" ``` `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) 固定設定會在儲存代理時、從代理建立工作階段時，以及工作階段處理的每個回合中，依據工作區的 [`allowed_inference_geos`](https://platform.claude.com/docs/zh-TW/manage-claude/data-residency#workspace-level-restrictions) 進行驗證。如果工作區允許清單縮小，導致固定設定不再被允許，則無法再從該代理建立新的工作階段，且執行中的工作階段會拒絕後續回合；固定設定永遠不會被豁免，因為工作區依賴它們來確保合規性與資料駐留。 在不支援地理推論固定的模型上設定 `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) 會回傳 400 錯誤；如需支援的模型，請參閱[模型可用性](https://platform.claude.com/docs/zh-TW/manage-claude/data-residency#model-availability)。在 `multiagent` (csharp, go: `Multiagent`) 設定中，代理的固定設定以及 `subagents` (csharp, go: `Subagents`) 或 `workflows` (csharp, go: `Workflows`) 的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單中列出的每個代理的固定設定，必須全部設為相同的值或全部不設定；請參閱[多代理協調](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration)。若之後要變更或清除固定設定，請更新代理的 `model` (csharp, go: `Model`) 物件；提供不含 `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) 的 `model` (csharp, go: `Model`) 會清除它，如[更新語意](https://platform.claude.com/docs/zh-TW/managed-agents/agent-setup#update-semantics)中所述。 ## 更新代理 當設定變更時，更新代理會產生新版本。`version` (csharp, go: `Version`) 欄位為選填：提供它以進行樂觀並行控制（不符時回傳 409），或省略它以無條件套用更新（最後寫入者勝出）。對已封存代理的更新會被拒絕。 使用 CLI 時，請編輯代理的檔案並再次執行 `ant apply`；apply 會為您提供 `version`。 ```bash cURL 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 '{ "version": '"$AGENT_VERSION"', "system": "You are a helpful coding agent. Always write tests." }' ``` ```bash CLI ant apply coding-assistant.md ``` ```markdown --- name: Coding Assistant model: claude-opus-5-5 tools: - type: agent_toolset_20260401 --- You are a helpful coding agent. Always write tests. ``` ```python Python updated_agent = client.beta.agents.update( agent.id, version=agent.version, system="You are a helpful coding agent. Always write tests.", ) print(f"New version: {updated_agent.version}") ``` ```typescript TypeScript const updatedAgent = await client.beta.agents.update(agent.id, { version: agent.version, system: "You are a helpful coding agent. Always write tests." }); console.log(`New version: ${updatedAgent.version}`); ``` ```csharp C# var updatedAgent = await client.Beta.Agents.Update(agent.ID, new() { Version = agent.Version, System = "You are a helpful coding agent. Always write tests.", }); Console.WriteLine($"New version: {updatedAgent.Version}"); ``` ```go Go updatedAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{ Version: anthropic.Int(agent.Version), System: anthropic.String("You are a helpful coding agent. Always write tests."), }) if err != nil { panic(err) } fmt.Printf("New version: %d\n", updatedAgent.Version) ``` ```java Java var updatedAgent = client.beta().agents().update( agent.id(), AgentUpdateParams.builder() .version(agent.version()) .system("You are a helpful coding agent. Always write tests.") .build() ); IO.println("New version: " + updatedAgent.version()); ``` ```php PHP $updatedAgent = $client->beta->agents->update( $agent->id, version: $agent->version, system: 'You are a helpful coding agent. Always write tests.', ); echo "New version: {$updatedAgent->version}\n"; ``` ```ruby Ruby updated_agent = client.beta.agents.update( agent.id, version: agent.version, system_: "You are a helpful coding agent. Always write tests." ) puts "New version: #{updated_agent.version}" ``` 上述範例提供了建立回應中的 `version`，因此只有在您讀取代理後沒有其他變更時，更新才會套用。若要無條件套用更新，請在請求中省略 `version`： ```bash cURL 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." }' ``` ```bash CLI ant beta:agents update \ --agent-id "$AGENT_ID" \ --description "Writes and reviews code." ``` ```python Python unconditional_agent = client.beta.agents.update( agent.id, description="Writes and reviews code.", ) print(f"New version: {unconditional_agent.version}") ``` ```typescript TypeScript const unconditionalAgent = await client.beta.agents.update(agent.id, { description: "Writes and reviews code." }); console.log(`New version: ${unconditionalAgent.version}`); ``` ```csharp C# var unconditionalAgent = await client.Beta.Agents.Update(agent.ID, new() { Description = "Writes and reviews code.", }); Console.WriteLine($"New version: {unconditionalAgent.Version}"); ``` ```go Go unconditionalAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{ Description: anthropic.String("Writes and reviews code."), }) if err != nil { panic(err) } fmt.Printf("New version: %d\n", unconditionalAgent.Version) ``` ```java Java var unconditionalAgent = client.beta().agents().update( agent.id(), AgentUpdateParams.builder() .description("Writes and reviews code.") .build() ); IO.println("New version: " + unconditionalAgent.version()); ``` ```php PHP $unconditionalAgent = $client->beta->agents->update( $agent->id, description: 'Writes and reviews code.', ); echo "New version: {$unconditionalAgent->version}\n"; ``` ```ruby Ruby unconditional_agent = client.beta.agents.update( agent.id, description: "Writes and reviews code." ) puts "New version: #{unconditional_agent.version}" ``` ### 更新語意 * **`version` (csharp, go: `Version`)** 為選填，提供時必須至少為 1。提供時，如果它與代理的目前版本不符，即使您傳送的欄位已與儲存的值相符，請求仍會回傳 409；請重新讀取代理並重試。省略時，更新會無條件套用，最新的更新會靜默取代任何並行的更新，且不會向任一呼叫者回報錯誤。對於互動式呼叫者，建議預設提供 `version` (csharp, go: `Version`)；而省略它則適用於宣告式套用迴圈，例如同步已簽入代理定義的 CI 作業，此時由該迴圈擁有代理。 * **省略的欄位會被保留。** 您只需包含想要變更的欄位。 * **純量欄位**（`model` (csharp, go: `Model`)、`system` (csharp, go: `System`; ruby: `system_`)、`name` (csharp, go: `Name`)、`description` (csharp, go: `Description`)）會被新值取代。`system` (csharp, go: `System`; ruby: `system_`) 和 `description` (csharp, go: `Description`) 可透過傳入 `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `param.Null[string]()`; php: `requestOptions: ['extraBodyParams' => ['system' => null, 'description' => null]]`) 來清除。`model` (csharp, go: `Model`) 和 `name` (csharp, go: `Name`) 為必填，無法清除。在您提供的 `model` (csharp, go: `Model`) 物件中，`effort` (csharp, go: `Effort`) 是唯一的例外：如果模型 `id` (csharp, go: `ID`) 未變更，省略 `effort` (csharp, go: `Effort`) 會保留已儲存的 effort 等級不變。如果您變更了模型 `id` (csharp, go: `ID`)，省略的 `effort` (csharp, go: `Effort`) 會重設為新模型的預設值。其他 `model` (csharp, go: `Model`) 欄位會隨物件一併被取代：提供不含 `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) 的 `model` (csharp, go: `Model`) 會清除代理的推論地理區域固定設定。 * **陣列欄位**（`tools` (csharp, go: `Tools`)、`mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`)、`skills` (csharp, go: `Skills`)）會被新陣列完全取代。若要完全清除陣列欄位，請傳入 `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `param.NullSlice[[]anthropic.BetaAgentUpdateParamsToolUnion]()`; php: `requestOptions: ['extraBodyParams' => ['mcp_servers' => null]]`) 或空陣列。 * **`multiagent` (csharp, go: `Multiagent`)** 在更新保留 `multiagent_20261001` 類型時，會逐層合併至已儲存的區塊。您省略的設定會保留其已儲存的值，而您傳送的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單會取代已儲存的清單。任何其他傳送 `multiagent` (csharp, go: `Multiagent`) 的更新都會整體取代已儲存的區塊，而其省略的設定會採用預設值。傳入 `"multiagent": null` (python: `multiagent=None`; typescript: `multiagent: null`; ruby: `multiagent: nil`; go: `Multiagent: param.NullStruct[anthropic.BetaManagedAgentsMultiagentParamsUnion]()`; java: `.multiagent(Optional.empty())`; csharp: `Multiagent = null`; php: `requestOptions: ['extraBodyParams' => ['multiagent' => null]]`) 可清除整個區塊。在區塊內，`null` 會將設定重設為其預設值，因此將 `workflows` (csharp, go: `Workflows`) 設為 `null` 會開啟動態工作流程。請參閱[開啟動態工作流程](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows)。 * **Metadata** 會在鍵層級合併。您提供的鍵會被新增或更新。您省略的鍵會被保留。若要刪除特定鍵，請將其值設為 `null`。 * **無操作偵測。** 如果更新相對於目前版本沒有產生任何變更，則不會建立新版本，並回傳現有版本。 * **其他代理的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單不會被更新。** 在 `subagents` (csharp, go: `Subagents`) 或 `workflows` (csharp, go: `Workflows`) 的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單中列出此代理的代理，會保留其建立時或上次更新傳送該清單時所固定的版本，即使參照省略了 `version` (csharp, go: `Version`) 也是如此。若要委派給新版本，請[更新列出它的代理](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#list-the-subagents)，使清單參照新版本。 以下更新會清除說明、從 `metadata` (csharp, go: `Metadata`) 中刪除 `team` 鍵，並將 `workflows` (csharp, go: `Workflows`) 設為 `null`，從而開啟動態工作流程： ```bash cURL 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": null, "metadata": {"team": null}, "multiagent": {"type": "multiagent_20261001", "workflows": null} }' ``` ```bash CLI ant apply code-reviewer.md ``` ```markdown --- 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. ``` 檔案中已不再有 `description` 或 `team` 鍵，因此 `ant apply` 會為它們傳送 `null`。刪除 `multiagent` 內的設定會保留其已儲存的值，因此檔案將 `workflows` 設為 `null`。 ```python Python cleared_agent = client.beta.agents.update( agent.id, description=None, metadata={"team": None}, multiagent={"type": "multiagent_20261001", "workflows": None}, ) print(f"Description: {cleared_agent.description}") ``` ```typescript TypeScript const clearedAgent = await client.beta.agents.update(agent.id, { description: null, metadata: { team: null }, multiagent: { type: "multiagent_20261001", workflows: null } }); console.log(`Description: ${clearedAgent.description}`); ``` ```csharp C# var clearedAgent = await client.Beta.Agents.Update(agent.ID, new() { Description = null, Metadata = new Dictionary { ["team"] = null }, Multiagent = new BetaManagedAgentsMultiagent20261001Params { Workflows = null }, }); Console.WriteLine($"Description: {clearedAgent.Description}"); ``` ```go Go // Metadata 是 map[string]string，因此請將 team 的 null 作為請求選項傳送。 clearedAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{ Description: param.Null[string](), Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{ OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{ Workflows: param.NullStruct[anthropic.BetaManagedAgentsMultiagentWorkflowsParamsUnion](), }, }, }, option.WithJSONSet("metadata.team", nil)) if err != nil { panic(err) } fmt.Printf("Description: %q\n", clearedAgent.Description) ``` ```java Java var clearedAgent = client.beta().agents().update( agent.id(), AgentUpdateParams.builder() .description(Optional.empty()) .metadata( AgentUpdateParams.Metadata.builder() .putAdditionalProperty("team", JsonValue.from(null)) .build() ) .multiagent( BetaManagedAgentsMultiagent20261001Params.builder() .workflows(Optional.empty()) .build() ) .build() ); IO.println("Description: " + clearedAgent.description().orElse(null)); ``` ```php PHP // update() 會捨棄 null 引數，因此請將 null 值放在 extraBodyParams 中傳入。 $clearedAgent = $client->beta->agents->update( $agent->id, requestOptions: [ 'extraBodyParams' => [ 'description' => null, 'metadata' => ['team' => null], 'multiagent' => ['type' => 'multiagent_20261001', 'workflows' => null], ], ], ); echo 'Description: ' . json_encode($clearedAgent->description) . "\n"; ``` ```ruby Ruby cleared_agent = client.beta.agents.update( agent.id, description: nil, metadata: {team: nil}, multiagent: {type: :multiagent_20261001, workflows: nil} ) puts "Description: #{cleared_agent.description.inspect}" ``` ## 代理生命週期 | 操作 | 行為 | | -------- | ---------------------------------- | | **更新** | 當設定變更時產生新的代理版本。 | | **列出版本** | 回傳完整的版本歷史，讓您能追蹤隨時間的變更。 | | **封存** | 使代理變為唯讀。新的工作階段無法參照它，但現有的工作階段會繼續執行。 | ### 列出版本 擷取完整的版本歷史，以追蹤代理隨時間的變化。結果會分頁，SDK 範例會自動擷取每一頁。 ```bash cURL 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" ``` ```bash CLI ant beta:agents:versions list --agent-id "$AGENT_ID" ``` ```python Python for version in client.beta.agents.versions.list(agent.id): print(f"Version {version.version}: {version.updated_at.isoformat()}") ``` ```typescript TypeScript for await (const version of client.beta.agents.versions.list(agent.id)) { console.log(`Version ${version.version}: ${version.updated_at}`); } ``` ```csharp C# var versions = await client.Beta.Agents.Versions.List(agent.ID); await foreach (var version in versions.Paginate()) { Console.WriteLine($"Version {version.Version}: {version.UpdatedAt:O}"); } ``` ```go Go iter := client.Beta.Agents.Versions.ListAutoPaging(ctx, agent.ID, anthropic.BetaAgentVersionListParams{}) for iter.Next() { version := iter.Current() fmt.Printf("Version %d: %s\n", version.Version, version.UpdatedAt.Format(time.RFC3339)) } if err := iter.Err(); err != nil { panic(err) } ``` ```java Java for (var version : client.beta().agents().versions().list(agent.id()).autoPager()) { IO.println("Version " + version.version() + ": " + version.updatedAt()); } ``` ```php PHP foreach ($client->beta->agents->versions->list($agent->id)->pagingEachItem() as $version) { echo "Version {$version->version}: {$version->updatedAt->format(\DateTimeInterface::ATOM)}\n"; } ``` ```ruby Ruby client.beta.agents.versions.list(agent.id).auto_paging_each do |agent_version| puts "Version #{agent_version.version}: #{agent_version.updated_at.iso8601}" end ``` ### 封存代理 封存會使代理變為唯讀，且無法復原。現有的工作階段會繼續執行，但新的工作階段無法參照該代理。回應會將 `archived_at` (java, php: `archivedAt`; csharp, go: `ArchivedAt`) 設為封存時間戳記。 ```bash cURL 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" ``` ```bash CLI ant beta:agents archive --agent-id "$AGENT_ID" ``` ```python Python archived = client.beta.agents.archive(agent.id) print(f"Archived at: {archived.archived_at.isoformat()}") ``` ```typescript TypeScript const archived = await client.beta.agents.archive(agent.id); console.log(`Archived at: ${archived.archived_at}`); ``` ```csharp C# var archived = await client.Beta.Agents.Archive(agent.ID); Console.WriteLine($"Archived at: {archived.ArchivedAt:O}"); ``` ```go Go archived, err := client.Beta.Agents.Archive(ctx, agent.ID, anthropic.BetaAgentArchiveParams{}) if err != nil { panic(err) } fmt.Printf("Archived at: %s\n", archived.ArchivedAt.Format(time.RFC3339)) ``` ```java Java var archived = client.beta().agents().archive(agent.id()); IO.println("Archived at: " + archived.archivedAt().orElseThrow()); ``` ```php PHP $archived = $client->beta->agents->archive($agent->id); echo "Archived at: {$archived->archivedAt->format(\DateTimeInterface::ATOM)}\n"; ``` ```ruby Ruby archived = client.beta.agents.archive(agent.id) puts "Archived at: #{archived.archived_at.iso8601}" ``` ## 後續步驟 設定您的代理可使用的工具。 為您的代理附加可重複使用、以檔案系統為基礎的專業知識，以用於特定領域的工作流程。 建立工作階段以執行您的代理並開始執行任務。 Claude Managed Agents 的事件類型、自行託管 worker CLI 旗標、支援的 MCP 伺服器類型、速率限制以及品牌指南。