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

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

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

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

## Session を作成する

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

| Prop | Type | Default | Description |
| - | - | - | - |
| `agent_id` | `uuid` | - | 実行する agent。その最新の live version がいま束縛され、束縛し直されることはありません。 |
| `display_name?` | `string` | - | 人が読むためのラベル。最大 200 文字。省略すると空です。 |
| `vault_ids?` | `uuid[]` | - | この session が tool credential を引き出せる vault — 最大 10 個、いずれも同じ workspace 内の live な vault。 |

応答には 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 を与えることであり、それ以上ではありません。

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

```http
POST /v1/sessions/{session_id}/tokens
```

## Event ログ

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

```http
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 のストリーミング](/ja/guides/streaming-events)を、すべての種類については [event リファレンス](/ja/reference/events)を参照してください。

## Run が触れるもの

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

1. **コミット済みのログ**

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

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

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

3. **tool broker のバインディング**

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

## 終端状態

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

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