セッションを開始する

セッションは、環境内のエージェントインスタンスです。各セッションはエージェントと環境（それぞれ別途作成）を参照し、複数のやり取りにわたって会話履歴を保持します。セッションは2段階のライフサイクルに従います。まずセッションを作成してサンドボックスをプロビジョニングし、次にユーザーイベントを送信して作業を開始します。



セッションの作成

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



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

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

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

• フィールドを省略する： セッションは、参照するエージェントバージョンから値を継承します。
• フィールドをnullに設定する、またはリストフィールドの場合は空の配列に設定する： セッションはそのフィールドがクリアされた状態で実行されます。このルールはsystem、mcp_servers、skillsに完全に適用されます。2つの例外があります。
  • modelはクリアできません。セッションには常にモデルが必要なため、model: nullは400 agent_model_requiredエラーを返します。
  • セッションの実効的なskillsが空でない場合、toolsをクリアすると400エラーが返されます。これは、スキルがreadツールを必要とするためです。それ以外の場合、tools: nullおよびtools: []はフィールドをクリアします。
• フィールドに値を設定する： その値がエージェントの値を完全に置き換えます。オーバーライドはエージェントの設定とマージされることはないため、toolsのオーバーライドにはセッションが持つべきすべてのツールをリストする必要があります。

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

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

# レスポンスの `agent` は解決済みスナップショットです：各オーバーライドはこのセッション
# のみでそのフィールドを置き換え、エージェントリソースは id と version を保持します。
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



Vaultを通じたMCP認証

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

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



セッションの開始

セッションを作成すると環境のサンドボックスがプロビジョニングされますが、作業は開始されません。タスクを委任するには、ユーザーイベントを使用してセッションにイベントを送信します。セッションは進行状況を追跡するステートマシンとして機能し、イベントが実際の実行を駆動します。

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

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

セッションが遷移するステータスについてはセッションステータスを、セッションの取得、一覧表示、更新、アーカイブ、削除についてはセッション操作を参照してください。

定期的なスケジュールでセッションを自動的に作成するには、スケジュールされたデプロイメントを参照してください。