セッション操作

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



セッションステータス

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



エージェント設定の更新

新しいエージェントバージョンを作成することなく、セッションの途中で、権限ポリシーを含むセッションのagent.toolsとagent.mcp_serversを更新できます。更新はセッションローカルであり、基盤となるエージェントには反映されません。

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

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

エージェントを更新するには、セッションが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フィルターを変更した場合も400エラーが返されます。残りのフィルターや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状態のセッションはアーカイブできません。すぐにアーカイブする必要がある場合は、中断イベントを送信してください。

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



セッションの削除

セッションを削除すると、そのレコード、イベント、および関連するサンドボックスが完全に削除されます。running状態のセッションは削除できません。すぐに削除する必要がある場合は、中断イベントを送信してください。

メモリストア、ボールト、スキル、環境、およびエージェントは独立したリソースであり、セッションの削除による影響を受けません。Files APIを通じてアップロードしたファイルも影響を受けませんが、セッション自体が生成したファイルはセッションにスコープされており、そのファイルシステムとともに完全に削除されます。保持する必要があるものは、セッションを削除する前にダウンロードしてください。

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