스트리밍 이벤트

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

SessionEvent 페이지는 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에서의 구독 예시

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(필수)

전형적인 이벤트 순서

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