> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Session イベントストリーム

> SSE で Agent の思考、メッセージ、ツール呼び出し、ステータスをストリーミング。

Qoder Cloud Agents は **Server-Sent Events (SSE)** を通じて、公開 Session イベントをストリーミングします。

## 接続 URL

```text theme={null}
GET https://api.qoder.com/api/v1/cloud/sessions/{session_id}/events/stream
```

リクエストヘッダー:

```text theme={null}
Authorization: Bearer $QODER_PAT
Accept: text/event-stream
```

ストリームエンドポイントは再接続時のリプレイのために `Last-Event-ID` ヘッダーをサポートします。最後に受信したイベントの `id` を渡すと、その ID の次のイベントからストリームが再開されます。イベントタイプによるクエリフィルタは現在サポートされていません。

増分ストリーミングは Session 作成時に Session ごとに有効化します。

```json theme={null}
{
  "incremental_streaming_enabled": true
}
```

1 つのストリーム接続のみで増分イベントを有効化するクエリパラメータやヘッダーはありません。フラグを有効にすると、同じ stream および list エンドポイントが、最終的な完全イベントに加えて増分イベントを公開します。クイックな検証フローについては [Incremental streaming](/ja/cloud-agents/incremental-streaming) を参照してください。

## SSE 形式

各イベントは標準の SSE フィールドを使用します。

```text theme={null}
id: evt_019e392c0d787cfaa21bda98e06cd913
event: agent.message
data: {"id":"evt_019e392c0d787cfaa21bda98e06cd913","type":"agent.message","content":[{"type":"text","text":"Hello"}],"processed_at":"2026-05-18T03:40:48.888851795Z"}
```

接続を維持するためにハートビートコメントが送信される場合があります。

## 典型的なイベントフロー

```text theme={null}
user.message
session.status_running
span.model_request_start
agent.thinking
agent.tool_use
agent.tool_result
agent.message
span.model_request_end
session.status_idle
```

すべてのターンがすべてのイベントを含むわけではありません。マネージド Agent の Session では、`session.thread_created`、`session.thread_status_running`、`agent.thread_message_sent`、`agent.thread_message_received` などのスレッドイベントも発行されることがあります。

> 注意: 公開される `agent.thinking` イベントには `id`、`processed_at`、`type` のみが含まれます。推論内容は意図的に公開されません。Agent が推論のために一時停止したことを示すマーカーとして扱ってください。他にもいくつかの Agent 生成イベントは `processed_at` を省略します。パース時にはこのフィールドを任意として扱ってください。

## 増分イベント

`incremental_streaming_enabled` が `true` の場合、クライアントは次のトップレベルの増分イベントタイプを受信することがあります。

`agent.message_start`、`agent.content_block_start`、`agent.content_block_delta`、`agent.content_block_stop`、`agent.message_delta`、`agent.message_stop`。

典型的なアシスタントメッセージの増分は、次の順序で現れます。

```text theme={null}
agent.message_start
agent.content_block_start
agent.content_block_delta
agent.content_block_stop
agent.message_delta
agent.message_stop
```

テキストチャンク、thinking チャンク、ツール入力チャンクなどの delta 概念は、`agent.content_block_delta.delta.type` 内で伝えられます。例:

```json theme={null}
{
  "type": "agent.content_block_delta",
  "index": 0,
  "delta": {
    "type": "text_delta",
    "text": "Hello"
  }
}
```

現在の実装ではツール出力のチャンクをストリーミングしません。ツール結果は引き続き完全な `agent.tool_result` イベントとして届きます。

## 接続のライフサイクル

* `session.status_idle` は現在のターンが終了したことを示します。接続は開いたまま、次のターンを待つべきです。
* `session.status_terminated` と `session.deleted` は終端状態です。クライアントは再接続を停止すべきで、以降イベントは届きません。
* `session.status_rescheduled` は一時的なシグナルです。ストリームは一時的に切断されることがありますが、ランタイムの準備が整うと再接続されます。
* ストリーム途中でネットワークが切断された場合は、最後に受信したイベント ID を `Last-Event-ID` ヘッダーに設定して再接続してください。サーバーはその時点以降のイベントをリプレイします。

## ツールの応答

ストリームが確認を必要とする `agent.tool_use` を発行した場合、ツールイベントの ID を付けて `POST /api/v1/cloud/sessions/{session_id}/events` に `user.tool_confirmation` を送信します。

```json theme={null}
{
  "events": [
    {
      "type": "user.tool_confirmation",
      "tool_use_id": "evt_01JZ6Q3FB6SG8F7J1M2N",
      "result": "allow"
    }
  ]
}
```

ストリームが `agent.custom_tool_use` を発行した場合は、クライアント側でカスタムツールを実行し、`user.custom_tool_result` を送信します。

## イベント履歴

履歴イベントとページングにはリストエンドポイントを使用します。

```bash theme={null}
curl -s "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID/events?limit=20&order=desc" \
  -H "Authorization: Bearer $QODER_PAT"
```

リストのレスポンスは `data` と `next_page` を使用します。[List events](/ja/cloud-agents/api/sessions/list-events) と [Session schemas](/ja/cloud-agents/api/sessions/schemas#public-event-types) を参照してください。