---
title: 啟動工作階段
url: https://platform.claude.com/docs/zh-TW/managed-agents/sessions
description: 建立工作階段以執行您的代理並開始執行任務。
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
---

「Session」（工作階段）是環境中的一個代理實例。每個工作階段都會參照一個[代理](https://platform.claude.com/docs/zh-TW/managed-agents/agent-setup)和一個[環境](https://platform.claude.com/docs/zh-TW/managed-agents/environments)（兩者皆需分別建立），並在多次互動之間維護對話歷史記錄。工作階段遵循兩步驟的生命週期：首先[建立工作階段](https://platform.claude.com/docs/zh-TW/managed-agents/sessions#creating-a-session)，然後[傳送使用者事件](https://platform.claude.com/docs/zh-TW/managed-agents/sessions#starting-the-session)以開始工作。您也可以使用 [`initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`)](https://platform.claude.com/docs/zh-TW/managed-agents/sessions#seed-the-session-with-initial-events) 將這兩個步驟合併為一次呼叫。

## 建立工作階段

工作階段需要一個 `agent` ID 和一個 `environment` ID。代理是具有版本的資源；以字串形式傳入 `agent` (csharp, go: `Agent`) ID 時，會使用最新的代理版本建立工作階段。

<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": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

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

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

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

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

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

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

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

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

若要將工作階段固定到特定的代理版本，請傳入一個物件。這讓您能精確控制要執行哪個版本，並獨立地分階段推出新版本。

<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": {"type": "agent", "id": "'"$AGENT_ID"'", "version": 1},
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  ant beta:sessions create <<YAML
  agent:
    type: agent
    id: $AGENT_ID
    version: 1
  environment_id: $ENVIRONMENT_ID
  YAML
  ```

  ```python Python
  pinned_session = client.beta.sessions.create(
      agent={"type": "agent", "id": agent.id, "version": 1},
      environment_id=environment.id,
  )
  ```

  ```typescript TypeScript
  const pinnedSession = await client.beta.sessions.create({
    agent: { type: "agent", id: agent.id, version: 1 },
    environment_id: environment.id
  });
  ```

  ```csharp C#
  var pinnedSession = await client.Beta.Sessions.Create(new()
  {
      Agent = new BetaManagedAgentsAgentParams
      {
          Type = BetaManagedAgentsAgentParamsType.Agent,
          ID = agent.ID,
          Version = 1,
      },
      EnvironmentID = environment.ID,
  });
  ```

  ```go Go
  pinnedSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{
  			Type:    anthropic.BetaManagedAgentsAgentParamsTypeAgent,
  			ID:      agent.ID,
  			Version: anthropic.Int(1),
  		},
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var pinnedSession = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(BetaManagedAgentsAgentParams.builder()
          .type(BetaManagedAgentsAgentParams.Type.AGENT)
          .id(agent.id())
          .version(1)
          .build())
      .environmentId(environment.id())
      .build());
  ```

  ```php PHP
  $pinnedSession = $client->beta->sessions->create(
      agent: ['type' => 'agent', 'id' => $agent->id, 'version' => 1],
      environmentID: $environment->id,
  );
  ```

  ```ruby Ruby
  pinned_session = client.beta.sessions.create(
    agent: {type: :agent, id: agent.id, version: 1},
    environment_id: environment.id
  )
  ```
</CodeGroup>

### 以初始事件預先填入工作階段

您可以在一次呼叫中建立工作階段並開始其工作。`initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) 是一個選用的初始[事件](https://platform.claude.com/docs/zh-TW/managed-agents/reference#event-types)陣列，會在建立時傳送至工作階段，並依序處理。它支援 `user.message` 和 [`user.define_outcome`](https://platform.claude.com/docs/zh-TW/managed-agents/define-outcomes) 事件，最多接受 50 個事件。非空的清單會在同一次呼叫中啟動代理迴圈：工作階段會直接以 `running` 狀態建立，無需再發出其他請求。

以下範例在 `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) 中使用單一 `user.message` 建立工作階段：

<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": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'",
      "initial_events": [
        {
          "type": "user.message",
          "content": [{"type": "text", "text": "List the files in the working directory."}]
        }
      ]
    }'
  ```

  ```bash CLI
  ant beta:sessions create <<YAML
  agent: $AGENT_ID
  environment_id: $ENVIRONMENT_ID
  initial_events:
    - type: user.message
      content:
        - type: text
          text: List the files in the working directory.
  YAML
  ```

  ```python Python
  seeded_session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
      initial_events=[
          {
              "type": "user.message",
              "content": [
                  {"type": "text", "text": "List the files in the working directory."}
              ],
          },
      ],
  )
  # initial_events 不會在建立回應中回傳；請從
  # session 的事件清單中讀回。
  for event in client.beta.sessions.events.list(seeded_session.id):
      if event.type == "user.message":
          for block in event.content:
              if block.type == "text":
                  print(f"Seeded event: {block.text}")
  ```

  ```typescript TypeScript
  const seededSession = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id,
    initial_events: [
      {
        type: "user.message",
        content: [{ type: "text", text: "List the files in the working directory." }]
      }
    ]
  });

  // initial_events 不會在建立回應中回傳；需列出 session 的
  // 事件才能讀回預先植入的訊息。
  for await (const event of client.beta.sessions.events.list(seededSession.id)) {
    if (event.type === "user.message") {
      for (const block of event.content) {
        if (block.type === "text") {
          console.log(`Seeded event: ${block.text}`);
        }
      }
    }
  }
  ```

  ```csharp C#
  var seededSession = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      InitialEvents =
      [
          new BetaManagedAgentsUserMessageEventParams
          {
              Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
              Content =
              [
                  new BetaManagedAgentsTextBlock
                  {
                      Type = BetaManagedAgentsTextBlockType.Text,
                      Text = "List the files in the working directory.",
                  },
              ],
          },
      ],
  });
  // initial_events 不會在建立回應中回傳；請從
  // session 的事件清單中讀回。
  var seededEvents = await client.Beta.Sessions.Events.List(seededSession.ID);
  await foreach (var sessionEvent in seededEvents.Paginate())
  {
      if (sessionEvent.TryPickUserMessage(out var userMessage))
      {
          foreach (var contentBlock in userMessage.Content)
          {
              if (contentBlock.TryPickBetaManagedAgentsTextBlock(out var textBlock))
              {
                  Console.WriteLine($"Seeded event: {textBlock.Text}");
              }
          }
      }
  }
  ```

  ```go Go
  seededSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  	InitialEvents: []anthropic.BetaSessionNewParamsInitialEventUnion{{
  		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
  			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
  			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
  				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
  					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
  					Text: "List the files in the working directory.",
  				},
  			}},
  		},
  	}},
  })
  if err != nil {
  	panic(err)
  }
  // initial_events 不會在建立回應中回傳，因此需列出
  // 工作階段的事件以讀回預先植入的 user.message。
  seededEvents, err := client.Beta.Sessions.Events.List(ctx, seededSession.ID, anthropic.BetaSessionEventListParams{})
  if err != nil {
  	panic(err)
  }
  for _, event := range seededEvents.Data {
  	if event.Type != "user.message" {
  		continue
  	}
  	for _, contentBlock := range event.AsUserMessage().Content {
  		if contentBlock.Type == "text" {
  			fmt.Printf("Seeded event: %s\n", contentBlock.AsText().Text)
  		}
  	}
  }
  ```

  ```java Java
  var seededSession = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .addInitialEvent(BetaManagedAgentsUserMessageEventParams.builder()
          .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
          .addTextContent("List the files in the working directory.")
          .build())
      .build());
  // initial_events 不會回傳在建立回應中；需列出
  // session 的事件才能讀回植入的 user.message。
  for (var event : client.beta().sessions().events().list(seededSession.id()).autoPager()) {
      if (event.isUserMessage()) {
          for (var contentBlock : event.asUserMessage().content()) {
              if (contentBlock.isText()) {
                  IO.println("Seeded event: " + contentBlock.asText().text());
              }
          }
      }
  }
  ```

  ```php PHP
  $seededSession = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
      initialEvents: [
          [
              'type' => 'user.message',
              'content' => [['type' => 'text', 'text' => 'List the files in the working directory.']],
          ],
      ],
  );

  // initial_events 不會回傳在建立回應中；請從 session 的
  // 事件清單中讀回。
  $seededEvents = $client->beta->sessions->events->list($seededSession->id);
  foreach ($seededEvents->getItems() as $event) {
      if ($event->type === 'user.message') {
          echo "Seeded event: {$event->content[0]->text}\n";
      }
  }
  ```

  ```ruby Ruby
  seeded_session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id,
    initial_events: [
      {
        type: :"user.message",
        content: [{type: :text, text: "List the files in the working directory."}]
      }
    ]
  )

  # initial_events 不會在建立回應中回傳；需從
  # session 的事件清單中讀回。
  client.beta.sessions.events.list(seeded_session.id).auto_paging_each do |event|
    next unless event.type == :"user.message"
    event.content.each do |block|
      puts "Seeded event: #{block.text}" if block.type == :text
    end
  end
  ```
</CodeGroup>

不接受其他任何事件類型。回應代理回合的事件（`user.tool_confirmation`、`user.tool_result` 和 `user.custom_tool_result`）不被接受，因為此時尚無代理回合存在；`user.interrupt` 也不被接受，因為沒有可停止的回合。與排程部署上的 `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) 不同，工作階段的 `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) 不接受 `system.message`。

`initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) 中的每個事件都會在建立回應傳回之前，依清單順序進行驗證並持久化，並附上伺服器指派的 ID，效果完全等同於您在建立後立即將其發布到[傳送事件](https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming#send-events)端點。每個事件的內容規則也與該端點相同。空清單等同於省略該欄位。驗證採全有或全無的方式：若任何事件驗證失敗，整個請求都會被拒絕，且不會建立任何工作階段。

在下列情況下，建立請求會被拒絕：

| 條件                                                                                                                   | 狀態  |
| -------------------------------------------------------------------------------------------------------------------- | --- |
| 超過一個 `user.define_outcome` 事件                                                                                        | 400 |
| 沒有 `rubric` 的 `user.define_outcome` 事件                                                                               | 400 |
| 整個清單中超過 100 個來自檔案的 [`document` 內容區塊](https://platform.claude.com/docs/zh-TW/build-with-claude/files#document-blocks) | 400 |
| 請求主體超過 32 MB                                                                                                         | 413 |

`initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) 中的 `user.define_outcome` 事件，其接受條件與傳送至現有工作階段時相同；請參閱[定義結果](https://platform.claude.com/docs/zh-TW/managed-agents/define-outcomes)。

### 為工作階段覆寫代理設定

您可以用三種形式傳入 `agent` (csharp, go: `Agent`)：代理 ID 字串、固定版本物件（`type: "agent"`），或覆寫物件。覆寫形式會針對單一工作階段變更代理設定的部分內容。您可以用它在某個工作階段中嘗試不同的模型或授予額外的工具，而無需為代理建立新版本。使用覆寫形式時，請將 `type` 設為 `agent_with_overrides`，並傳入代理的 `id` (csharp, go: `ID`)，以及選用的 `version` (csharp, go: `Version`)（省略 `version` (csharp, go: `Version`) 即使用代理的最新版本）。接著加入 `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`) 中的任何一項，並填入工作階段應使用的值。

每個可覆寫的欄位都遵循相同的三條規則：

* **省略該欄位：** 工作階段會繼承其所參照之代理版本的值。

* **將該欄位設為 `null`，或對清單欄位設為空陣列：** 工作階段會在該欄位被清除的情況下執行。此規則完整適用於 `system` (csharp, go: `System`; ruby: `system_`) 和 `skills` (csharp, go: `Skills`)。有三個例外：

  * `model` 永遠無法清除。工作階段一定需要模型，因此 `model: null` 會傳回 400 `agent_model_required` 錯誤。
  * 當工作階段的有效 `skills` (csharp, go: `Skills`) 非空時，清除 `tools` 會傳回 400 錯誤，因為技能需要 `read` 工具。否則，`tools: null` 和 `tools: []` 會清除該欄位。
  * 當工作階段的有效 `tools` (csharp, go: `Tools`) 仍包含參照代理某個伺服器的 `mcp_toolset` 時，清除 `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) 會傳回 400 錯誤。請在同一個請求中覆寫 `tools` (csharp, go: `Tools`) 以移除這些 `mcp_toolset` 項目，然後再清除 `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`)。

* **將該欄位設為某個值：** 該值會完整取代代理的值。覆寫永遠不會與代理的設定合併，因此 `tools` (csharp, go: `Tools`) 覆寫必須列出工作階段應具備的每一個工具。同樣地，`model` (csharp, go: `Model`) 覆寫會完整取代代理的 `model` (csharp, go: `Model`) 物件，因此代理本身的 `effort` (csharp, go: `Effort`) 不會被沿用。若要以特定的 effort 等級執行工作階段，請在覆寫的 `model` (csharp, go: `Model`) 物件中設定 `effort` (csharp, go: `Effort`)。模型不支援的等級會傳回 400 錯誤，而沒有 `effort` (csharp, go: `Effort`) 的 `model` (csharp, go: `Model`) 覆寫則會以該模型的預設 effort 等級執行。

覆寫僅適用於您所建立的工作階段。它們不會修改代理資源，也不會建立新的代理版本，因此參照同一代理的其他工作階段不受影響。

在回應中，`agent` (csharp, go: `Agent`) 物件反映的是套用覆寫後工作階段實際執行的設定。其 `id` (csharp, go: `ID`) 和 `version` (csharp, go: `Version`) 仍然識別套用覆寫的代理和版本。這讓您能將工作階段追溯回其基礎代理。

以下範例啟動一個覆寫模型並清除系統提示的工作階段：

<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": {
        "type": "agent_with_overrides",
        "id": "'"$AGENT_ID"'",
        "model": {"id": "claude-sonnet-5-5"},
        "system": null
      },
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  # The response's `agent` is the resolved snapshot: each override replaces that
  # field for this session only, and the agent resource keeps its id and version.
  ant beta:sessions create <<YAML
  agent:
    type: agent_with_overrides
    id: $AGENT_ID
    model:
      id: claude-sonnet-5-5
    system: null
  environment_id: $ENVIRONMENT_ID
  YAML
  ```

  ```python Python
  override_session = client.beta.sessions.create(
      agent={
          "type": "agent_with_overrides",
          "id": agent.id,
          "model": {"id": "claude-sonnet-5-5"},
          "system": None,  # clear the agent's system prompt for this session
      },
      environment_id=environment.id,
  )
  # 回應中的 agent 是套用覆寫後解析出的快照。
  print(f"Model: {override_session.agent.model.id}")
  print(f"System: {override_session.agent.system}")
  ```

  ```typescript TypeScript
  const overrideSession = await client.beta.sessions.create({
    agent: {
      type: "agent_with_overrides",
      id: agent.id,
      model: { id: "claude-sonnet-5-5" },
      system: null // clear the agent's system prompt for this session
    },
    environment_id: environment.id
  });
  // 回應中的 agent 是套用覆寫後解析出的快照。
  console.log(`Model: ${overrideSession.agent.model.id}`);
  console.log(`System: ${overrideSession.agent.system}`);
  ```

  ```csharp C#
  var overrideSession = await client.Beta.Sessions.Create(new()
  {
      Agent = new BetaManagedAgentsAgentWithOverridesParams
      {
          Type = BetaManagedAgentsAgentWithOverridesParamsType.AgentWithOverrides,
          ID = agent.ID,
          Model = new BetaManagedAgentsModelConfigParams
          {
              ID = BetaManagedAgentsModel.ClaudeSonnet5_5,
          },
          System = null, // clear the agent's system prompt for this session
      },
      EnvironmentID = environment.ID,
  });
  // 回應中的 agent 是已套用覆寫後解析出的快照。
  Console.WriteLine($"Model: {overrideSession.Agent.Model.ID.Raw()}");
  Console.WriteLine($"System: {overrideSession.Agent.System ?? "null"}");
  ```

  ```go Go
  overrideSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfBetaManagedAgentsAgentWithOverridess: &anthropic.BetaManagedAgentsAgentWithOverridesParams{
  			Type: anthropic.BetaManagedAgentsAgentWithOverridesParamsTypeAgentWithOverrides,
  			ID:   agent.ID,
  			Model: anthropic.BetaManagedAgentsModelConfigParams{
  				ID: anthropic.BetaManagedAgentsModelClaudeSonnet5_5,
  			},
  			// 清除此工作階段中代理的系統提示。
  			System: param.Null[string](),
  		},
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  // 回應中的 agent 是套用覆寫後解析出的快照。
  fmt.Printf("Model: %s\n", overrideSession.Agent.Model.ID)
  fmt.Printf("System: %q\n", overrideSession.Agent.System)
  ```

  ```java Java
  var overrideSession = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(BetaManagedAgentsAgentWithOverridesParams.builder()
          .type(BetaManagedAgentsAgentWithOverridesParams.Type.AGENT_WITH_OVERRIDES)
          .id(agent.id())
          .model(BetaManagedAgentsModelConfigParams.builder()
              .id(BetaManagedAgentsModel.CLAUDE_SONNET_5_5)
              .build())
          .system((String) null) // clear the agent's system prompt for this session
          .build())
      .environmentId(environment.id())
      .build());
  // 回應中的 agent 是套用覆寫後解析出的快照。
  IO.println("Model: " + overrideSession.agent().model().id());
  IO.println("System: " + overrideSession.agent().system().orElse("null"));
  ```

  ```php PHP
  $overrides = BetaManagedAgentsAgentWithOverridesParams::with(
      id: $agent->id,
      type: 'agent_with_overrides',
      model: ['id' => 'claude-sonnet-5-5'],
  );
  // 清除此 session 的系統提示。此處的陣列存取是關鍵：
  // create() 會從原始陣列移除 null，而 ::with() 會將 null 引數視為省略。
  $overrides['system'] = null;

  $overrideSession = $client->beta->sessions->create(
      agent: $overrides,
      environmentID: $environment->id,
  );
  // 回應中的 agent 是套用覆寫後解析出的快照。
  echo "Model: {$overrideSession->agent->model->id}\n";
  echo 'System: ' . ($overrideSession->agent->system ?? 'null') . "\n";
  ```

  ```ruby Ruby
  # 系統提示的覆寫欄位是 `system_`（結尾底線），因為單純的
  # `system` 是 Ruby 的 Kernel#system。設為 nil 可清除提示。
  override_session = client.beta.sessions.create(
    agent: Anthropic::Beta::BetaManagedAgentsAgentWithOverridesParams.new(
      type: :agent_with_overrides,
      id: agent.id,
      model: {id: "claude-sonnet-5-5"},
      system_: nil
    ),
    environment_id: environment.id
  )
  # 回應中的 agent 是套用覆寫後解析出的快照。
  puts "Model: #{override_session.agent.model.id}"
  puts "System: #{override_session.agent.system_.inspect}"
  ```
</CodeGroup>

#### 為工作階段固定推論地理區域

由於 `model` (csharp, go: `Model`) 覆寫會完整取代代理的 `model` (csharp, go: `Model`) 物件，它也會為工作階段設定或清除模型的[推論地理區域](https://platform.claude.com/docs/zh-TW/manage-claude/data-residency)固定設定：包含 `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) 的覆寫會固定處理工作階段模型請求的地理區域，而省略它的覆寫則會清除代理的固定設定，使工作階段遵循工作區的 `default_inference_geo`。覆寫的值會在建立工作階段時依據工作區的 `allowed_inference_geos` 進行驗證。

以下範例從一個模型未固定地理區域的代理啟動工作階段，透過在 `model` (csharp, go: `Model`) 覆寫中加入 `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`)，將工作階段的模型請求固定為美國推論，並印出回應中 `agent.model` (csharp, go: `Agent.Model`) 所回傳的值：

<CodeGroup>
  ```bash cURL
  # Replaces the whole model object of the agent: restate id, add inference_geo to pin.
  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": {
        "type": "agent_with_overrides",
        "id": "'"$AGENT_ID"'",
        "model": {"id": "claude-opus-5-5", "inference_geo": "us"}
      },
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  # Replaces the whole model object of the agent: restate id, add inference_geo to pin.
  ant beta:sessions create <<YAML
  agent:
    type: agent_with_overrides
    id: $AGENT_ID
    model:
      id: claude-opus-5-5
      inference_geo: us
  environment_id: $ENVIRONMENT_ID
  YAML
  ```

  ```python Python
  session = client.beta.sessions.create(
      agent={
          "type": "agent_with_overrides",
          "id": agent.id,
          # 完整取代代理程式的 `model`：重新指定 `id`，並加入 `inference_geo` 以固定位置。
          "model": {"id": "claude-opus-5-5", "inference_geo": "us"},
      },
      environment_id=environment.id,
  )
  print(f"Inference geo: {session.agent.model.inference_geo}")
  ```

  ```typescript TypeScript
  const session = await client.beta.sessions.create({
    agent: {
      type: "agent_with_overrides",
      id: agent.id,
      // 完整取代代理程式的 `model`：重新指定 `id`，並加入 `inference_geo` 以固定。
      model: { id: "claude-opus-5-5", inference_geo: "us" }
    },
    environment_id: environment.id
  });
  console.log(`Inference geo: ${session.agent.model.inference_geo}`);
  ```

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = new BetaManagedAgentsAgentWithOverridesParams
      {
          Type = BetaManagedAgentsAgentWithOverridesParamsType.AgentWithOverrides,
          ID = agent.ID,
          // 完整取代 agent 的 `model`：重新指定 `id`，並加入 `inference_geo` 以固定位置。
          Model = new BetaManagedAgentsModelConfigParams
          {
              ID = BetaManagedAgentsModel.ClaudeOpus5_5,
              InferenceGeo = "us",
          },
      },
      EnvironmentID = environment.ID,
  });
  Console.WriteLine($"Inference geo: {session.Agent.Model.InferenceGeo}");
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfBetaManagedAgentsAgentWithOverridess: &anthropic.BetaManagedAgentsAgentWithOverridesParams{
  			Type: anthropic.BetaManagedAgentsAgentWithOverridesParamsTypeAgentWithOverrides,
  			ID:   agent.ID,
  			// 完整取代 agent 的 `model`：重新指定 `id`，並加入 `inference_geo` 以固定。
  			Model: anthropic.BetaManagedAgentsModelConfigParams{
  				ID:           anthropic.BetaManagedAgentsModelClaudeOpus5_5,
  				InferenceGeo: anthropic.String("us"),
  			},
  		},
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  fmt.Printf("Inference geo: %s\n", session.Agent.Model.InferenceGeo)
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(BetaManagedAgentsAgentWithOverridesParams.builder()
          .type(BetaManagedAgentsAgentWithOverridesParams.Type.AGENT_WITH_OVERRIDES)
          .id(agent.id())
          // 完整取代代理程式的 `model`：重新指定 `id`，並加入 `inference_geo` 以固定位置。
          .model(BetaManagedAgentsModelConfigParams.builder()
              .id(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
              .inferenceGeo("us")
              .build())
          .build())
      .environmentId(environment.id())
      .build());
  IO.println("Inference geo: " + session.agent().model().inferenceGeo().orElseThrow());
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: BetaManagedAgentsAgentWithOverridesParams::with(
          id: $agent->id,
          type: 'agent_with_overrides',
          // 完整取代代理程式的 `model`：重新指定 `id`，並加入 `inference_geo` 以固定位置。
          model: BetaManagedAgentsModelConfigParams::with(
              id: 'claude-opus-5-5',
              inferenceGeo: 'us',
          ),
      ),
      environmentID: $environment->id,
  );
  echo "Inference geo: {$session->agent->model->inferenceGeo}\n";
  ```

  ```ruby Ruby
  session = client.beta.sessions.create(
    agent: {
      type: :agent_with_overrides,
      id: agent.id,
      # 完整取代代理程式的 `model`：重新指定 `id`，並加入 `inference_geo` 以固定。
      model: {id: "claude-opus-5-5", inference_geo: "us"}
    },
    environment_id: environment.id
  )
  puts "Inference geo: #{session.agent.model.inference_geo}"
  ```
</CodeGroup>

<Tip>
  代理定義了 Claude 在工作階段中的行為方式，包括模型、系統提示、工具和 MCP 伺服器。詳情請參閱[定義您的代理](https://platform.claude.com/docs/zh-TW/managed-agents/agent-setup)。
</Tip>

### 設定工作階段預算

若要限制工作階段的花費上限，請在建立時傳入選用的 `budget` (csharp, go: `Budget`) 物件。預算是工作階段牌價成本的硬性上限：平台會以公開牌價計算工作階段所消耗的一切，一旦累計總額達到 `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`)，工作階段就會停止發出新的模型請求。請將 `type` (csharp, go: `Type`) 設為 `limit`，並為 `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`) 提供 `amount` (csharp, go: `Amount`) 和 `currency` (csharp, go: `Currency`)。`amount` (csharp, go: `Amount`) 是以字串表示的美分整數，例如 `"125"` 代表 $1.25。API 採用字串而非數字，因此永遠不會套用浮點數捨入。`USD` 是目前唯一支援的貨幣。當工作階段達到上限時，它會暫停並進入閒置狀態，停止原因為 `budget_reached`。上限是在模型請求之間強制執行的，因此跨越上限的那個請求會先完成，工作階段最終的牌價成本可能會[略微超過上限](https://platform.claude.com/docs/zh-TW/managed-agents/budgets#when-a-session-reaches-its-budget)。預算只能在建立時附加：您之後可以[變更或移除](https://platform.claude.com/docs/zh-TW/managed-agents/session-operations#updating-the-session-budget)它，但無法為建立時未設定預算的工作階段新增預算。

以下範例建立一個預算為 $1.25 的工作階段：

<CodeGroup>
  ```bash cURL
  curl -sS --fail-with-body 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": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'",
      "budget": {
        "type": "limit",
        "max_list_cost": {"amount": "125", "currency": "USD"}
      }
    }'
  ```

  ```bash CLI
  # 請將金額保留在引號內，使其以字串而非數字傳送。
  ant beta:sessions create \
    --agent "$AGENT_ID" \
    --environment-id "$ENVIRONMENT_ID" \
    --budget '{type: limit, max_list_cost: {amount: "125", currency: USD}}'
  ```

  ```python Python
  session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
      budget={
          "type": "limit",
          "max_list_cost": {"amount": "125", "currency": "USD"},
      },
  )
  print(session.id, session.budget.max_list_cost.amount)  # sesn_01... 125
  ```

  ```typescript TypeScript
  const session = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id,
    budget: {
      type: "limit",
      max_list_cost: { amount: "125", currency: "USD" }
    }
  });
  console.log(session.id, session.budget?.max_list_cost.amount); // sesn_01... 125
  ```

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      Budget = new()
      {
          Type = BetaManagedAgentsBudgetLimitType.Limit,
          MaxListCost = new() { Amount = "125", Currency = BetaCurrency.Usd },
      },
  });
  Console.WriteLine($"{session.ID} {session.Budget?.MaxListCost.Amount}");  // sesn_01... 125
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  	Budget: anthropic.BetaManagedAgentsBudgetLimitParam{
  		Type: anthropic.BetaManagedAgentsBudgetLimitTypeLimit,
  		MaxListCost: anthropic.BetaMonetaryAmountParam{
  			Amount:   "125",
  			Currency: anthropic.BetaCurrencyUsd,
  		},
  	},
  })
  if err != nil {
  	panic(err)
  }
  fmt.Println(session.ID, session.Budget.MaxListCost.Amount) // sesn_01... 125
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .budget(BetaManagedAgentsBudgetLimit.builder()
          .type(BetaManagedAgentsBudgetLimit.Type.LIMIT)
          .maxListCost(BetaMonetaryAmount.builder()
              .amount("125")
              .currency(BetaCurrency.USD)
              .build())
          .build())
      .build());
  IO.println(session.id() + " " + session.budget().orElseThrow().maxListCost().amount());  // sesn_01... 125
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
      budget: [
          'type' => 'limit',
          'max_list_cost' => ['amount' => '125', 'currency' => 'USD'],
      ],
  );
  echo "{$session->id} {$session->budget->maxListCost->amount}\n"; // sesn_01... 125
  ```

  ```ruby Ruby
  session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id,
    budget: {
      type: "limit",
      max_list_cost: {amount: "125", currency: "USD"}
    }
  )
  puts "#{session.id} #{session.budget.max_list_cost.amount}" # sesn_01... 125
  ```
</CodeGroup>

請參閱[工作階段預算](https://platform.claude.com/docs/zh-TW/managed-agents/budgets)，了解強制執行的運作方式、哪些項目計入牌價成本，以及預算在多代理工作階段中的行為。

## 透過保管庫進行 MCP 驗證

如果您的代理使用需要驗證的 MCP 工具，請在建立工作階段時傳入 `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`)，以參照包含已儲存 OAuth 憑證的保管庫。Anthropic 會代您管理權杖更新。請參閱[使用保管庫進行驗證](https://platform.claude.com/docs/zh-TW/managed-agents/vaults)，了解如何建立保管庫和註冊憑證。

<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": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'",
      "vault_ids": ["'"$VAULT_ID"'"]
    }'
  ```

  ```bash CLI
  ant beta:sessions create <<YAML
  agent: $AGENT_ID
  environment_id: $ENVIRONMENT_ID
  vault_ids:
    - $VAULT_ID
  YAML
  ```

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

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

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

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

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

  ```php PHP
  $vaultSession = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
      vaultIDs: [$vault->id],
  );
  ```

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

## 啟動工作階段

在沒有 `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) 的情況下建立工作階段，只會註冊工作階段而不會開始任何工作；環境的沙箱會在工作階段建立後立即開始佈建，因此第一次工具呼叫不需要等待它。若要委派任務，請使用[使用者事件](https://platform.claude.com/docs/zh-TW/managed-agents/reference#event-types)將事件傳送至工作階段。若要改為在建立請求中提供第一個事件，請參閱[以初始事件預先填入工作階段](https://platform.claude.com/docs/zh-TW/managed-agents/sessions#seed-the-session-with-initial-events)。工作階段扮演狀態機的角色，追蹤進度，而事件則驅動實際的執行。

<CodeGroup>
  ```bash cURL
  curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
    -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 '{
      "events": [
        {
          "type": "user.message",
          "content": [{"type": "text", "text": "List the files in the working directory."}]
        }
      ]
    }'
  ```

  ```bash CLI
  ant beta:sessions:events send \
    --session-id "$SESSION_ID" <<'YAML'
  events:
    - type: user.message
      content:
        - type: text
          text: List the files in the working directory.
  YAML
  ```

  ```python Python
  client.beta.sessions.events.send(
      session.id,
      events=[
          {
              "type": "user.message",
              "content": [
                  {"type": "text", "text": "List the files in the working directory."}
              ],
          },
      ],
  )
  ```

  ```typescript TypeScript
  await client.beta.sessions.events.send(session.id, {
    events: [
      {
        type: "user.message",
        content: [{ type: "text", text: "List the files in the working directory." }]
      }
    ]
  });
  ```

  ```csharp C#
  await client.Beta.Sessions.Events.Send(session.ID, new()
  {
      Events =
      [
          new BetaManagedAgentsUserMessageEventParams
          {
              Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
              Content =
              [
                  new BetaManagedAgentsTextBlock
                  {
                      Type = BetaManagedAgentsTextBlockType.Text,
                      Text = "List the files in the working directory.",
                  },
              ],
          },
      ],
  });
  ```

  ```go Go
  if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
  	Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
  		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
  			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
  			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
  				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
  					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
  					Text: "List the files in the working directory.",
  				},
  			}},
  		},
  	}},
  }); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  client.beta().sessions().events().send(
      session.id(),
      EventSendParams.builder()
          .addEvent(BetaManagedAgentsUserMessageEventParams.builder()
              .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
              .addTextContent("List the files in the working directory.")
              .build())
          .build());
  ```

  ```php PHP
  $client->beta->sessions->events->send(
      $session->id,
      events: [
          [
              'type' => 'user.message',
              'content' => [['type' => 'text', 'text' => 'List the files in the working directory.']],
          ],
      ],
  );
  ```

  ```ruby Ruby
  client.beta.sessions.events.send_(
    session.id,
    events: [
      {
        type: :"user.message",
        content: [{type: :text, text: "List the files in the working directory."}]
      }
    ]
  )
  ```
</CodeGroup>

請參閱[工作階段事件串流](https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming)，了解如何串流代理的回應並處理工具確認。

請參閱[工作階段狀態](https://platform.claude.com/docs/zh-TW/managed-agents/session-operations#session-statuses)，了解工作階段會經歷的各種狀態。

## 後續步驟

<CardGroup cols={3}>
  <Card title="工作階段操作" icon="settings" href="https://platform.claude.com/docs/zh-TW/managed-agents/session-operations">
    擷取、列出、更新、封存和刪除 Claude Managed Agents 工作階段。
  </Card>

  <Card title="工作階段事件串流" icon="lightning" href="https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming">
    傳送事件、串流回應，並在執行過程中中斷或重新導向您的工作階段。
  </Card>

  <Card title="排程部署" icon="arrows-clockwise" href="https://platform.claude.com/docs/zh-TW/managed-agents/scheduled-deployments">
    使用 Claude API 建立和管理部署：依週期性 cron 排程執行代理，並檢視其執行歷史記錄。
  </Card>
</CardGroup>