セッション操作

セッションが存在するようになったら、これらの操作を使用してセッションの読み取り、更新、アーカイブ、または削除を行います。セッションの作成と作業の送信については、セッションを開始するを参照してください。

セッションのステータス

セッションは以下のステータスを経て進行します。セッションのライフサイクルについては、セッションを開始するを参照してください。

エージェント設定の更新

セッションのagent.toolsとagent.mcp_serversは、権限ポリシーやドメインフィルターなどのツールごとのWeb設定を含め、新しいエージェントバージョンを作成することなくセッションの途中で更新できます。更新はセッションローカルであり、基盤となるエージェントには反映されません。更新されたallowed_domainsとblocked_domainsは、セッションの残りの期間に適用されます。

セッション作成後に変更できるのは、エージェントのtoolsとmcp_serversのみです。エージェントのものとは異なるmodel、system、またはskillsの値でセッションを実行するには、セッション作成時にエージェント設定のオーバーライドを使用してください。エージェントのモデル設定（inference_geoのピンを含む）もセッションの途中で変更することはできません。ピンはエージェントを保存するときに設定するか、セッション作成時にmodelオーバーライドを使用して単一のセッションに対して設定または解除してください。エージェントに設定されたsystemフィールドは、セッションの存続期間中は固定されます。対応しているモデルでは、system.messageイベントを送信することで、セッションの途中でもシステムレベルのガイダンスを追加できます。

toolsまたはmcp_serversの更新のセマンティクスは完全置換です。指定された配列が新しい値になります。既存のエントリを保持するには、セッションをGETし、配列を変更して、POSTで送り返してください。

エージェントを更新するには、セッションがidleである必要があります。セッションの実行中にエージェントを更新するには、user.interruptイベントを単独で送信し、セッションがidleになるまで待ちます。

ant beta:sessions update --session-id "$SESSION_ID" <<'YAML'
agent:
  tools:
    - type: agent_toolset_20260401
    - type: mcp_toolset
      mcp_server_name: linear
  mcp_servers:
    - type: url
      name: linear
      url: https://mcp.linear.app/sse
YAML

セッション予算の更新

予算付きで作成されたセッションは、2種類の予算更新を受け付けます。上限を新しいmax_list_costで置き換えることと、budgetをnullに設定して上限を削除することです。どちらも、セッションが上限に達したときに一時停止した作業を自動的に再開します。置き換え後の上限は現在の上限より高くても低くてもかまいませんが、セッションの消費済みリストコストより厳密に大きくなければなりません。また、削除は一方向です。null以外のbudgetは、現在予算を持っているセッションでのみ受け付けられるため、削除した予算を再度追加したり、予算なしで作成されたセッションに予算を追加したりすることはできません。リクエスト例、エラー時の動作、およびリストコストに計上される対象については、セッション予算を参照してください。

セッションの取得

ant beta:sessions retrieve --session-id "$SESSION_ID"

セッションの一覧表示

GET /v1/sessionsの結果はページネーションされます。ページサイズを制御するにはlimitクエリパラメータを使用します。各レスポンスにはnext_pageカーソルが含まれます。次のリクエストでこれをpageパラメータとして渡すと、次のページを取得できます。これ以上結果がない場合、next_pageはnullになります。

前のページに戻るには、prev_pageをpageパラメータとして渡します。最初のページにいる場合、prev_pageはnullになります。

pageカーソルは不透明であり、それを生成したリクエストのorderをエンコードしています。orderクエリパラメータは、結果のソート方向を作成時刻のascまたはdescで設定します。デフォルトはdesc（新しい順）です。異なるorderでカーソルを再利用すると400エラーが返されます。カーソルの位置を除外するようにcreated_atフィルターを変更した場合も同様です。残りのフィルターやlimitを含むその他のクエリパラメータは、ページネーションされたリクエスト間で変更できます。一覧エンドポイント間で共通のページネーションフィールドについては、ページネーションを参照してください。

# --format raw は prev_page と next_page のカーソルを含む 1 ページ分のエンベロープを
# 返します。デフォルトの出力は自動でページネーションし、セッションのみを出力します。
cursors=$(ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --format raw \
  --transform '{prev_page,next_page}')
printf '%s\n' "$cursors"

# next_page カーソルを --page として渡すと次のページを取得できます。
NEXT_PAGE=$(jq -r '.next_page' <<< "$cursors")
ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --page "$NEXT_PAGE" \
  --format raw \
  --transform '{prev_page,next_page}'
# そのレスポンスの prev_page を --page として渡すと同じ方法で前に戻れます。

セッションのアーカイブ

セッションをアーカイブすると、履歴を保持したまま新しいイベントの送信を防ぐことができます。running状態のセッションはアーカイブできません。アーカイブするには、user.interruptイベントを単独で送信し、セッションがidleになるまで待ちます。

ant beta:sessions archive \
  --session-id "$SESSION_ID"

セッションの削除

セッションを削除すると、そのレコード、イベント、および関連するサンドボックスが永久に削除されます。running状態のセッションは削除できません。削除するには、user.interruptイベントを単独で送信し、セッションがidleになるまで待ちます。

メモリストア、ボールト、スキル、環境、およびエージェントは独立したリソースであり、セッションの削除による影響を受けません。Files APIを通じてアップロードしたファイルも影響を受けませんが、セッション自体が生成したファイルはそのセッションにスコープされており、ファイルシステムとともに永久に削除されます。セッションを削除する前に、保持する必要があるものはすべてダウンロードしてください。最後のターンの終わりに書き込まれた出力ファイルは、セッションがidleになってからセッションのファイル一覧に表示されるまで数秒かかることがあるため、まず期待するファイルが一覧に表示されていることを確認してください。

ant beta:sessions delete \
  --session-id "$SESSION_ID"