セッション操作

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



セッションステータス

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



エージェント設定の更新

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

セッション作成後に変更できるのは、エージェントのtoolsとmcp_serversのみです。エージェントとは異なるmodel、system、またはskillsの値でセッションを実行するには、セッション作成時にエージェント設定のオーバーライドを使用してください。エージェントに設定された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



セッションの取得

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エラーが返されます。フィルターや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状態のセッションは削除できません。すぐに削除する必要がある場合は、中断イベントを送信してください。

ファイル、メモリストア、ボールト、スキル、環境、およびエージェントは独立したリソースであり、セッションの削除による影響を受けません。

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