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

# 스트리밍 이벤트

> SessionConfig의 streaming을 활성화했을 때 받을 수 있는 Session Event 종류와 payload를 정리합니다.

## 스트리밍 이벤트

`SessionConfig`에서 `streaming: true`를 활성화하면 세션 중의 동작이 이벤트로 순차 전송됩니다.
이 페이지는 공식 `streaming-events.md`를 Laravel용으로 읽기 쉽게 정리한 한국어 버전입니다.

> [SessionEvent](/ko/packages/laravel-copilot-sdk/session-event) 페이지는 Laravel용으로 확장한 `SessionEvent` 클래스 자체의 설명입니다.
> 이 페이지는 "어떤 이벤트 타입으로 어떤 데이터가 도착하는가"의 레퍼런스입니다.

## 개요

Copilot 에이전트의 처리(추론, 메시지 생성, 도구 실행, 권한 확인 등)는 모두 세션 이벤트로 흐릅니다.

* **Ephemeral event**: 실시간 배포만. 세션 로그에는 영속화되지 않음(재개 시 재생되지 않음)
* **Persisted event**: 세션 로그에 저장됨(재개 시 재생됨)
* **Delta event**: 단편적으로 도착하는 차분 이벤트(`deltaContent` 등). 연결해서 전문을 구성
* **`parentId` chain**: 각 이벤트가 직전 이벤트 ID를 참조하는 연쇄

## Event envelope(공통 필드)

모든 이벤트는 다음 공통 구조를 가집니다.

| Field       | Type             | 설명                        |
| ----------- | ---------------- | ------------------------- |
| `id`        | `string`         | 이벤트 고유 ID(UUID v4)        |
| `timestamp` | `string`         | 작성 시각(ISO 8601)           |
| `parentId`  | `string \| null` | 직전 이벤트 ID(선두 이벤트는 `null`) |
| `ephemeral` | `boolean?`       | 일시 이벤트인 경우 `true`         |
| `type`      | `string`         | 이벤트 타입                    |
| `data`      | `object`         | 이벤트 고유의 페이로드              |

## Laravel에서의 구독 예시

```php theme={null}
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Enums\SessionEventType;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\SessionEvent;

Copilot::start(function (CopilotSession $session): void {
    // 전 이벤트
    $session->on(function (SessionEvent $event): void {
        info($event->type(), $event->toArray());
    });

    // 특정 이벤트
    $session->on(SessionEventType::ASSISTANT_MESSAGE_DELTA, function (SessionEvent $event): void {
        echo $event->deltaContent();
    });

    $session->sendAndWait(prompt: 'Laravel의 특징을 알려줘');
}, config: new SessionConfig(streaming: true));
```

## 주요 이벤트 카테고리

## Assistant events

### `assistant.turn_start`

턴 시작.

* `turnId`(필수)
* `interactionId`(임의)

### `assistant.intent`(ephemeral)

현재 실행 의도(예: `Exploring codebase`).

* `intent`(필수)

### `assistant.reasoning`

추론 블록의 완성판.

* `reasoningId`(필수)
* `content`(필수)

### `assistant.reasoning_delta`(ephemeral)

추론 텍스트의 차분.

* `reasoningId`(필수)
* `deltaContent`(필수)

### `assistant.message`

어시스턴트의 완성 메시지.

주요 필드:

* `messageId`(필수)
* `content`(필수)
* `toolRequests`(임의)
* `reasoningOpaque` / `reasoningText` / `encryptedContent`(임의)
* `phase` / `outputTokens` / `interactionId`(임의)
* `parentToolCallId`(임의, 서브에이전트 유래 시)

### `assistant.message_delta`(ephemeral)

메시지 본문의 차분.

* `messageId`(필수)
* `deltaContent`(필수)
* `parentToolCallId`(임의)

### `assistant.turn_end`

턴 종료.

* `turnId`(필수)

### `assistant.usage`(ephemeral)

API 호출 단위의 사용량 정보.

주요 필드:

* `model`(필수)
* `inputTokens` / `outputTokens` / `cost` / `duration`(임의)
* `apiCallId` / `providerCallId`(임의)
* `quotaSnapshots` / `copilotUsage`(임의)

### `assistant.streaming_delta`(ephemeral)

저수준 수신 진척.

* `totalResponseSizeBytes`(필수)

## Tool execution events

### `tool.execution_start`

도구 실행 시작.

* `toolCallId`(필수)
* `toolName`(필수)
* `arguments` / `mcpServerName` / `mcpToolName` / `parentToolCallId`(임의)

### `tool.execution_partial_result`(ephemeral)

도구 실행 중의 부분 출력.

* `toolCallId`(필수)
* `partialOutput`(필수)

### `tool.execution_progress`(ephemeral)

진척 메시지.

* `toolCallId`(필수)
* `progressMessage`(필수)

### `tool.execution_complete`

도구 실행 완료(성공/실패).

* `toolCallId`(필수)
* `success`(필수)
* `result`(성공 시)
* `error`(실패 시)
* `toolTelemetry` / `parentToolCallId`(임의)

### `tool.user_requested`

사용자 명시 요구에 의한 도구 호출.

* `toolCallId`(필수)
* `toolName`(필수)
* `arguments`(임의)

## Session lifecycle events

### `session.start`

세션 시작. Cloud Sessions에서는 `producer`가 `copilot-agent`의 `session.start`를 확인한 후에 최초 프롬프트를 보내는 것이 안전합니다.

* `producer`(임의)

### `session.idle`(ephemeral)

현재 처리가 완료되고 다음 입력을 대기.

* `backgroundTasks`(임의)

### `session.error`

세션 처리 중의 에러.

* `errorType`(필수)
* `message`(필수)
* `stack` / `statusCode` / `providerCallId`(임의)

### `session.compaction_start`

컨텍스트 압축 시작(`data`는 빈 오브젝트).

### `session.compaction_complete`

컨텍스트 압축 완료.

주요 필드:

* `success`(필수)
* `error`(임의)
* `preCompactionTokens` / `postCompactionTokens`(임의)
* `summaryContent` / `checkpointPath`(임의)

### `session.title_changed`(ephemeral)

자동 타이틀 업데이트.

* `title`(필수)

### `session.context_changed`

작업 컨텍스트 변경.

* `cwd`(필수)
* `gitRoot` / `repository` / `branch`(임의)

### `session.info`

리모트 URL 등의 세션 정보.

* `infoType`(필수)
* `url`(임의, `infoType`가 `remote`인 경우 등)

### `session.remote_steerable_changed`

Mission Control로부터의 원격 조작 가부가 변경되었음을 나타내는 이벤트.

* `remoteSteerable`(임의)

### `session.usage_info`(ephemeral)

컨텍스트 윈도우 이용 상황.

* `tokenLimit`(필수)
* `currentTokens`(필수)
* `messagesLength`(필수)

### `session.task_complete`

태스크 완료 통지.

* `summary`(임의)

### `session.shutdown`

세션 종료.

주요 필드:

* `shutdownType`(필수)
* `errorReason`(임의)
* `totalPremiumRequests` / `totalApiDurationMs`(필수)
* `codeChanges` / `modelMetrics`(필수)

## Permission / user input events

### `permission.requested`(ephemeral)

권한 확인 요구.

* `requestId`(필수)
* `permissionRequest`(필수)

`permissionRequest.kind`:

* `shell`
* `write`
* `read`
* `mcp`
* `url`
* `memory`
* `custom-tool`

### `permission.completed`(ephemeral)

권한 확인의 해결 결과.

* `requestId`(필수)
* `result.kind`(필수)

### `user_input.requested`(ephemeral)

사용자에게의 질문.

* `requestId`(필수)
* `question`(필수)
* `choices` / `allowFreeform`(임의)

### `user_input.completed`(ephemeral)

사용자 입력 완료.

* `requestId`(필수)

### `elicitation.requested`(ephemeral)

구조화 입력(폼) 요구.

* `requestId`(필수)
* `message`(필수)
* `requestedSchema`(필수)

### `elicitation.completed`(ephemeral)

구조화 입력의 완료.

* `requestId`(필수)

## Sub-agent / skill events

### `subagent.started`

* `toolCallId`(필수)
* `agentName` / `agentDisplayName` / `agentDescription`(필수)

### `subagent.completed`

* `toolCallId`(필수)
* `agentName` / `agentDisplayName`(필수)

### `subagent.failed`

* `toolCallId`(필수)
* `agentName` / `agentDisplayName`(필수)
* `error`(필수)

### `subagent.selected`

* `agentName`(필수)
* `agentDisplayName`(필수)
* `tools`(필수, `null` 허용)

### `subagent.deselected`

기본 에이전트로 복귀(`data`는 빈 오브젝트).

### `skill.invoked`

* `name` / `path` / `content`(필수)
* `allowedTools` / `pluginName` / `pluginVersion`(임의)

## Other events

### `abort`

* `reason`(필수)

### `user.message`

* `content`(필수)
* `transformedContent` / `attachments` / `source` / `agentMode` / `interactionId`(임의)

### `system.message`

* `content`(필수)
* `role`(필수)
* `name` / `metadata`(임의)

### `external_tool.requested`(ephemeral)

* `requestId` / `sessionId` / `toolCallId` / `toolName`(필수)
* `arguments`(임의)

### `external_tool.completed`(ephemeral)

* `requestId`(필수)

### `exit_plan_mode.requested`(ephemeral)

* `requestId` / `summary` / `planContent` / `actions` / `recommendedAction`(필수)

### `exit_plan_mode.completed`(ephemeral)

* `requestId`(필수)

### `command.queued`(ephemeral)

* `requestId`(필수)
* `command`(필수)

### `command.completed`(ephemeral)

* `requestId`(필수)

## 전형적인 이벤트 순서

```text theme={null}
assistant.turn_start
├── assistant.intent (ephemeral)
├── assistant.reasoning_delta (ephemeral, 여러 번)
├── assistant.reasoning
├── assistant.message_delta (ephemeral, 여러 번)
├── assistant.message
├── assistant.usage (ephemeral)
├── [필요에 따라 permission / tool.*이 루프]
assistant.turn_end
session.idle (ephemeral)
```

## 전체 이벤트 목록(퀵 레퍼런스)

| Event Type                         | Ephemeral | Category      |
| ---------------------------------- | --------- | ------------- |
| `session.start`                    |           | Session       |
| `assistant.turn_start`             |           | Assistant     |
| `assistant.intent`                 | ✅         | Assistant     |
| `assistant.reasoning`              |           | Assistant     |
| `assistant.reasoning_delta`        | ✅         | Assistant     |
| `assistant.streaming_delta`        | ✅         | Assistant     |
| `assistant.message`                |           | Assistant     |
| `assistant.message_delta`          | ✅         | Assistant     |
| `assistant.turn_end`               |           | Assistant     |
| `assistant.usage`                  | ✅         | Assistant     |
| `tool.user_requested`              |           | Tool          |
| `tool.execution_start`             |           | Tool          |
| `tool.execution_partial_result`    | ✅         | Tool          |
| `tool.execution_progress`          | ✅         | Tool          |
| `tool.execution_complete`          |           | Tool          |
| `session.idle`                     | ✅         | Session       |
| `session.error`                    |           | Session       |
| `session.compaction_start`         |           | Session       |
| `session.compaction_complete`      |           | Session       |
| `session.title_changed`            | ✅         | Session       |
| `session.context_changed`          |           | Session       |
| `session.info`                     |           | Session       |
| `session.remote_steerable_changed` |           | Session       |
| `session.usage_info`               | ✅         | Session       |
| `session.task_complete`            |           | Session       |
| `session.shutdown`                 |           | Session       |
| `permission.requested`             | ✅         | Permission    |
| `permission.completed`             | ✅         | Permission    |
| `user_input.requested`             | ✅         | User Input    |
| `user_input.completed`             | ✅         | User Input    |
| `elicitation.requested`            | ✅         | User Input    |
| `elicitation.completed`            | ✅         | User Input    |
| `subagent.started`                 |           | Sub-Agent     |
| `subagent.completed`               |           | Sub-Agent     |
| `subagent.failed`                  |           | Sub-Agent     |
| `subagent.selected`                |           | Sub-Agent     |
| `subagent.deselected`              |           | Sub-Agent     |
| `skill.invoked`                    |           | Skill         |
| `abort`                            |           | Control       |
| `user.message`                     |           | User          |
| `system.message`                   |           | System        |
| `external_tool.requested`          | ✅         | External Tool |
| `external_tool.completed`          | ✅         | External Tool |
| `command.queued`                   | ✅         | Command       |
| `command.completed`                | ✅         | Command       |
| `exit_plan_mode.requested`         | ✅         | Plan Mode     |
| `exit_plan_mode.completed`         | ✅         | Plan Mode     |

## 관련 문서

* [공식 Streaming Events 레퍼런스](https://github.com/github/copilot-sdk/blob/main/docs/features/streaming-events.md)
* Laravel 버전의 이벤트 클래스 설명: [SessionEvent](/ko/packages/laravel-copilot-sdk/session-event)
* 스트리밍 구현 패턴: [Streaming](/ko/packages/laravel-copilot-sdk/streaming)


## Related topics

- [스트리밍](/ko/packages/laravel-copilot-sdk/streaming.md)
- [Laravel AI SDK용 Amazon Bedrock 드라이버](/ko/packages/laravel-amazon-bedrock.md)
- [지연 서비스 프로바이더](/ko/advanced/deferred-provider.md)
- [Laravel에서 MCP 서버 만들기](/ko/advanced/mcp-server.md)
- [Laravel Prompts](/ko/prompts.md)