セッションを開始する

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

セッションの作成

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

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

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

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

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

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

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

SEEDED_SESSION_ID=$(ant beta:sessions create \
  --transform id --raw-output <<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
)

# initial_events は作成レスポンスにはエコーされません。シードされたメッセージを
# 確認するには、セッションのイベントを一覧表示します。
echo "Seeded event: $(ant beta:sessions:events list \
  --session-id "$SEEDED_SESSION_ID" \
  --format raw \
  --transform 'data.#(type=="user.message").content.0.text' --raw-output)"

他のイベントタイプは受け付けられません。エージェントのターンに応答するイベント（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が空でない場合、toolsをクリアすると400エラーが返されます。スキルにはreadツールが必要なためです。それ以外の場合、tools: nullとtools: []はフィールドをクリアします。
  • セッションの有効なtoolsに、エージェントのサーバーのいずれかを参照するmcp_toolsetがまだ含まれている場合、mcp_serversをクリアすると400エラーが返されます。同じリクエストでtoolsをオーバーライドしてそれらのmcp_toolsetエントリを削除してから、mcp_serversをクリアしてください。
• フィールドに値を設定する： その値がエージェントの値を完全に置き換えます。オーバーライドはエージェントの設定とマージされることはないため、toolsのオーバーライドにはセッションが持つべきすべてのツールを列挙する必要があります。1つの例外があります。
  • セッションごとのmodelオーバーライド内のeffortレベルは適用されません。また、オーバーライドはエージェントのmodelオブジェクトを完全に置き換えるため、エージェント自身のeffortも引き継がれません。modelオーバーライドを指定して作成されたセッションは、モデルのデフォルトのeffortレベルで実行されます。特定のeffortレベルで実行するには、エージェントにeffortを設定し、そのセッションではmodelをオーバーライドしないでください。

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

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

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

# レスポンスの `agent` は解決済みのスナップショットです。各オーバーライドはこのセッションに
# 限ってそのフィールドを置き換え、エージェントリソースの id とバージョンは保持されます。
ant beta:sessions create \
  --transform 'agent.{id,version,model,system}' \
  --format json <<YAML
agent:
  type: agent_with_overrides
  id: $AGENT_ID
  model:
    id: claude-sonnet-5
  system: null
environment_id: $ENVIRONMENT_ID
YAML

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

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

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

# エージェントの`model`を完全に置き換えます：`id`を再指定し、`inference_geo`を追加して固定します。
session=$(ant beta:sessions create <<YAML
agent:
  type: agent_with_overrides
  id: $AGENT_ID
  model:
    id: claude-opus-5
    inference_geo: us
environment_id: $ENVIRONMENT_ID
YAML
)
echo "Inference geo: $(jq -r '.agent.model.inference_geo' <<< "$session")"

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

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

次の例では、$25.00の予算を持つセッションを作成します。レスポンスはセッションリソース上のbudgetをエコーします。

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 @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2500", "currency": "USD"}
  }
}
EOF

適用の仕組み、リストコストに計上される対象、マルチエージェントセッションでの予算の動作については、セッション予算を参照してください。

ボールトによるMCP認証

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

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

セッションの開始

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

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

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

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

次のステップ