Session と run

Session は追記専用の event ログです。Run は engine がその上を 1 回通過することです。Agent について観測できるものはすべて event です。

Session はひとつの作業単位です — 会話、チケット、バックグラウンドジョブ。Workspace に属し、作成時に agent version を束縛し、起きたことすべての追記専用ログを保持します。

Run は、engine がそのログの上を 1 回通過することです。ユーザー入力を追記すると run が始まり、run は進みながら自分の event を追記し、ちょうどひとつの終端 event で終わります。

この区別が重要なのは、session が run より長生きするからです。Run は失敗することも、キャンセルされることも、見ていた接続を失うこともありますが、session はログを保ったままそこにあります。

Session を作成する

{
  "agent_id": "…",
  "display_name": "ticket-4192",
  "vault_ids": ["…"]
}

PropType

agent_iduuid

実行する agent。その最新の live version がいま束縛され、束縛し直されることはありません。

Typeuuid

display_name?string

人が読むためのラベル。最大 200 文字。省略すると空です。

Typestring

vault_ids?uuid[]

この session が tool credential を引き出せる vault — 最大 10 個、いずれも同じ workspace 内の live な vault。

Typeuuid[]

応答には session と、一度だけ表示される最初の session token が含まれます。

2 つの credential、2 つの役割

	API key	Session token
スコープ	ひとつの workspace	ひとつの session
持つもの	発行時に与えられた permission	permission は一切なし
置き場所	あなたのサーバー	必要な場所どこでも — ブラウザのタブ、worker
失効	取り消したとき、または `expires_at`	`session_token_expires_at`

Session token は自分の session を読み、そこに入力を追記し、client を登録できます。Session の一覧取得も、session の作成も、workspace 内の他のものに触れることもできません — つまり、これをフロントエンドに渡すことは、そのフロントエンドにちょうどひとつの session を与えることであり、それ以上ではありません。

必要な数だけ発行してください。

POST /v1/sessions/{session_id}/tokens

Event ログ

すべての event はシーケンス番号を持ち、ログは session についての完全な真実です。Run は event であり、メッセージは event であり、tool call とその結果も event、client の参加も event です。

GET  /v1/sessions/{session_id}/events          # paged, newest first by default
GET  /v1/sessions/{session_id}/events/stream   # SSE, tail and resume
POST /v1/sessions/{session_id}/events          # append user input, starting a run
POST /v1/sessions/{session_id}/cancel          # ask the current run to stop

追尾と再開のルールは Event のストリーミングを、すべての種類については event リファレンスを参照してください。

Run が触れるもの

Run が確保されると、engine は 3 つのものを渡されます。いずれもその run だけにスコープされています。

コミット済みのログ

Engine はすでに保存された event から状態を組み立て直します。だから失敗した run の次に走る run は、前の試行が起きていると思っていたことではなく、実際に起きたことから始まります。

モデルプロキシのバインディング

確保時に新しく発行される URL と run token。あなたの provider キーが engine に渡されることはなく — プロキシが保持します。古い試行の token は、run が再確保された瞬間に効かなくなります。

tool broker のバインディング

URL、run token、そして束縛された version が grant するサーバー名の一覧。Credential も、上流の URL も、ポリシーも渡されません — 呼び出しが届いたときに broker がその 3 つを自分で解決します。

終端状態

Event	意味
`run_completed`	モデルが自分のターンを終え、やることが残っていない。
`run_failed`	run がエラーで停止した。`error` にその内容が入る。
`run_cancelled`	キャンセル要求が受け入れられた。

実行中の run がない session は idle であって、終了したわけではありません。さらに入力を追記すれば、同じログに対して新しい run が始まります。