セッションを開始する

セッションは、環境内のエージェントインスタンスです。各セッションはエージェントと環境（どちらも個別に作成されます）を参照し、複数のインタラクションにわたって会話履歴を保持します。セッションは2段階のライフサイクルに従います。まずセッションを作成し、次にユーザーイベントを送信して作業を開始します。initial_eventsを使用して、両方のステップを1回の呼び出しにまとめることもできます。

セッションの作成

セッションにはagent IDとenvironment IDが必要です。エージェントはバージョン管理されたリソースです。agent IDを文字列として渡すと、最新のエージェントバージョンでセッションが作成されます。

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

セッションを特定のエージェントバージョンに固定するには、オブジェクトを渡します。これにより、どのバージョンを実行するかを正確に制御でき、新しいバージョンのロールアウトを独立して段階的に進めることができます。

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

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

セッションの作成と作業の開始を1回の呼び出しで行うことができます。initial_eventsは、作成時にセッションへ送信する初期イベントのオプションの配列で、順番に処理されます。user.messageイベントとuser.define_outcomeイベントをサポートし、最大50個のイベントを受け付けます。空でないリストを渡すと、同じ呼び出しでエージェントループが開始されます。セッションは追加のリクエストなしで、直接runningステータスで作成されます。

次の例では、initial_eventsに単一のuser.messageを含めてセッションを作成します。

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}")

その他のイベントタイプは受け付けられません。エージェントのターンに応答するイベント（user.tool_confirmation、user.tool_result、user.custom_tool_result）は、まだエージェントのターンが存在しないため受け付けられず、user.interruptは停止するターンがないため受け付けられません。スケジュールされたデプロイメントのinitial_eventsとは異なり、セッションのinitial_eventsはsystem.messageを受け付けません。

initial_events内の各イベントは、作成レスポンスが返される前に、リストの順序で検証および永続化され、サーバーが割り当てたIDが付与されます。これは、作成直後にイベント送信エンドポイントへ投稿した場合とまったく同じです。イベントごとのコンテンツルールも、そのエンドポイントと同じです。空のリストは、フィールドを省略した場合と同等です。検証はオールオアナッシングです。いずれかのイベントが検証に失敗すると、リクエスト全体が拒否され、セッションは作成されません。

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

initial_events内のuser.define_outcomeイベントは、既存のセッションに送信する場合と同じ条件で受け付けられます。成果を定義するを参照してください。

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

agentは3つの形式で渡すことができます。エージェントID文字列、バージョン固定オブジェクト（type: "agent"）、またはオーバーライドオブジェクトです。オーバーライド形式は、単一のセッションに対してエージェントの設定の一部を変更します。エージェントをバージョン管理することなく、1つのセッションで別のモデルを試したり、追加のツールを付与したりする場合に使用します。オーバーライド形式では、typeをagent_with_overridesに設定し、エージェントのidと、オプションでversionを渡します（エージェントの最新バージョンを使用するにはversionを省略します）。次に、model、system、tools、mcp_servers、またはskillsのいずれかを、セッションで使用する値とともに含めます。

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

• フィールドを省略する： セッションは、参照するエージェントバージョンから値を継承します。
• フィールドをnullに設定する、またはリストフィールドの場合は空の配列に設定する： セッションはそのフィールドがクリアされた状態で実行されます。このルールはsystemとskillsに完全に適用されます。例外が3つあります。
  • modelはクリアできません。セッションには常にモデルが必要なため、model: nullは400 agent_model_requiredエラーを返します。
  • セッションの有効なskillsが空でない場合、スキルにはreadツールが必要なため、toolsをクリアすると400エラーが返されます。それ以外の場合、tools: nullとtools: []はフィールドをクリアします。
  • セッションの有効なtoolsに、エージェントのサーバーのいずれかを参照するmcp_toolsetがまだ含まれている場合、mcp_serversをクリアすると400エラーが返されます。同じリクエストでtoolsをオーバーライドしてそれらのmcp_toolsetエントリを削除してから、mcp_serversをクリアしてください。
• フィールドに値を設定する： その値がエージェントの値を完全に置き換えます。オーバーライドはエージェントの設定とマージされることはないため、toolsのオーバーライドには、セッションが持つべきすべてのツールを列挙する必要があります。同様に、modelのオーバーライドはエージェントのmodelオブジェクトを完全に置き換えるため、エージェント自身のeffortは引き継がれません。特定のeffortレベルでセッションを実行するには、オーバーライドのmodelオブジェクト内でeffortを設定します。モデルがサポートしていないレベルを指定すると400エラーが返され、effortのないmodelオーバーライドは、そのモデルのデフォルトのeffortレベルで実行されます。

オーバーライドは、作成するセッションにのみ適用されます。エージェントリソースを変更したり、新しいエージェントバージョンを作成したりすることはないため、同じエージェントを参照する他のセッションには影響しません。

レスポンスでは、agentオブジェクトは、オーバーライドが適用された後にセッションが実行される設定を反映します。そのidとversionは、引き続きオーバーライドの適用対象となるエージェントとバージョンを識別します。これにより、セッションをそのベースエージェントまで遡って追跡できます。

次の例では、モデルをオーバーライドし、システムプロンプトをクリアするセッションを開始します。

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}")

セッションの推論ジオを固定する

modelのオーバーライドはエージェントのmodelオブジェクトを完全に置き換えるため、セッションに対するモデルの「inference geo」（推論ジオ）の固定も設定またはクリアします。inference_geoを含むオーバーライドは、セッションのモデルリクエストを処理する地域を固定し、これを省略したオーバーライドはエージェントの固定をクリアするため、セッションはワークスペースのdefault_inference_geoに従います。オーバーライドされた値は、セッションの作成時にワークスペースのallowed_inference_geosに対して検証されます。

次の例では、モデルにジオの固定がないエージェントからセッションを開始し、modelオーバーライドにinference_geoを含めることでセッションのモデルリクエストを米国での推論に固定し、レスポンスのagent.modelに返された値を出力します。

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}")

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

セッションが支出できる金額に上限を設けるには、作成時にオプションのbudgetオブジェクトを渡します。予算は、セッションの「list cost」（定価ベースのコスト）に対する厳格な上限です。プラットフォームはセッションが消費するすべてのものを公開定価で計算し、その累計がmax_list_costに達すると、セッションは新しいモデルリクエストの発行を停止します。typeをlimitに設定し、max_list_costにamountとcurrencyを指定します。amountは、文字列として記述された米セント単位の整数で、たとえば$1.25の場合は"125"です。APIが数値ではなく文字列を受け取るのは、浮動小数点の丸めが一切適用されないようにするためです。現在サポートされている通貨はUSDのみです。セッションが上限に達すると、一時停止し、停止理由budget_reachedでアイドル状態になります。上限はモデルリクエストの間で適用されるため、上限を超えるリクエストは先に完了し、セッションの最終的なlist costは上限をわずかに超える場合があります。予算は作成時にのみ付与できます。後から変更または削除することはできますが、予算なしで作成されたセッションに予算を追加することはできません。

次の例では、$1.25の予算でセッションを作成します。

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

適用の仕組み、list costに含まれるもの、マルチエージェントセッションでの予算の動作については、セッション予算を参照してください。

Vaultを介したMCP認証

エージェントが認証を必要とするMCPツールを使用する場合は、セッション作成時にvault_idsを渡して、保存されたOAuth認証情報を含むvaultを参照します。トークンの更新はAnthropicが代わりに管理します。vaultの作成方法と認証情報の登録方法については、Vaultで認証するを参照してください。

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

セッションの開始

initial_eventsなしでセッションを作成すると、セッションは登録されますが、作業は開始されません。環境のサンドボックスはセッションが作成されるとすぐにプロビジョニングを開始するため、最初のツール呼び出しがそれを待つことはありません。タスクを委任するには、ユーザーイベントを使用してセッションにイベントを送信します。代わりに作成リクエストで最初のイベントを指定するには、初期イベントでセッションをシードするを参照してください。セッションは進行状況を追跡するステートマシンとして機能し、イベントが実際の実行を駆動します。

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

エージェントのレスポンスをストリーミングし、ツールの確認を処理する方法については、セッションイベントストリームを参照してください。

セッションが遷移するステータスについては、セッションステータスを参照してください。

次のステップ