---
title: セッションを開始する
url: https://platform.claude.com/docs/ja/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
---

セッションは、環境内のエージェントインスタンスです。各セッションは[エージェント](https://platform.claude.com/docs/ja/managed-agents/agent-setup)と[環境](https://platform.claude.com/docs/ja/managed-agents/environments)（どちらも個別に作成されます）を参照し、複数のインタラクションにわたって会話履歴を保持します。セッションは2段階のライフサイクルに従います。まず[セッションを作成](https://platform.claude.com/docs/ja/managed-agents/sessions#creating-a-session)し、次に[ユーザーイベントを送信](https://platform.claude.com/docs/ja/managed-agents/sessions#starting-the-session)して作業を開始します。[`initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`)](https://platform.claude.com/docs/ja/managed-agents/sessions#seed-the-session-with-initial-events)を使用して、両方のステップを1回の呼び出しにまとめることもできます。

## セッションの作成

セッションには`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>

### 初期イベントでセッションをシードする

セッションの作成と作業の開始を1回の呼び出しで行うことができます。`initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`)は、作成時にセッションへ送信する初期[イベント](https://platform.claude.com/docs/ja/managed-agents/reference#event-types)のオプションの配列で、順番に処理されます。`user.message`イベントと[`user.define_outcome`](https://platform.claude.com/docs/ja/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 は作成レスポンスにエコーされないため、
  # セッションのイベントリストから読み戻します。
  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 は作成レスポンスにエコーされないため、セッションの
  // イベントを一覧して、シードしたメッセージを読み取ります。
  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 は作成レスポンスにエコーされないため、セッションの
  // イベントリストから読み戻します。
  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 は作成レスポンスにエコーされないため、セッションの
  // イベントを一覧して、シードした 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 は create レスポンスにエコーされないため、
  // セッションのイベント一覧から読み戻します。
  $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 は作成レスポンスにはエコーされないため、セッションの
  # イベントリストから読み戻します。
  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/ja/managed-agents/events-and-streaming#send-events)エンドポイントへ投稿した場合とまったく同じです。イベントごとのコンテンツルールも、そのエンドポイントと同じです。空のリストは、フィールドを省略した場合と同等です。検証はオールオアナッシングです。いずれかのイベントが検証に失敗すると、リクエスト全体が拒否され、セッションは作成されません。

作成リクエストは、次の場合に拒否されます。

| 条件                                                                                                                       | ステータス |
| ------------------------------------------------------------------------------------------------------------------------ | ----- |
| 複数の`user.define_outcome`イベント                                                                                             | 400   |
| `rubric`のない`user.define_outcome`イベント                                                                                     | 400   |
| リスト全体で100個を超えるファイルソースの[`document`コンテンツブロック](https://platform.claude.com/docs/ja/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/ja/managed-agents/define-outcomes)を参照してください。

### セッションのエージェント設定をオーバーライドする

`agent` (csharp, go: `Agent`)は3つの形式で渡すことができます。エージェントID文字列、バージョン固定オブジェクト（`type: "agent"`）、またはオーバーライドオブジェクトです。オーバーライド形式は、単一のセッションに対してエージェントの設定の一部を変更します。エージェントをバージョン管理することなく、1つのセッションで別のモデルを試したり、追加のツールを付与したりする場合に使用します。オーバーライド形式では、`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`)のいずれかを、セッションで使用する値とともに含めます。

オーバーライド可能な各フィールドは、同じ3つのルールに従います。

* **フィールドを省略する：** セッションは、参照するエージェントバージョンから値を継承します。

* **フィールドを`null`に設定する、またはリストフィールドの場合は空の配列に設定する：** セッションはそのフィールドがクリアされた状態で実行されます。このルールは`system` (csharp, go: `System`; ruby: `system_`)と`skills` (csharp, go: `Skills`)に完全に適用されます。例外が3つあります。

  * `model`はクリアできません。セッションには常にモデルが必要なため、`model: null`は400 `agent_model_required`エラーを返します。
  * セッションの有効な`skills` (csharp, go: `Skills`)が空でない場合、スキルには`read`ツールが必要なため、`tools`をクリアすると400エラーが返されます。それ以外の場合、`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'],
  );
  // このセッションのシステムプロンプトをクリアします。ここでは配列アクセスが重要です:
  // 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`)オブジェクトを完全に置き換えるため、セッションに対するモデルの「[inference geo](https://platform.claude.com/docs/ja/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,
          // エージェントの `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,
  			// エージェントの `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>
  エージェントは、モデル、システムプロンプト、ツール、MCPサーバーなど、セッション内でのClaudeの動作を定義します。詳細については、[エージェントを定義する](https://platform.claude.com/docs/ja/managed-agents/agent-setup)を参照してください。
</Tip>

### セッション予算を設定する

セッションが支出できる金額に上限を設けるには、作成時にオプションの`budget` (csharp, go: `Budget`)オブジェクトを渡します。予算は、セッションの「list cost」（定価ベースのコスト）に対する厳格な上限です。プラットフォームはセッションが消費するすべてのものを公開定価で計算し、その累計が`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`)は、文字列として記述された米セント単位の整数で、たとえば$1.25の場合は`"125"`です。APIが数値ではなく文字列を受け取るのは、浮動小数点の丸めが一切適用されないようにするためです。現在サポートされている通貨は`USD`のみです。セッションが上限に達すると、一時停止し、停止理由`budget_reached`でアイドル状態になります。上限はモデルリクエストの間で適用されるため、上限を超えるリクエストは先に完了し、セッションの最終的なlist costは[上限をわずかに超える](https://platform.claude.com/docs/ja/managed-agents/budgets#when-a-session-reaches-its-budget)場合があります。予算は作成時にのみ付与できます。後から[変更または削除](https://platform.claude.com/docs/ja/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>

適用の仕組み、list costに含まれるもの、マルチエージェントセッションでの予算の動作については、[セッション予算](https://platform.claude.com/docs/ja/managed-agents/budgets)を参照してください。

## Vaultを介したMCP認証

エージェントが認証を必要とするMCPツールを使用する場合は、セッション作成時に`vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`)を渡して、保存されたOAuth認証情報を含むvaultを参照します。トークンの更新はAnthropicが代わりに管理します。vaultの作成方法と認証情報の登録方法については、[Vaultで認証する](https://platform.claude.com/docs/ja/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/ja/managed-agents/reference#event-types)を使用してセッションにイベントを送信します。代わりに作成リクエストで最初のイベントを指定するには、[初期イベントでセッションをシードする](https://platform.claude.com/docs/ja/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/ja/managed-agents/events-and-streaming)を参照してください。

セッションが遷移するステータスについては、[セッションステータス](https://platform.claude.com/docs/ja/managed-agents/session-operations#session-statuses)を参照してください。

## 次のステップ

<CardGroup cols={3}>
  <Card title="セッション操作" icon="settings" href="https://platform.claude.com/docs/ja/managed-agents/session-operations">
    Claude Managed Agentsのセッションを取得、一覧表示、更新、アーカイブ、削除します。
  </Card>

  <Card title="セッションイベントストリーム" icon="lightning" href="https://platform.claude.com/docs/ja/managed-agents/events-and-streaming">
    イベントを送信し、レスポンスをストリーミングし、実行中のセッションを中断またはリダイレクトします。
  </Card>

  <Card title="スケジュールされたデプロイメント" icon="arrows-clockwise" href="https://platform.claude.com/docs/ja/managed-agents/scheduled-deployments">
    Claude APIでデプロイメントを作成および管理します。定期的なcronスケジュールでエージェントを実行し、その実行履歴を確認します。
  </Card>
</CardGroup>