セッション操作

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

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

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

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

新しいエージェントバージョンを作成することなく、セッションの途中でセッションの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になるまで待ちます。ワークフロー実行が開いている場合、それが実行中か一時停止中かにかかわらず、セッションがidleであっても更新は400エラーを返します。中断しても実行は終了しないため、セッションを中断した後も更新は失敗します。エージェントに実行の停止を依頼するuser.messageを送信するか、すべての実行が終了するまで待ってください。

client.beta.sessions.update(
    session.id,
    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"}
        ],
    },
)

セッション予算の更新

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

セッションの取得

retrieved = client.beta.sessions.retrieve(session.id)
print(f"Status: {retrieved.status}")

セッションの一覧表示

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を含むその他のクエリパラメータは、ページネーションされたリクエスト間で変更できます。一覧エンドポイント間で共通のページネーションフィールドについては、ページネーションを参照してください。

# 結果が複数ページにまたがるよう、`limit` を低く設定します。
first_page = client.beta.sessions.list(limit=1, agent_id=agent.id)
# `prev_page` は最初のページでは None、`next_page` は最後のページでは None です。
print(f"prev_page: {first_page.prev_page}")
print(f"next_page: {first_page.next_page}")

# `next_page` を `page` として渡すと次のページを取得できます。
second_page = client.beta.sessions.list(
    limit=1, agent_id=agent.id, page=first_page.next_page
)
for listed_session in second_page.data:
    print(f"{listed_session.id}: {listed_session.status}")

# `prev_page` を `page` として渡すと前のページに戻れます。
previous_page = client.beta.sessions.list(
    limit=1, agent_id=agent.id, page=second_page.prev_page
)
for listed_session in previous_page.data:
    print(f"{listed_session.id}: {listed_session.status}")
# 前方のみの反復であれば、ページオブジェクトを直接イテレートすることもできます。

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

セッションをアーカイブすると、履歴を保持したまま新しいイベントの送信を防止できます。running状態のセッションはアーカイブできません。アーカイブするには、user.interruptイベントを単独で送信し、セッションがidleになるまで待ちます。ワークフロー実行が開いている場合、セッションがidleであってもアーカイブが400エラーを返すことがあり、あるいはアーカイブが成功して実行が終了することもあります。アーカイブする前に、エージェントに実行の停止を依頼するuser.messageを送信するか、各実行が終了するまで待ってください。その後、セッションがidleになったらアーカイブします。

client.beta.sessions.archive(session.id)

セッションの削除

セッションを削除すると、そのレコード、イベント、および関連するサンドボックスが完全に削除されます。running状態のセッションは削除できません。削除するには、user.interruptイベントを単独で送信し、セッションがidleになるまで待ちます。ワークフロー実行が開いている場合、セッションがidleであっても削除が400エラーを返すことがあり、あるいは削除が成功することもあります。削除が成功した後は、セッションの実行の終了を報告するworkflow_runイベントはありません。削除する前に、エージェントに実行の停止を依頼するuser.messageを送信するか、各実行が終了するまで待ってください。その後、セッションがidleになったら削除します。

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

client.beta.sessions.delete(session.id)