---
title: 多代理協調
url: https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration
description: 在單一工作階段中協調多個代理。
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
---

「Multiagent orchestration」（多代理協調）讓一個代理能夠與其他代理協作以完成複雜的工作。各代理可以在各自隔離的上下文中平行運作，這有助於提升輸出品質，也能縮短完成時間。

不確定多代理設定是否適合您的問題？請參閱[何時使用多代理系統（以及何時不該使用）](https://claude.com/blog/building-multi-agent-systems-when-and-how-to-use-them)。

## 將工作交給其他代理

工作階段所執行的代理可以透過兩種方式將工作交給其他代理。使用 **subagents**（子代理）時，它會自行委派任務，並讀取每個子代理回報的內容。使用 **dynamic workflows**（動態工作流程）時，它會撰寫一個工作流程：一個在背景執行多個代理並合併其結果的程式。它也可以在自行完成工作的同時，諮詢 **advisor**（顧問）模型以取得指引。

您決定代理可以使用其中哪些方式，而代理決定何時使用它們。為了引導這項選擇，請在代理的系統提示中告訴它何時使用工作流程執行。請參閱[告訴代理何時使用執行](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#tell-the-agent-when-to-use-a-run)。您也可以將代理限制為只能使用您列出的代理。

使用子代理時，由代理本身決定接下來發生什麼。[子代理的執行緒](https://platform.claude.com/docs/zh-TW/managed-agents/session-threads)在您封存之前都會保持可用，因此代理可以向它傳送後續訊息。使用動態工作流程時，Claude 會撰寫一個程式來協調代理，而不需要 Claude 直接參與。上下文和結果會以程式化方式從一個代理傳遞到另一個代理，讓主要工作階段執行緒得以與使用者溝通，並查看一個或多個正在執行的工作流程以回報進度。代理無法向執行的執行緒傳送後續訊息，且伺服器最晚會在執行結束時封存其每個執行緒。

| 方式                                                                                                                      | 運作方式                                                                                                                                              | 適用時機                                                         | 注意事項                                                                                                                                                      |
| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [子代理](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#delegate-to-subagents)             | 代理將任務委派給其子代理。每個子代理在自己的[工作階段執行緒](https://platform.claude.com/docs/zh-TW/managed-agents/session-threads)中工作，您可以列出並串流這些執行緒。                          | 代理應在子代理回報後向其傳送後續訊息，或者它需要您列出的、具有各自系統提示和工具的專家代理。               | 委派只有一層深，且一個工作階段同時最多可以有 25 個子執行緒，包括閒置的執行緒。顧問執行緒和工作流程執行的執行緒不計入。                                                                                             |
| [動態工作流程](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#dynamic-workflows)              | 代理撰寫一個工作流程：一個分階段執行多個代理並合併其結果的程式。伺服器會在背景將其作為一個工作流程執行來運行，您可以追蹤它。工作流程會定義代理，或從您提供的清單中挑選代理。                                                            | 大多數需要多個代理的工作：包含許多部分的工作、平行工作，或應該更快完成的長時間任務。例如稽核、遷移、深度研究和交叉核對。 | 執行中的每個代理都會使用 token，因此請設定[工作階段預算](https://platform.claude.com/docs/zh-TW/managed-agents/budgets)來限制工作階段的支出（包含執行）。請在代理的系統提示中告訴它何時使用執行。您可以依階段追蹤執行，並讀取其每個執行緒。 |
| [為工作階段提供顧問](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#give-the-session-an-advisor) | 工作階段的[主要執行緒](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#how-it-works)會在回合中途諮詢顧問模型以取得指引，例如規劃方法或審查工作，並繼續自行完成工作。 | 應由一個代理完成工作，並在規劃或最終審查等關鍵時刻借助顧問模型的判斷。                          | 只有主要執行緒可以諮詢顧問，且諮詢會以顧問模型的費率計費。                                                                                                                             |

您可以在代理定義的 `multiagent` 區塊中設定這些功能，該區塊具有一個 `type`。使用 `multiagent_20261001` 類型時，代理可以同時使用這三種方式，且您可以個別開啟或關閉每一種。預設情況下，`subagents` 和 `workflows` 都已啟用。`subagents` 和 `workflows` 各自都啟用了 `inline_agents`，這是針對[由代理或工作流程自行定義的代理](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#predefined-and-inline-agents)的設定：

```json
{
  "multiagent": { "type": "multiagent_20261001" }
}
```

若要設定代理可以呼叫哪些代理，請參閱[預先定義代理與內嵌代理](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#predefined-and-inline-agents)。若要關閉某項設定，請參閱[開啟動態工作流程](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows)。

## 預先定義代理與內嵌代理

每個子代理，以及工作流程執行中的每個代理，都屬於以下兩種之一：

* **預先定義代理：** 您已經[建立](https://platform.claude.com/docs/zh-TW/managed-agents/agent-setup)，並列在 `multiagent` (csharp, go: `Multiagent`) 區塊中的代理。它使用自己的設定：模型、系統提示、工具、MCP 伺服器和技能。
* **內嵌代理：** 未儲存的代理。由工作階段所執行的代理或工作流程在分派工作時定義它。它使用該代理的模型、工具、MCP 伺服器和技能。

這兩種代理在 `subagents` 和 `workflows` 下都可運作：

| 代理種類 | 在 `subagents` 下                                     | 在 `workflows` 下                                                |
| ---- | --------------------------------------------------- | -------------------------------------------------------------- |
| 預先定義 | 代理可以委派給您在 `subagents.predefined_agents` 中列出的代理。     | 工作流程可以使用您在 `workflows.predefined_agents` 中列出的代理。               |
| 內嵌   | 代理在委派時可以定義內嵌代理。`subagents.inline_agents` 可開啟或關閉此功能。 | 工作流程可以定義內嵌代理，並為每個代理撰寫系統提示。`workflows.inline_agents` 可開啟或關閉此功能。 |

`subagents.predefined_agents` 和 `workflows.predefined_agents` 是兩個獨立的清單。一個清單中的代理不會被加入另一個清單。兩個清單預設都是空的。任一清單的項目採用以下其中一種形式：

* `{"type": "agent", "id": agent.id}` 透過 ID 參照先前建立的 `agent`。如果未指定 `version`，則在建立列出它的代理時，或在更新傳送該清單時，參照會固定到該代理的最新版本。
* `{"type": "agent", "id": agent.id, "version": agent.version}` 固定特定的代理版本。
* 單獨的 `agent.id` 字串是 `{"type": "agent", "id": agent.id}` 的簡寫。
* `{"type": "self"}` 列出代理本身，讓它的副本可以執行工作。如果工作階段是以[代理設定覆寫](https://platform.claude.com/docs/zh-TW/managed-agents/sessions#override-agent-configuration-for-a-session)建立的，這些覆寫也會套用到這些副本。透過 ID 參照的項目不受影響。

這些項目及其所指名代理的規則適用於兩個清單。請參閱[列出子代理](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#list-the-subagents)。

內嵌代理在兩項設定下預設都是開啟的。若要只允許您列出的代理，請在 `subagents` 下、`workflows` 下或兩者下將 `inline_agents` 設為 `{"type": "disabled"}`。關閉內嵌代理的設定，其 `predefined_agents` 清單中至少需要一個代理。若清單為空，請求會以 400 錯誤失敗。在更新時，伺服器會依更新後的設定狀態進行檢查。

以下代理只允許它列出的代理。它可以委派給一個代理以及它自己的副本，而工作流程可以使用另一個代理的第 2 版：

```json
{
  "multiagent": {
    "type": "multiagent_20261001",
    "subagents": {
      "type": "enabled",
      "inline_agents": { "type": "disabled" },
      "predefined_agents": ["agent_01J8XkN5uT3vHpLqRfWdY2", { "type": "self" }]
    },
    "workflows": {
      "type": "enabled",
      "inline_agents": { "type": "disabled" },
      "predefined_agents": [
        { "type": "agent", "id": "agent_01Lm4cV8yQ2tNs7XbKdR5h", "version": 2 }
      ]
    }
  }
}
```

## 委派給子代理

### 要委派什麼

多代理協調最適合複雜的任務，這些任務要麼需要跨多種介面進行工作，要麼由多個範圍明確的任務共同促成一個整體目標。

效果良好的模式：

* **平行化：** 同時分派獨立的子任務（搜尋多個來源、分析不同的檔案），並讓代理綜合結果。
* **專業化：** 路由到具有特定領域系統提示和工具的代理，例如安全代理或文件代理，而不是讓單一代理承載所有能力。
* **升級處理：** 針對一部分複雜的子任務，諮詢能力更強的代理或模型。若要諮詢模型，請[為工作階段提供顧問](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#give-the-session-an-advisor)。

### 運作方式

所有代理共用相同的沙箱、檔案系統和[保管庫憑證](https://platform.claude.com/docs/zh-TW/managed-agents/vaults)，但每個代理都在自己的 **session thread**（工作階段執行緒）中執行，這是一個具有自己對話歷史的上下文隔離事件串流。工作階段所執行的代理會在 **primary thread**（主要執行緒）中回報活動，也就是工作階段層級的[事件串流](https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming)。當它委派工作時，會在執行期間產生額外的執行緒。工作流程執行也會建立執行緒。

子代理的執行緒是持久的。代理可以向先前呼叫過的子代理傳送後續訊息，而該子代理會保留其先前回合的所有內容。

子代理使用哪種設定，取決於它是[預先定義代理還是內嵌代理](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#predefined-and-inline-agents)。工作階段層級的[代理設定覆寫](https://platform.claude.com/docs/zh-TW/managed-agents/sessions#override-agent-configuration-for-a-session)會套用到工作階段所執行的代理及其 `self` 副本。每個代理都保有自己的對話歷史。

### 列出子代理

在[定義您的代理](https://platform.claude.com/docs/zh-TW/managed-agents/agent-setup)時，請在 `multiagent` (csharp, go: `Multiagent`) 區塊中設定 `subagents` (csharp, go: `Subagents`) 的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單，以列出它可以委派的代理：

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  curl -fsS 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": "Engineering Lead",
      "model": "claude-opus-5-5",
      "system": "You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.",
      "tools": [
        {
          "type": "agent_toolset_20260401"
        }
      ],
      "multiagent": {
        "type": "multiagent_20261001",
        "subagents": {
          "type": "enabled",
          "predefined_agents": [
            {"type": "agent", "id": "'"$REVIEWER_AGENT_ID"'"},
            {"type": "agent", "id": "'"$TEST_WRITER_AGENT_ID"'"}
          ]
        }
      }
    }'
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply engineering-lead.md reviewer.md test-writer.md
    ```

    <File filename="engineering-lead.md">
      ```markdown
      ---
      name: Engineering Lead
      model: claude-opus-5-5
      tools:
        - type: agent_toolset_20260401
      multiagent:
        type: multiagent_20261001
        subagents:
          type: enabled
          predefined_agents: # ant apply replaces each path with {type: agent, id, version}
            - ./reviewer.md
            - ./test-writer.md
      ---

      You coordinate engineering work. Delegate code review to the reviewer agent
      and test writing to the test agent.
      ```
    </File>

    <File filename="reviewer.md">
      ```markdown
      ---
      name: reviewer
      model: claude-haiku-5-5
      ---

      You are a code reviewer.
      ```
    </File>

    <File filename="test-writer.md">
      ```markdown
      ---
      name: test-writer
      model: claude-haiku-5-5
      ---

      You write unit tests.
      ```
    </File>
  </CodeGroupItem>

  ```python Python
  lead_agent = client.beta.agents.create(
      name="Engineering Lead",
      model="claude-opus-5-5",
      system="You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.",
      tools=[
          {"type": "agent_toolset_20260401"},
      ],
      multiagent={
          "type": "multiagent_20261001",
          "subagents": {
              "type": "enabled",
              "predefined_agents": [
                  {"type": "agent", "id": reviewer_agent.id},
                  {"type": "agent", "id": test_writer_agent.id},
              ],
          },
      },
  )
  ```

  ```typescript TypeScript
  const leadAgent = await client.beta.agents.create({
    name: "Engineering Lead",
    model: "claude-opus-5-5",
    system:
      "You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.",
    tools: [{ type: "agent_toolset_20260401" }],
    multiagent: {
      type: "multiagent_20261001",
      subagents: {
        type: "enabled",
        predefined_agents: [
          { type: "agent", id: reviewerAgent.id },
          { type: "agent", id: testWriterAgent.id }
        ]
      }
    }
  });
  ```

  ```csharp C#
  var leadAgent = await client.Beta.Agents.Create(new()
  {
      Name = "Engineering Lead",
      Model = BetaManagedAgentsModel.ClaudeOpus5_5,
      System = "You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.",
      Tools =
      [
          new BetaManagedAgentsAgentToolset20260401Params
          {
              Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401,
          },
      ],
      Multiagent = new BetaManagedAgentsMultiagent20261001Params
      {
          Subagents = new BetaManagedAgentsMultiagentSubagentsEnabledParams
          {
              PredefinedAgents = [reviewerAgent.ID, testWriterAgent.ID],
          },
      },
  });
  ```

  ```go Go
  leadAgent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
  	Name:   "Engineering Lead",
  	Model:  anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5},
  	System: anthropic.String("You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent."),
  	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
  		OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
  			Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
  		},
  	}},
  	Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{
  		OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{
  			Subagents: anthropic.BetaManagedAgentsMultiagentSubagentsParamsUnion{
  				OfEnabled: &anthropic.BetaManagedAgentsMultiagentSubagentsEnabledParams{
  					PredefinedAgents: []anthropic.BetaManagedAgentsMultiagentPredefinedAgentParamsUnion{
  						{OfString: anthropic.String(reviewerAgent.ID)},
  						{OfString: anthropic.String(testWriterAgent.ID)},
  					},
  				},
  			},
  		},
  	},
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var leadAgent = client.beta().agents().create(
      AgentCreateParams.builder()
          .name("Engineering Lead")
          .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
          .system("You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.")
          .addTool(
              BetaManagedAgentsAgentToolset20260401Params.builder()
                  .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
                  .build()
          )
          .multiagent(BetaManagedAgentsMultiagent20261001Params.builder()
              .subagents(BetaManagedAgentsMultiagentSubagentsEnabledParams.builder()
                  .addPredefinedAgent(BetaManagedAgentsAgentParams.builder()
                      .type(BetaManagedAgentsAgentParams.Type.AGENT)
                      .id(reviewerAgent.id())
                      .build())
                  .addPredefinedAgent(BetaManagedAgentsAgentParams.builder()
                      .type(BetaManagedAgentsAgentParams.Type.AGENT)
                      .id(testWriterAgent.id())
                      .build())
                  .build())
              .build())
          .build()
  );
  ```

  ```php PHP
  $leadAgent = $client->beta->agents->create(
      name: 'Engineering Lead',
      model: 'claude-opus-5-5',
      system: 'You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.',
      tools: [
          ['type' => 'agent_toolset_20260401'],
      ],
      multiagent: [
          'type' => 'multiagent_20261001',
          'subagents' => [
              'type' => 'enabled',
              'predefined_agents' => [
                  ['type' => 'agent', 'id' => $reviewerAgent->id],
                  ['type' => 'agent', 'id' => $testWriterAgent->id],
              ],
          ],
      ],
  );
  ```

  ```ruby Ruby
  lead_agent = client.beta.agents.create(
    name: "Engineering Lead",
    model: "claude-opus-5-5",
    system: "You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.",
    tools: [
      {type: "agent_toolset_20260401"}
    ],
    multiagent: {
      type: "multiagent_20261001",
      subagents: {
        type: "enabled",
        predefined_agents: [
          {type: "agent", id: reviewer_agent.id},
          {type: "agent", id: test_writer_agent.id}
        ]
      }
    }
  )
  ```
</CodeGroup>

除非您將內嵌代理關閉，否則代理也可以委派給內嵌代理。關於該設定，以及 `subagents` (csharp, go: `Subagents`) 的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單項目所採用的形式，請參閱[預先定義代理與內嵌代理](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#predefined-and-inline-agents)。

`"advisor": {"type": "enabled", "model": "<model id>"}` 為工作階段的主要執行緒提供一個可在回合中途諮詢的顧問。顧問是 `multiagent` (csharp, go: `Multiagent`) 區塊中的一項設定，而不是此清單中的項目。請參閱[為工作階段提供顧問](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#give-the-session-an-advisor)。

使用此類型時，動態工作流程也預設為啟用，因此此代理可以規劃在背景執行多個代理的大型工作。若要關閉它們，或列出工作流程可以使用的代理，請參閱[開啟動態工作流程](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows)。

以下規則適用於您在 `subagents` (csharp, go: `Subagents`) 的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單中列出的代理，也適用於您在 `workflows` (csharp, go: `Workflows`) 的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單中列出的代理：

* **固定版本：** 代理的設定，包括 `subagents` (csharp, go: `Subagents`) 的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單，會在代理建立或更新時建立快照。被參照的代理會固定在當時解析出的版本，不會套用其定義之後的更新。未傳送該清單的更新會保留已固定的版本。若要委派給被參照代理的較新版本，請[更新代理](https://platform.claude.com/docs/zh-TW/managed-agents/agent-setup#update-an-agent)，讓 `subagents` (csharp, go: `Subagents`) 的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單參照該版本。
* **一層：** 代理只能委派給一層代理。參照另一個已設定 `multiagent` (csharp, go: `Multiagent`) 的代理，會使建立或更新請求以 400 驗證錯誤失敗。
* **最多 20 個代理：** `subagents` (csharp, go: `Subagents`) 的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單最多可以列出 20 個不重複的代理。此限制是以清單為單位：`workflows` (csharp, go: `Workflows`) 的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單也最多可以列出 20 個。在工作階段的[執行緒限制](https://platform.claude.com/docs/zh-TW/managed-agents/session-threads)內，代理可以呼叫每個子代理的多個副本。
* **推論地理區域：** 代理以及您在 `subagents` (csharp, go: `Subagents`) 或 `workflows` (csharp, go: `Workflows`) 的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單中列出的每個代理，都必須固定相同的[推論地理區域](https://platform.claude.com/docs/zh-TW/manage-claude/data-residency)（[代理定義](https://platform.claude.com/docs/zh-TW/managed-agents/agent-setup)的 `model` (csharp, go: `Model`) 中的 `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`)），或者全部都不固定。任一清單中的不一致都會以 400 驗證錯誤被拒絕。此檢查會在儲存代理時執行，也會在[建立工作階段時的覆寫](https://platform.claude.com/docs/zh-TW/managed-agents/sessions#override-agent-configuration-for-a-session)變更任何固定設定時執行。

### 建立工作階段

建立一個參照該代理的工作階段。代理會視需要委派給您在 `subagents` (csharp, go: `Subagents`) 的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單中列出的代理。除非您將其關閉，否則它也可以委派給[內嵌代理](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#predefined-and-inline-agents)。

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -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 '{
      "agent": "'"$LEAD_AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  ant beta:sessions create \
    --agent "$LEAD_AGENT_ID" \
    --environment-id "$ENVIRONMENT_ID"
  ```

  ```python Python
  session = client.beta.sessions.create(
      agent=lead_agent.id,
      environment_id=environment.id,
  )
  ```

  ```typescript TypeScript
  const session = await client.beta.sessions.create({
    agent: leadAgent.id,
    environment_id: environment.id
  });
  ```

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = leadAgent.ID,
      EnvironmentID = environment.ID,
  });
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(leadAgent.ID),
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(leadAgent.id())
      .environmentId(environment.id())
      .build());
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: $leadAgent->id,
      environmentID: $environment->id,
  );
  ```

  ```ruby Ruby
  session = client.beta.sessions.create(
    agent: lead_agent.id,
    environment_id: environment.id
  )
  ```
</CodeGroup>

### 將代理連接到 MCP 伺服器

MCP 伺服器的範圍是以代理為單位：每個代理定義都會宣告自己的伺服器和工具。內嵌代理沒有代理定義，因此它使用工作階段所執行之代理的 MCP 伺服器和工具。保管庫憑證的範圍是以工作階段為單位：在建立工作階段時傳入的 `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`) 會套用到每個執行緒。這對您的整合有兩項影響：

* 若要驗證 MCP 伺服器，請為所有代理所使用的每個 MCP 伺服器提供保管庫憑證。
* 若要限制代理的存取權，請在其代理定義中只宣告它需要的伺服器。您無法以這種方式限制內嵌代理。若要只允許您列出的代理，請在 `subagents` (csharp, go: `Subagents`) 和 `workflows` (csharp, go: `Workflows`) 中都停用 `inline_agents` (java, php: `inlineAgents`; csharp, go: `InlineAgents`)，並在每一項中至少列出一個代理。請參閱[預先定義代理與內嵌代理](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#predefined-and-inline-agents)。

建立工作階段時的[代理設定覆寫](https://platform.claude.com/docs/zh-TW/managed-agents/sessions#override-agent-configuration-for-a-session)可以取代工作階段所執行代理及其 `self` 副本的 MCP 伺服器。

使用 `limited` [環境](https://platform.claude.com/docs/zh-TW/managed-agents/environments#networking)時，如果代理，或您在 `subagents` (csharp, go: `Subagents`) 或 `workflows` (csharp, go: `Workflows`) 的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單中列出的代理，宣告了主機不在 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 中的 MCP 伺服器，建立工作階段會以 400 錯誤失敗。在環境的網路設定中將 `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) 設為 `true` 可關閉此檢查。

建立宣告 GitHub MCP 伺服器的研究員代理，以及委派給研究員的代理：

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  # Create the researcher
  curl --fail-with-body -sS 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": "researcher",
      "model": "claude-haiku-5-5",
      "mcp_servers": [{"type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/"}],
      "tools": [{"type": "mcp_toolset", "mcp_server_name": "github"}]
    }'

  # Create the agent that delegates to it: research_agent_id is the id from the first response
  curl --fail-with-body -sS 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": "lead",
      "model": "claude-opus-5-5",
      "tools": [{"type": "agent_toolset_20260401"}],
      "multiagent": {
        "type": "multiagent_20261001",
        "subagents": {
          "type": "enabled",
          "predefined_agents": [{"type": "agent", "id": "'"$research_agent_id"'"}]
        }
      }
    }'
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply lead.md researcher.md
    ```

    <File filename="lead.md">
      ```markdown
      ---
      name: lead
      model: claude-opus-5-5
      tools:
        - type: agent_toolset_20260401
      multiagent:
        type: multiagent_20261001
        subagents:
          type: enabled
          predefined_agents: # ant apply replaces each path with {type: agent, id, version}
            - ./researcher.md
      ---
      ```
    </File>

    <File filename="researcher.md">
      ```markdown
      ---
      name: researcher
      model: claude-haiku-5-5
      mcp_servers:
        - type: url
          name: github
          url: https://api.githubcopilot.com/mcp/
      tools:
        - type: mcp_toolset
          mcp_server_name: github
      ---
      ```
    </File>
  </CodeGroupItem>

  ```python Python
  research_agent = client.beta.agents.create(
      name="researcher",
      model="claude-haiku-5-5",
      mcp_servers=[
          {"type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/"},
      ],
      tools=[{"type": "mcp_toolset", "mcp_server_name": "github"}],
  )

  lead_agent = client.beta.agents.create(
      name="lead",
      model="claude-opus-5-5",
      tools=[{"type": "agent_toolset_20260401"}],
      multiagent={
          "type": "multiagent_20261001",
          "subagents": {
              "type": "enabled",
              "predefined_agents": [{"type": "agent", "id": research_agent.id}],
          },
      },
  )
  ```

  ```typescript TypeScript
  const researchAgent = await client.beta.agents.create({
    name: "researcher",
    model: "claude-haiku-5-5",
    mcp_servers: [{ type: "url", name: "github", url: "https://api.githubcopilot.com/mcp/" }],
    tools: [{ type: "mcp_toolset", mcp_server_name: "github" }]
  });

  const leadAgent = await client.beta.agents.create({
    name: "lead",
    model: "claude-opus-5-5",
    tools: [{ type: "agent_toolset_20260401" }],
    multiagent: {
      type: "multiagent_20261001",
      subagents: {
        type: "enabled",
        predefined_agents: [{ type: "agent", id: researchAgent.id }]
      }
    }
  });
  ```

  ```csharp C#
  var researchAgent = await client.Beta.Agents.Create(new()
  {
      Name = "researcher",
      Model = BetaManagedAgentsModel.ClaudeHaiku5_5,
      McpServers =
      [
          new()
          {
              Type = BetaManagedAgentsUrlMcpServerParamsType.Url,
              Name = "github",
              Url = "https://api.githubcopilot.com/mcp/",
          },
      ],
      Tools =
      [
          new BetaManagedAgentsMcpToolsetParams
          {
              Type = BetaManagedAgentsMcpToolsetParamsType.McpToolset,
              McpServerName = "github",
          },
      ],
  });

  var leadAgent = await client.Beta.Agents.Create(new()
  {
      Name = "lead",
      Model = BetaManagedAgentsModel.ClaudeOpus5_5,
      Tools =
      [
          new BetaManagedAgentsAgentToolset20260401Params
          {
              Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401,
          },
      ],
      Multiagent = new BetaManagedAgentsMultiagent20261001Params
      {
          Subagents = new BetaManagedAgentsMultiagentSubagentsEnabledParams
          {
              PredefinedAgents =
              [
                  new BetaManagedAgentsAgentParams
                  {
                      Type = BetaManagedAgentsAgentParamsType.Agent,
                      ID = researchAgent.ID,
                  },
              ],
          },
      },
  });
  ```

  ```go Go
  researcher, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
  	Name:  "researcher",
  	Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeHaiku5_5},
  	MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{{
  		Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL,
  		Name: "github",
  		URL:  "https://api.githubcopilot.com/mcp/",
  	}},
  	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
  		OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{
  			Type:          anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset,
  			MCPServerName: "github",
  		},
  	}},
  })
  if err != nil {
  	panic(err)
  }

  leadAgent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
  	Name:  "lead",
  	Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5},
  	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
  		OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
  			Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
  		},
  	}},
  	Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{
  		OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{
  			Subagents: anthropic.BetaManagedAgentsMultiagentSubagentsParamsUnion{
  				OfEnabled: &anthropic.BetaManagedAgentsMultiagentSubagentsEnabledParams{
  					PredefinedAgents: []anthropic.BetaManagedAgentsMultiagentPredefinedAgentParamsUnion{{
  						OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{
  							Type: anthropic.BetaManagedAgentsAgentParamsTypeAgent,
  							ID:   researcher.ID,
  						},
  					}},
  				},
  			},
  		},
  	},
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var researcher = client.beta().agents().create(
      AgentCreateParams.builder()
          .name("researcher")
          .model(BetaManagedAgentsModel.CLAUDE_HAIKU_5_5)
          .addMcpServer(BetaManagedAgentsUrlMcpServerParams.builder()
              .name("github")
              .type(BetaManagedAgentsUrlMcpServerParams.Type.URL)
              .url("https://api.githubcopilot.com/mcp/")
              .build())
          .addTool(BetaManagedAgentsMcpToolsetParams.builder()
              .type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET)
              .mcpServerName("github")
              .build())
          .build()
  );

  var leadAgent = client.beta().agents().create(
      AgentCreateParams.builder()
          .name("lead")
          .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
          .addTool(BetaManagedAgentsAgentToolset20260401Params.builder()
              .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
              .build())
          .multiagent(BetaManagedAgentsMultiagent20261001Params.builder()
              .subagents(BetaManagedAgentsMultiagentSubagentsEnabledParams.builder()
                  .addPredefinedAgent(BetaManagedAgentsAgentParams.builder()
                      .type(BetaManagedAgentsAgentParams.Type.AGENT)
                      .id(researcher.id())
                      .build())
                  .build())
              .build())
          .build()
  );
  ```

  ```php PHP
  $researchAgent = $client->beta->agents->create(
      name: 'researcher',
      model: 'claude-haiku-5-5',
      mcpServers: [
          ['type' => 'url', 'name' => 'github', 'url' => 'https://api.githubcopilot.com/mcp/'],
      ],
      tools: [
          ['type' => 'mcp_toolset', 'mcp_server_name' => 'github'],
      ],
  );

  $leadAgent = $client->beta->agents->create(
      name: 'lead',
      model: 'claude-opus-5-5',
      tools: [
          ['type' => 'agent_toolset_20260401'],
      ],
      multiagent: [
          'type' => 'multiagent_20261001',
          'subagents' => [
              'type' => 'enabled',
              'predefined_agents' => [
                  ['type' => 'agent', 'id' => $researchAgent->id],
              ],
          ],
      ],
  );
  ```

  ```ruby Ruby
  research_agent = client.beta.agents.create(
    name: "researcher",
    model: "claude-haiku-5-5",
    mcp_servers: [
      {type: "url", name: "github", url: "https://api.githubcopilot.com/mcp/"}
    ],
    tools: [
      {type: "mcp_toolset", mcp_server_name: "github"}
    ]
  )

  lead_agent = client.beta.agents.create(
    name: "lead",
    model: "claude-opus-5-5",
    tools: [
      {type: "agent_toolset_20260401"}
    ],
    multiagent: {
      type: "multiagent_20261001",
      subagents: {
        type: "enabled",
        predefined_agents: [
          {type: "agent", id: research_agent.id}
        ]
      }
    }
  )
  ```
</CodeGroup>

接著使用存放 GitHub 憑證的保管庫建立工作階段：

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS https://api.anthropic.com/v1/sessions \
    -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 '{
      "agent": "'"$lead_agent_id"'",
      "environment_id": "'"$environment_id"'",
      "vault_ids": ["'"$vault_id"'"]
    }'
  ```

  ```bash CLI
  ant beta:sessions create \
    --agent "$lead_agent_id" \
    --environment-id "$environment_id" \
    --vault-id "$vault_id"
  ```

  ```python Python
  session = client.beta.sessions.create(
      agent=lead_agent.id,
      environment_id=environment.id,
      vault_ids=[vault.id],
  )
  print(session.id)
  ```

  ```typescript TypeScript
  const session = await client.beta.sessions.create({
    agent: leadAgent.id,
    environment_id: environment.id,
    vault_ids: [vault.id]
  });
  console.log(session.id);
  ```

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = leadAgent.ID,
      EnvironmentID = environment.ID,
      VaultIds = [vault.ID],
  });
  Console.WriteLine(session.ID);
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(leadAgent.ID),
  	},
  	EnvironmentID: environment.ID,
  	VaultIDs:      []string{vault.ID},
  })
  if err != nil {
  	panic(err)
  }
  fmt.Println(session.ID)
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(leadAgent.id())
      .environmentId(environment.id())
      .vaultIds(List.of(vault.id()))
      .build());
  IO.println(session.id());
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: $leadAgent->id,
      environmentID: $environment->id,
      vaultIDs: [$vault->id],
  );
  echo "{$session->id}\n";
  ```

  ```ruby Ruby
  session = client.beta.sessions.create(
    agent: lead_agent.id,
    environment_id: environment.id,
    vault_ids: [vault.id]
  )
  puts session.id
  ```
</CodeGroup>

在此範例中，只有研究員宣告了 GitHub MCP 伺服器，因此工作階段所執行的代理沒有存取權。工作階段的 `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`) 會將 GitHub 憑證提供給研究員的執行緒。

<Tip>
  如果在您宣告伺服器後，代理的 MCP 呼叫仍無法通過驗證，請確認憑證的 `mcp_server_url` (java: `mcpServerUrl`; php: `mcpServerURL`; csharp: `McpServerUrl`; go: `MCPServerURL`) 與代理的 `mcp_servers[].url` (java, php: `mcpServers[].url`; csharp: `McpServers[].Url`; go: `MCPServers[].URL`) 指向同一個伺服器。兩個 URL 在比對前都會經過正規化（scheme 和主機轉為小寫，並移除預設連接埠和結尾斜線），因此主機大小寫、預設連接埠或結尾斜線的差異不會妨礙比對；但不同的路徑、子網域或非預設連接埠則會。
</Tip>

### 執行緒

每個代理的工作階段執行緒都有自己的事件串流。若要列出、中斷或封存執行緒、讀取其事件，以及跨執行緒處理工具權限，請參閱[工作階段執行緒](https://platform.claude.com/docs/zh-TW/managed-agents/session-threads)。

## 動態工作流程

透過動態工作流程，代理可以承擔包含許多部分的工作，例如審查數百份文件或交叉核對許多來源。代理會撰寫一個 **workflow**（工作流程）：一個分階段執行許多代理並合併其回傳內容的程式。伺服器會在背景將其作為 **workflow run**（工作流程執行）來運行，同時代理可以繼續工作或結束其回合。您可以透過代理 `multiagent` (csharp, go: `Multiagent`) 區塊中的 `workflows` (csharp, go: `Workflows`) 設定來開啟或關閉動態工作流程。執行中的代理可以同時工作，因此長時間任務可以比由一個代理依序處理每個部分更快完成。

* **執行如何開始：** 您在 `user.message` 中描述工作。代理會據此決定是否以及何時啟動執行，因此不需要額外的 API 呼叫。您可以改為在 `user.message` 或代理的系統提示中描述何時使用執行，以影響代理的判斷。（權限政策適用於執行中的代理所呼叫的工具，而不適用於啟動執行本身。）
* **它使用哪些代理：** 由工作流程定義的[內嵌代理](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#predefined-and-inline-agents)、您在 `workflows` (csharp, go: `Workflows`) 的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單中列出的預先定義代理，或兩者皆有。如果您沒有列出任何代理，工作流程會定義所有代理。內嵌代理使用工作階段所執行之代理的模型。若要讓執行中的部分代理使用其他模型，請將它們建立為代理，並列在 `workflows` (csharp, go: `Workflows`) 的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單中。
* **如何追蹤它：** 執行事件會出現在工作階段的事件串流上，而執行中的每個代理都在一個您可以列出、讀取和串流的[工作階段執行緒](https://platform.claude.com/docs/zh-TW/managed-agents/session-threads)中運作。關於事件、中斷、[限制](https://platform.claude.com/docs/zh-TW/managed-agents/workflow-runs#limits)以及[執行的執行緒會顯示什麼](https://platform.claude.com/docs/zh-TW/managed-agents/workflow-runs#a-runs-threads)，請參閱[工作流程執行](https://platform.claude.com/docs/zh-TW/managed-agents/workflow-runs)。

### 開啟動態工作流程

在[定義您的代理](https://platform.claude.com/docs/zh-TW/managed-agents/agent-setup)時，將 `multiagent.type` 設為 `"multiagent_20261001"` 並啟用 `workflows`。使用此類型時，動態工作流程與委派（`subagents`）預設皆為開啟。若只要使用動態工作流程，請加入 `"subagents": {"type": "disabled"}`。

在變更現有代理的 `multiagent.type` 之前，請參閱[如何將代理移轉至此類型](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#move-from-the-coordinator-type)。

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  curl -fsS 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": "Contract Reviewer",
      "model": "claude-opus-5-5",
      "system": "You review contracts. When you are asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.",
      "tools": [{"type": "agent_toolset_20260401"}],
      "multiagent": {"type": "multiagent_20261001", "workflows": {"type": "enabled"}}
    }'
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply contract-reviewer.md
    ```

    <File filename="contract-reviewer.md">
      ```markdown
      ---
      name: Contract Reviewer
      model: claude-opus-5-5
      tools:
        - type: agent_toolset_20260401
      multiagent:
        type: multiagent_20261001
        workflows:
          type: enabled
      ---

      You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.
      ```
    </File>
  </CodeGroupItem>

  ```python Python
  agent = client.beta.agents.create(
      name="Contract Reviewer",
      model="claude-opus-5-5",
      system="You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.",
      tools=[{"type": "agent_toolset_20260401"}],
      multiagent={"type": "multiagent_20261001", "workflows": {"type": "enabled"}},
  )
  ```

  ```typescript TypeScript
  const agent = await client.beta.agents.create({
    name: "Contract Reviewer",
    model: "claude-opus-5-5",
    system:
      "You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.",
    tools: [{ type: "agent_toolset_20260401" }],
    multiagent: { type: "multiagent_20261001", workflows: { type: "enabled" } }
  });
  ```

  ```csharp C#
  var agent = await client.Beta.Agents.Create(new()
  {
      Name = "Contract Reviewer",
      Model = BetaManagedAgentsModel.ClaudeOpus5_5,
      System = "You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.",
      Tools =
      [
          new BetaManagedAgentsAgentToolset20260401Params
          {
              Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401,
          },
      ],
      // 設定類別會為您設定類型。
      Multiagent = new BetaManagedAgentsMultiagent20261001Params
      {
          Workflows = new BetaManagedAgentsMultiagentWorkflowsEnabledParams(),
      },
  });
  ```

  ```go Go
  agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
  	Name:   "Contract Reviewer",
  	Model:  anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5},
  	System: anthropic.String("You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run."),
  	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
  		OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
  			Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
  		},
  	}},
  	Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{
  		OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{
  			Workflows: anthropic.BetaManagedAgentsMultiagentWorkflowsParamsUnion{
  				OfEnabled: &anthropic.BetaManagedAgentsMultiagentWorkflowsEnabledParams{},
  			},
  		},
  	},
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var agent = client.beta().agents().create(
      AgentCreateParams.builder()
          .name("Contract Reviewer")
          .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
          .system("You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.")
          .addTool(
              BetaManagedAgentsAgentToolset20260401Params.builder()
                  .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
                  .build()
          )
          // 設定類別會為您設定類型。
          .multiagent(BetaManagedAgentsMultiagent20261001Params.builder()
              .workflows(BetaManagedAgentsMultiagentWorkflowsEnabledParams.builder().build())
              .build())
          .build()
  );
  ```

  ```php PHP
  $agent = $client->beta->agents->create(
      name: 'Contract Reviewer',
      model: 'claude-opus-5-5',
      system: "You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.",
      tools: [
          ['type' => 'agent_toolset_20260401'],
      ],
      multiagent: ['type' => 'multiagent_20261001', 'workflows' => ['type' => 'enabled']],
  );
  ```

  ```ruby Ruby
  agent = client.beta.agents.create(
    name: "Contract Reviewer",
    model: "claude-opus-5-5",
    system_: "You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.",
    tools: [
      {type: "agent_toolset_20260401"}
    ],
    multiagent: {type: "multiagent_20261001", workflows: {type: "enabled"}}
  )
  ```
</CodeGroup>

若要讓工作流程使用您已建立的代理，請將它們列在 `workflows.predefined_agents` 中。`subagents` 與 `advisor` 設定放在同一個 `multiagent` 區塊中。若要列出子代理，請參閱[委派給子代理](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#delegate-to-subagents)。若要設定顧問，請參閱[為工作階段提供顧問](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#give-the-session-an-advisor)。此代理讓工作流程使用一個您建立的代理、列出兩個子代理，並具有一個顧問：

```json
{
  "multiagent": {
    "type": "multiagent_20261001",
    "workflows": {
      "type": "enabled",
      "predefined_agents": [{ "type": "agent", "id": "agent_01Lm4cV8yQ2tNs7XbKdR5h" }]
    },
    "subagents": {
      "type": "enabled",
      "predefined_agents": [
        { "type": "agent", "id": "agent_01J8XkN5uT3vHpLqRfWdY2" },
        { "type": "agent", "id": "agent_01HqR2k7vXbZ9mNpL3wYcT" }
      ]
    },
    "advisor": { "type": "enabled", "model": "claude-opus-5-5" }
  }
}
```

每項設定都可個別啟用或停用：

| 設定          | 開啟的功能                     | 代理放置位置                                | 預設值 |
| ----------- | ------------------------- | ------------------------------------- | --- |
| `workflows` | 動態工作流程                    | `workflows.predefined_agents`，最多 20 個 | 已啟用 |
| `subagents` | 委派給子代理：您列出的代理，以及代理自行定義的代理 | `subagents.predefined_agents`，最多 20 個 | 已啟用 |
| `advisor`   | 顧問模型                      | 無。請設定 `model`。                        | 已停用 |

關於每個清單中應放入的內容，以及如何只允許您列出的代理，請參閱[預先定義代理與內嵌代理](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#predefined-and-inline-agents)。

請留意以下事項：

* **更新：** 保留 `multiagent_20261001` 類型的更新只會變更其所傳送的內容：

  * 您省略的設定或欄位會保留其已儲存的值。
  * 您以 `null` 傳送的設定或欄位會採用其預設值，其內部的所有內容也是如此，無論您先前儲存了什麼。
  * 您傳送的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單會取代已儲存的清單。
  * 您以不同 `type` 傳送的設定會取代已儲存的設定，而您在其中省略的欄位會採用其預設值。
  * 您傳送的每個物件都需要其 `type`，而已啟用的 `advisor` 需要其 `model`。

* **關閉功能：** 將 `workflows` 設為 `{"type": "disabled"}`。它會保持關閉，直到某次更新再次將其開啟。傳送 `null` 會將其開啟，因為其預設值為已啟用。`subagents` 也適用相同規則。

* **現有工作階段：** 工作階段會在建立時複製設定，因此之後變更代理不會改變已存在的工作階段。

* **可列出的代理：** 已設定 `multiagent` (csharp, go: `Multiagent`) 的代理，不能被列為另一個代理的子代理，也不能列在另一個代理的 `workflows` (csharp, go: `Workflows`) 的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單中。代理可以使用 `{"type": "self"}` 在任一清單中列出自己，讀回時會顯示為其自身的 `id` 與 `version`。

* **工具名稱：** `ant__` 前綴為保留字。如果您的代理已有名稱以 `ant__` 開頭的自訂工具，更新會以 400 錯誤失敗，直到您傳送不含該名稱的 `tools` (csharp, go: `Tools`)。如果新工作階段的代理，或任一清單中的代理具有此類工具，該工作階段也會以 400 錯誤被拒絕。請在開啟動態工作流程的同一次更新中重新命名或移除該工具。請參閱[自訂工具](https://platform.claude.com/docs/zh-TW/managed-agents/tools#custom-tools)。

* **預算：** 在建立工作階段時設定[工作階段預算](https://platform.claude.com/docs/zh-TW/managed-agents/budgets)，以限制工作階段的支出（包含執行）；您無法為現有工作階段新增預算。當工作階段達到預算時，執行會暫停；當您提高或移除預算時，因預算而暫停的執行會恢復，除非它們也因中斷而暫停。請參閱[成本與預算](https://platform.claude.com/docs/zh-TW/managed-agents/workflow-runs#cost-and-budgets)。

### 告訴代理何時使用執行

開啟動態工作流程後，代理便能啟動工作流程執行。由代理決定何時啟動執行。若要引導此選擇，請在代理的系統提示中加入類似以下的指示。[開啟動態工作流程](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows)中的合約審查代理使用此系統提示：

```text wrap
You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.
```

若要調整它，請指出您代理領域中需要啟動工作流程執行的任務，以及代理應自行完成的小型任務。您也可以引導執行如何完成工作，如以下範例所示：

* **如何拆分工作：**「在執行中，每份合約使用一個代理。然後讓第二個代理審查每一份合約，而不只是第一個代理有發現問題的合約，並找出第一個代理遺漏的內容。任何未通過審查的項目都要重做並再次審查。」
* **代理失敗時該怎麼做：**「一個代理失敗不得導致整個執行失敗。如果某個代理無法讀取某份合約，請將該合約列為未涵蓋。執行結束時，告訴我哪些合約未被涵蓋。」
* **時間限制：**「為執行設定一小時的時間限制。」
* **先規劃：**「在開始執行之前，描述其各個階段以及每個階段執行多少個代理。然後等待我的同意。」執行開始前沒有核准步驟，因此沒有任何機制強制執行這一點。

請只在需要的任務上使用執行，因為執行中的每個代理都會消耗 token。

接著，如同使用任何代理一樣，以該代理[建立工作階段](https://platform.claude.com/docs/zh-TW/managed-agents/sessions)，並在 `user.message` 中描述工作。您也可以在該訊息中要求啟動執行。

關於執行的事件、在有開啟中執行時中斷工作階段、執行開啟期間會有哪些變化，以及預算與限制，請參閱[工作流程執行](https://platform.claude.com/docs/zh-TW/managed-agents/workflow-runs)。

## 為工作階段提供顧問

代理的 `multiagent` (csharp, go: `Multiagent`) 區塊中已啟用的 `advisor` 設定，會為工作階段的主要執行緒提供一個 **advisor**（顧問）：一個它可以在回合中途諮詢以取得策略性指引的模型，例如規劃方法、擺脫困境，或在完成前審查工作。此設定預設為停用。若要啟用，請將 `advisor` 設為 `{"type": "enabled", "model": "..."}`，它恰好有兩個欄位：`type` 與 `model`：

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  curl -fsS 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": "Backend engineer",
      "model": "claude-sonnet-5",
      "system": "You implement backend features end to end. Consult the advisor before major backend design decisions.",
      "multiagent": {
        "type": "multiagent_20261001",
        "advisor": {"type": "enabled", "model": "claude-opus-5-5"}
      }
    }'
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply backend-engineer.md
    ```

    <File filename="backend-engineer.md">
      ```markdown
      ---
      name: Backend engineer
      model: claude-sonnet-5
      multiagent:
        type: multiagent_20261001
        advisor:
          type: enabled
          model: claude-opus-5-5
      ---

      You implement backend features end to end. Consult the advisor before major backend design decisions.
      ```
    </File>
  </CodeGroupItem>

  ```python Python
  agent = client.beta.agents.create(
      name="Backend engineer",
      model="claude-sonnet-5",
      system="You implement backend features end to end. Consult the advisor before major backend design decisions.",
      multiagent={
          "type": "multiagent_20261001",
          "advisor": {"type": "enabled", "model": "claude-opus-5-5"},
      },
  )
  print(agent.id)
  ```

  ```typescript TypeScript
  const agent = await client.beta.agents.create({
    name: "Backend engineer",
    model: "claude-sonnet-5",
    system:
      "You implement backend features end to end. Consult the advisor before major backend design decisions.",
    multiagent: {
      type: "multiagent_20261001",
      advisor: { type: "enabled", model: "claude-opus-5-5" }
    }
  });
  console.log(agent.id);
  ```

  ```csharp C#
  var agent = await client.Beta.Agents.Create(new()
  {
      Name = "Backend engineer",
      Model = BetaManagedAgentsModel.ClaudeSonnet5,
      System = "You implement backend features end to end. Consult the advisor before major backend design decisions.",
      Multiagent = new BetaManagedAgentsMultiagent20261001Params
      {
          Advisor = new BetaManagedAgentsMultiagentAdvisorEnabledParams { Model = "claude-opus-5-5" },
      },
  });
  Console.WriteLine(agent.ID);
  ```

  ```go Go
  agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
  	Name:   "Backend engineer",
  	Model:  anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeSonnet5},
  	System: anthropic.String("You implement backend features end to end. Consult the advisor before major backend design decisions."),
  	Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{
  		OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{
  			Advisor: anthropic.BetaManagedAgentsMultiagentAdvisorParamsUnion{
  				OfEnabled: &anthropic.BetaManagedAgentsMultiagentAdvisorEnabledParams{
  					Model: "claude-opus-5-5",
  				},
  			},
  		},
  	},
  })
  if err != nil {
  	panic(err)
  }
  fmt.Println(agent.ID)
  ```

  ```java Java
  var agent = client.beta().agents().create(
      AgentCreateParams.builder()
          .name("Backend engineer")
          .model(BetaManagedAgentsModel.CLAUDE_SONNET_5)
          .system("You implement backend features end to end. Consult the advisor before major backend design decisions.")
          .multiagent(BetaManagedAgentsMultiagent20261001Params.builder()
              .advisor(BetaManagedAgentsMultiagentAdvisorEnabledParams.builder()
                  .model("claude-opus-5-5")
                  .build())
              .build())
          .build()
  );
  IO.println(agent.id());
  ```

  ```php PHP
  $agent = $client->beta->agents->create(
      name: 'Backend engineer',
      model: 'claude-sonnet-5',
      system: 'You implement backend features end to end. Consult the advisor before major backend design decisions.',
      multiagent: [
          'type' => 'multiagent_20261001',
          'advisor' => ['type' => 'enabled', 'model' => 'claude-opus-5-5'],
      ],
  );
  echo $agent->id, PHP_EOL;
  ```

  ```ruby Ruby
  agent = client.beta.agents.create(
    name: "Backend engineer",
    model: "claude-sonnet-5",
    system_: "You implement backend features end to end. Consult the advisor before major backend design decisions.",
    multiagent: {
      type: "multiagent_20261001",
      advisor: {type: "enabled", model: "claude-opus-5-5"}
    }
  )
  puts agent.id
  ```
</CodeGroup>

此範例只設定 `advisor` (csharp, go: `Advisor`)。另外兩項設定 `subagents` (csharp, go: `Subagents`) 與 `workflows` (csharp, go: `Workflows`) 保留其預設值，因此兩者皆為啟用，代理也可以委派給內嵌代理並啟動工作流程執行。若要讓代理諮詢顧問並自行完成所有工作，請將兩者都設為 `{"type": "disabled"}`。

您不能將顧問列在 `subagents` (csharp, go: `Subagents`) 或 `workflows` (csharp, go: `Workflows`) 的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單中。已啟用的 `advisor` (csharp, go: `Advisor`) 會保留名稱 `anthropic.advisor`。在其啟用期間，兩個清單都不能包含名稱恰為 `anthropic.advisor` 的代理：該請求會以 400 驗證錯誤被拒絕。

顧問模型必須達到最低能力門檻，且代理本身的模型不得比其顧問更強；能力相同的模型可以配對。無效的配對會在儲存代理時以 400 驗證錯誤被拒絕，建立工作階段時也會再次被拒絕。每次諮詢開始時也會檢查配對：如果配對已不再有效，該次諮詢會失敗，而工作階段會繼續進行。有效的配對遵循顧問工具的[模型相容性](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/advisor-tool#model-compatibility)表格。

顧問也可作為 [Messages API 上的伺服器工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/advisor-tool)使用。Managed Agents 介面在設定與傳遞方式上有所不同：`advisor` (csharp, go: `Advisor`) 設定沒有 `max_uses`、`max_tokens` 或 `caching` 欄位，且建議是透過執行緒事件傳遞，而非 `advisor_tool_result` 區塊。

### 諮詢的運作方式

每次諮詢都會以平台產生、名為 `anthropic.advisor` 的執行緒執行，該執行緒會在諮詢完成時自行終止，而建議會以 `agent.thread_message_received` 事件傳遞給主要執行緒。諮詢會發出標準的執行緒事件，並以保留名稱 `anthropic.advisor` 識別（執行緒生命週期事件以 `agent_name` (java, php: `agentName`; csharp, go: `AgentName`) 攜帶此名稱，而建議傳遞則以 `from_agent_name` (java, php: `fromAgentName`; csharp, go: `FromAgentName`) 攜帶），通常依以下順序：

1. `session.thread_created`
2. `session.thread_status_running`
3. `agent.thread_message_received`（建議）
4. `session.thread_status_idle`（`stop_reason: end_turn`）
5. `session.thread_status_terminated`

諮詢不會發出 `agent.tool_use` 事件，工作階段的事件串流上也不會出現 `agent.thread_message_sent` 事件，因為諮詢輸入是由平台組成，而非由代理傳送。如果您列出顧問執行緒本身的事件，建議也會以 `agent.thread_message_sent` 事件出現在那裡。建議傳遞（事件 3）不保證會在顧問執行緒的閒置與終止事件之前抵達，因此請勿將這些事件視為建議已傳遞的訊號。

您的用戶端是否能讀取建議，取決於顧問模型的政策。這與 Messages API 顧問工具上的[結果變體](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/advisor-tool#result-variants)區分相對應。在該處回傳純文字結果的顧問模型，在此會傳遞可讀的文字。回傳遮蔽結果的模型，則會在每個用戶端介面上傳遞 `[{"type": "redacted"}]` 佔位符，而代理仍會在伺服器端讀取完整建議。前述範例使用您可用的最新 Opus 模型作為顧問。Claude Opus 5.5 會回傳遮蔽結果，因此您的用戶端只會看到佔位符。若要在事件串流上讀取建議，請使用回傳純文字的顧問，例如 Claude Opus 4.8。模型的政策可能在 API 未變更的情況下改變，因此請同時處理 `text` 與 `redacted` 區塊。某些代理模型只能與回傳遮蔽結果的顧問配對；請參閱顧問工具的[相容性表格](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/advisor-tool#model-compatibility)。顧問的思考內容永遠不會公開。用戶端無法自行傳送 `redacted` 區塊；包含此類區塊的事件會以 400 驗證錯誤被拒絕。

失敗或被中斷的諮詢絕不會導致代理的回合失敗：代理會在收到諮詢失敗的一般通知後繼續。在諮詢期間發出工作階段層級的 `user.interrupt`，會終止顧問執行緒且不傳遞任何建議；帶有顧問執行緒 `session_thread_id` (java: `sessionThreadId`; php: `sessionThreadID`; csharp, go: `SessionThreadID`) 的 `user.interrupt` 只會放棄該次諮詢。

### 顧問執行緒

顧問不是子代理。代理的 `list_agents` 工具不會顯示它，而用於向子代理傳送後續訊息的 `send_to_agent` 也無法觸及它。只有工作階段的主要執行緒可以諮詢它；子代理則不行。

顧問執行緒不受 25 個子執行緒的限制。它們會出現在工作階段的[執行緒清單](https://platform.claude.com/docs/zh-TW/managed-agents/session-threads)中。它們的 `agent` 為顧問形式 `{"type": "advisor", "model": ...}`，其中包含您設定的模型，而它們的 `parent_thread_id` 為主要執行緒。

顧問端的提示快取是自動進行的；無需任何設定。諮詢會依顧問模型的費率計費，其 token 會出現在顧問執行緒的用量以及工作階段的用量總計中。它們也會以顧問模型的定價計入[工作階段預算](https://platform.claude.com/docs/zh-TW/managed-agents/budgets)。每次諮詢都會將主要執行緒至今的對話傳送給顧問，因此在長時間工作階段後期的諮詢會使用更多輸入 token。

### 移除顧問

若要移除顧問，請以設為 `{"type": "disabled"}` 的 `advisor` [更新代理](https://platform.claude.com/docs/zh-TW/managed-agents/agent-setup#update-an-agent)。在已具有 `multiagent_20261001` 類型的代理上，更新中省略的設定會保留其已儲存的值，因此您不需要再次傳送 `subagents` 或 `workflows`。基於同樣的原因，省略 `advisor` 的更新會保留顧問。在變更現有代理的 `multiagent.type` 之前，請參閱[如何將代理移轉至此類型](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#move-from-the-coordinator-type)。

## 從 `coordinator` 類型移轉

與 `multiagent_20261001` 一樣，`coordinator` 類型讓代理可以委派給您列出的子代理，並諮詢顧問模型。使用 `coordinator` 類型時，代理無法啟動工作流程執行，也無法自行定義子代理。API 接受這兩種類型。

若要將代理移轉至 `multiagent_20261001`，請以該類型的 `multiagent` 區塊[更新代理](https://platform.claude.com/docs/zh-TW/managed-agents/agent-setup#update-an-agent)：

1. 將 `type` 設為 `"multiagent_20261001"`。
2. 在 `subagents.predefined_agents` 中列出代理可以呼叫的代理。這些項目保留其目前的形式。
3. 如果代理有顧問，請將 `advisor` 設為 `{"type": "enabled", "model": "..."}`，並填入顧問的模型。
4. 在一次更新中傳送整個區塊。

例如，此區塊為代理提供兩個子代理與一個顧問：

```json
{
  "multiagent": {
    "type": "multiagent_20261001",
    "subagents": {
      "type": "enabled",
      "predefined_agents": [
        { "type": "agent", "id": "agent_01J8XkN5uT3vHpLqRfWdY2" },
        { "type": "agent", "id": "agent_01HqR2k7vXbZ9mNpL3wYcT" }
      ]
    },
    "advisor": { "type": "enabled", "model": "claude-opus-5-5" }
  }
}
```

該區塊省略了 `workflows` 與 `subagents.inline_agents`，因此兩者都採用其預設值並為啟用狀態。移轉後的代理也可以啟動工作流程執行並自行定義子代理。若要讓其中任一項保持關閉，請在同一次更新中將其設為 `{"type": "disabled"}`。請參閱[開啟動態工作流程](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows)與[預先定義代理與內嵌代理](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#predefined-and-inline-agents)。

如果代理有顧問但沒有子代理，請將 `subagents` 設為 `{"type": "disabled"}` 以保持委派關閉。停用 `subagents.inline_agents` 且未列出任何代理的請求會以 400 錯誤失敗。

此更新會取代整個 `multiagent` 區塊，因此請如範例所示，再次傳送代理清單與顧問。您省略的內容會採用其預設值：

* **`subagents.predefined_agents`：** 清單為空，因此代理會失去您列出的子代理。
* **`advisor`：** 顧問會被停用。

一旦代理具有 `multiagent_20261001` 類型，之後更新中省略的設定就會保留其已儲存的值。

此更新不會變更已存在的工作階段。若要使用新區塊，請在更新後建立工作階段。