Copilot SDK의 스트리밍 이벤트

참고

          코필로트 SDK가 현재 기술 미리 보기에 있습니다. 기능 및 가용성은 변경될 수 있습니다.

에이전트가 Copilot 수행하는 모든 작업(생각, 코드 작성, 실행 도구)은 구독할 수 있는 세션 이벤트 로 내보내집니다. 이 문서는 각 이벤트 유형에 대한 필드 수준 참조이므로 예상되는 데이터를 정확히 알 수 있습니다.

세션에서 설정되면 streaming: true SDK는 지속형 이벤트(전체 메시지, 도구 결과)와 함께 임시 이벤트(델타, 진행률 업데이트)를 실시간으로 내보냅니다. 모든 이벤트는 공통 엔벨로프를 공유하며, 이벤트 type 형식에 따라 달라지는 data 페이로드를 전달합니다. 전체 이벤트 흐름의 시퀀스 다이어그램은 리포지토리를github/copilot-sdk 참조하세요.

개념	설명

          **임시 이벤트** | 일시적인; 실시간으로 스트리밍되지만 세션 로그에 유지 **되지 않습니다** . 세션 다시 시작에서 재생되지 않습니다. |

이벤트 봉투

형식에 관계없이 모든 세션 이벤트에는 다음 필드가 포함됩니다.

분야	유형	설명
`id`

          `string` (UUID v4) | 고유 이벤트 식별자 |

이벤트 구독

// All events
session.on((event) => {
    console.log(event.type, event.data);
});

// Specific event type — data is narrowed automatically
session.on("assistant.message_delta", (event) => {
    process.stdout.write(event.data.deltaContent);
});

Python, Go 및 .NET의 예제는 리포지토리를github/copilot-sdk 참조하세요.

팁

          **Python/Go:** 이러한 SDK는 가능한 모든 필드가 있는 단일 `Data` 클래스/구조체를 선택적/nullable로 사용합니다. 아래 표에 나열된 필드만 각 이벤트 유형에 대해 채워집니다. 나머지는 다음과 같습니다 `None` / `nil`.

          **.Net:** .NET SDK는 이벤트당 강력한 형식의 별도의 데이터 클래스를 `AssistantMessageDeltaData`사용하므로 각 형식에 관련 필드만 존재합니다.

          **TypeScript:** TypeScript SDK는 식별된 유니온을 사용합니다. 일치 항목을 기준으로 하면 `event.type`가 `data` 페이로드를 자동으로 올바른 형식으로 좁힙니다.

도우미 이벤트

이러한 이벤트는 턴 시작부터 스트리밍 청크를 거쳐 최종 메시지까지 에이전트의 응답 수명 주기를 추적합니다.

`assistant.turn_start`

에이전트가 턴 처리를 시작할 때 내보내집니다.

데이터 필드	유형	필수	설명
`turnId`	`string`	✅	턴 식별자(일반적으로 문자열화된 턴 번호)
`interactionId`	`string`
원격 분석 상관 관계에 대한 상호 작용 식별자

`assistant.intent`

임시. 에이전트가 현재 수행하는 작업에 대한 간단한 설명이며 작동하면서 업데이트됩니다.

데이터 필드	유형	필수	설명
`intent`	`string`	✅	사람이 읽을 수 있는 의도(예: "코드베이스 탐색")

`assistant.reasoning`

모델에서 확장된 사고 블록을 완성합니다. 추론이 완료된 후 내보냅니다.

데이터 필드	유형	필수	설명
`reasoningId`	`string`	✅	이 추론 블록의 고유 식별자
`content`	`string`	✅	확장된 사고 전체 텍스트

`assistant.reasoning_delta`

임시. 모델의 확장된 사고의 증분 조각이 실시간으로 스트리밍됩니다.

데이터 필드	유형	필수	설명
`reasoningId`	`string`	✅	해당 이벤트와 일치 `assistant.reasoning`
`deltaContent`	`string`	✅	추론 콘텐츠에 추가할 텍스트 청크

`assistant.message`

이 LLM 호출에 대한 도우미의 전체 응답입니다. 도구 호출 요청을 포함할 수 있습니다.

데이터 필드	유형	필수	설명
`messageId`	`string`	✅	이 메시지의 고유 식별자
`content`	`string`	✅	도우미의 텍스트 응답
`toolRequests`	`ToolRequest[]`
도우미가 수행하려는 도구 호출(아래 참조)
`reasoningOpaque`	`string`
암호화된 확장 사고(인류 모델); 세션 바인딩
`reasoningText`	`string`
확장된 사고에서 읽을 수 있는 추론 텍스트
`encryptedContent`	`string`
암호화된 추론 콘텐츠(OpenAI 모델); 세션 바인딩
`phase`	`string`
생성 단계(예: `"thinking"` 대 `"response"`)
`outputTokens`	`number`
API 응답의 실제 출력 토큰 수
`interactionId`	`string`
원격 분석에 대한 상호 작용 식별자
`parentToolCallId`	`string`
이 메시지가 하위 에이전트에서 시작되는 경우 설정

          **
          `ToolRequest` 필드:**

분야	유형	필수	설명
`toolCallId`	`string`	✅	이 도구 호출의 고유 ID
`name`	`string`	✅	도구 이름(예: `"bash"`, `"edit"`, `"grep"`)
`arguments`	`object`
구문 분석된 도구의 인수
`type`	`"function" \| "custom"`
호출 유형; 없는 경우 기본값은 `"function"` 입니다.

`assistant.message_delta`

임시. 실시간으로 스트리밍되는 도우미 텍스트 응답의 증분 청크입니다.

데이터 필드	유형	필수	설명
`messageId`	`string`	✅	해당 이벤트와 일치 `assistant.message`
`deltaContent`	`string`	✅	메시지에 추가할 텍스트 청크
`parentToolCallId`	`string`
하위 에이전트에서 시작될 때 설정

`assistant.turn_end`

에이전트가 턴을 완료할 때 내보내집니다(모든 도구 실행이 완료되고 최종 응답이 전달됨).

데이터 필드	유형	필수	설명
`turnId`	`string`	✅	해당 이벤트와 일치 `assistant.turn_start`

`assistant.usage`

임시. 개별 API 호출에 대한 토큰 사용량 및 비용 정보입니다.

데이터 필드	유형	필수	설명
`model`	`string`	✅	모델 식별자(예: `"gpt-4.1"`)
`inputTokens`	`number`
사용된 입력 토큰
`outputTokens`	`number`
생성된 출력 토큰
`cacheReadTokens`	`number`
프롬프트 캐시에서 읽은 토큰
`cacheWriteTokens`	`number`
프롬프트 캐시에 기록된 토큰
`cost`	`number`
청구에 대한 모델 승수 비용
`duration`	`number`
API 호출 기간(밀리초)
`initiator`	`string`
이 호출을 트리거한 항목(예: `"sub-agent"`); 사용자가 시작한 경우 없음
`apiCallId`	`string`
공급자의 완료 ID(예: `chatcmpl-abc123`)
`providerCallId`	`string`

          GitHub 요청 추적 ID(`x-github-request-id`) |

`assistant.streaming_delta`

임시. 낮은 수준의 네트워크 진행률 표시기 - 스트리밍 API 응답에서 받은 총 바이트 수입니다.

데이터 필드	유형	필수	설명
`totalResponseSizeBytes`	`number`	✅	지금까지 받은 누적 바이트

도구 실행 이벤트

이러한 이벤트는 실행부터 완료까지 도구 호출을 요청하는 모델에서 각 도구 호출의 전체 수명 주기를 추적합니다.

`tool.execution_start`

도구 실행을 시작할 때 내보냅니다.

데이터 필드	유형	필수	설명
`toolCallId`	`string`	✅	이 도구 호출에 대한 고유 식별자
`toolName`	`string`	✅	도구의 이름(예: `"bash"`, , "edit"``"grep")
`arguments`	`object`
구문 분석된 인수가 도구에 전달됨
`mcpServerName`	`string`
MCP 서버에서 도구를 제공하는 경우 MCP 서버 이름
`mcpToolName`	`string`
MCP 서버의 원래 도구 이름
`parentToolCallId`	`string`
하위 에이전트에서 호출할 때 설정

`tool.execution_partial_result`

임시. 실행 중인 도구의 증분 출력(예: 스트리밍 bash 출력).

데이터 필드	유형	필수	설명
`toolCallId`	`string`	✅	해당 항목과 일치 `tool.execution_start`
`partialOutput`	`string`	✅	증분 출력 청크

`tool.execution_progress`

임시. 실행 중인 도구에서 사람이 읽을 수 있는 진행 상태(예: MCP 서버 진행률 알림).

데이터 필드	유형	필수	설명
`toolCallId`	`string`	✅	해당 항목과 일치 `tool.execution_start`
`progressMessage`	`string`	✅	진행 상태 메시지

`tool.execution_complete`

도구 실행이 성공적으로 또는 오류와 함께 완료될 때 내보냅니다.

데이터 필드	유형	필수	설명
`toolCallId`	`string`	✅	해당 항목과 일치 `tool.execution_start`
`success`	`boolean`	✅	실행 성공 여부
`model`	`string`
이 도구 호출을 생성한 모델
`interactionId`	`string`
상호 작용 식별자
`isUserRequested`	`boolean`

          `true` 사용자가 이 도구 호출을 명시적으로 요청한 경우 |

| result | Result | | 성공 시 프레젠테이션(아래 참조) | | error | { message, code? } | | 실패 시 표시됨 | | toolTelemetry | object | | 도구별 원격 분석 | | parentToolCallId | string | | 하위 에이전트에서 호출할 때 설정 |

          **
          `Result` 필드:**

분야	유형	필수	설명
`content`	`string`	✅	LLM으로 전송된 간결한 결과(토큰 효율성을 위해 잘려질 수 있음)
`detailedContent`	`string`
전체 표시 결과, diffs와 같은 전체 콘텐츠 유지
`contents`	`ContentBlock[]`
구조적 콘텐츠 블록(텍스트, 터미널, 이미지, 오디오, 리소스)

`tool.user_requested`

사용자가 도구 호출을 명시적으로 요청할 때 내보내집니다(모델이 호출하도록 선택하는 대신).

데이터 필드	유형	필수	설명
`toolCallId`	`string`	✅	이 도구 호출에 대한 고유 식별자
`toolName`	`string`	✅	사용자가 호출하려는 도구의 이름
`arguments`	`object`
호출에 대한 인수

세션 수명 주기 이벤트

`session.idle`

임시. 에이전트가 모든 처리를 완료했으며 다음 메시지를 준비했습니다. 이는 턴이 완전히 완료되었다는 신호입니다.

데이터 필드	유형	필수	설명
`backgroundTasks`	`BackgroundTasks`
에이전트가 유휴 상태가 되었을 때 백그라운드 에이전트/셸이 계속 실행됩니다.

`session.error`

세션 처리 중에 오류가 발생했습니다.

데이터 필드	유형	필수	설명
`errorType`	`string`	✅	오류 범주(예: `"authentication"`, `"quota"`, `"rate_limit"`)
`message`	`string`	✅	사람이 읽을 수 있는 오류 메시지
`stack`	`string`
오류 스택 추적
`statusCode`	`number`
업스트림 요청의 HTTP 상태 코드
`providerCallId`	`string`

          GitHub 서버 쪽 로그 상관 관계에 대한 요청 추적 ID |

`session.compaction_start`

컨텍스트 창 압축이 시작되었습니다. 데이터 페이로드가 비어 있습니다({}).

`session.compaction_complete`

컨텍스트 창 압축이 완료되었습니다.

데이터 필드	유형	필수	설명
`success`	`boolean`	✅	압축 성공 여부
`error`	`string`
압축에 실패한 경우 오류 메시지
`preCompactionTokens`	`number`
압축 전 토큰
`postCompactionTokens`	`number`
압축 후 토큰
`preCompactionMessagesLength`	`number`
압축 전 메시지 수
`messagesRemoved`	`number`
제거된 메시지
`tokensRemoved`	`number`
제거된 토큰
`summaryContent`	`string`
압축된 기록의 LLM 생성 요약
`checkpointNumber`	`number`
복구를 위해 만든 검사점 스냅샷 번호
`checkpointPath`	`string`
검사점이 저장된 파일 경로
`compactionTokensUsed`	`{ input, output, cachedInput }`
압축 LLM 호출에 대한 토큰 사용량
`requestId`	`string`

          GitHub 압축 호출에 대한 요청 추적 ID |

`session.title_changed`

임시. 세션의 자동 생성된 타이틀이 업데이트되었습니다.

데이터 필드	유형	필수	설명
`title`	`string`	✅	새 세션 제목

`session.context_changed`

세션의 작업 디렉터리 또는 리포지토리 컨텍스트가 변경되었습니다.

데이터 필드	유형	필수	설명
`cwd`	`string`	✅	현재 작업 디렉터리
`gitRoot`	`string`
Git 리포지토리 루트
`repository`	`string`
형식의 `"owner/name"` 리포지토리
`branch`	`string`
현재 Git 브랜치

`session.usage_info`

임시. 컨텍스트 창 사용률 스냅샷

데이터 필드	유형	필수	설명
`tokenLimit`	`number`	✅	모델의 컨텍스트 창에 대한 최대 토큰
`currentTokens`	`number`	✅	컨텍스트 창의 현재 토큰
`messagesLength`	`number`	✅	대화의 현재 메시지 수

`session.task_complete`

에이전트가 할당된 작업을 완료했습니다.

데이터 필드	유형	필수	설명
`summary`	`string`
완료된 작업의 요약

`session.shutdown`

세션이 종료되었습니다.

데이터 필드	유형	필수	설명
`shutdownType`	`"routine" \| "error"`	✅	정상적인 종료 또는 충돌
`errorReason`	`string`

          `shutdownType`이 `"error"`일 때 오류 설명 |

| totalPremiumRequests | number | ✅ | 사용된 총 프리미엄 API 요청 | | totalApiDurationMs | number | ✅ | 누적 API 호출 시간(밀리초) | | sessionStartTime | number | ✅ | 세션이 시작된 때의 Unix 타임스탬프(ms) | | codeChanges | { linesAdded, linesRemoved, filesModified } | ✅ | 집계 코드 변경 메트릭 | | modelMetrics | Record<string, ModelMetric> | ✅ | 모델별 사용량 분석 | | currentModel | string | | 종료 시 선택한 모델 |

권한 및 사용자 입력 이벤트

이러한 이벤트는 에이전트가 계속하기 전에 사용자의 승인 또는 입력이 필요할 때 내보내집니다.

`permission.requested`

임시. 에이전트는 작업을 수행할 수 있는 권한이 필요합니다(명령 실행, 파일 쓰기 등).

데이터 필드	유형	필수	설명
`requestId`	`string`	✅	이를 통해 응답하세요. `session.respondToPermission()`
`permissionRequest`	`PermissionRequest`	✅	요청되는 권한의 세부 정보

          `permissionRequest`는 `kind`에 대한 구별된 합집합입니다.

`kind`	주요 필드	설명
`"shell"`

          `fullCommandText`, `intention`, , `commands[]`, `possiblePaths[]` | 셸 명령 실행 |

또한 모든 kind 변형에는 요청을 트리거한 도구 호출에 대한 선택적 toolCallId 연결도 포함됩니다.

`permission.completed`

임시. 권한 요청이 해결되었습니다.

데이터 필드	유형	필수	설명
`requestId`	`string`	✅	해당 항목과 일치 `permission.requested`
`result.kind`	`string`	✅	다음 중 하나: `"approved"`, `"denied-by-rules"`, `"denied-interactively-by-user"`, "denied-no-approval-rule-and-could-not-request-from-user"``"denied-by-content-exclusion-policy"

`user_input.requested`

임시. 에이전트가 사용자에게 질문을 하고 있습니다.

데이터 필드	유형	필수	설명
`requestId`	`string`	✅	다음 방법으로 응답하십시오: `session.respondToUserInput()`
`question`	`string`	✅	사용자에게 제시할 질문
`choices`	`string[]`
사용자에 대해 미리 정의된 선택
`allowFreeform`	`boolean`
자유 형식 텍스트 입력 허용 여부

`user_input.completed`

임시. 사용자 입력 요청이 확인되었습니다.

데이터 필드	유형	필수	설명
`requestId`	`string`	✅	해당 항목과 일치 `user_input.requested`

`elicitation.requested`

임시. 에이전트에는 사용자의 구조적 양식 입력이 필요합니다(MCP 유도 프로토콜).

데이터 필드	유형	필수	설명
`requestId`	`string`	✅	이를 통해 응답하세요. `session.respondToElicitation()`
`message`	`string`	✅	필요한 정보에 대한 설명
`mode`	`"form"`
유도 모드(현재는 `"form"`만 가능)
`requestedSchema`	`{ type: "object", properties, required? }`	✅	양식 필드를 설명하는 JSON 스키마

`elicitation.completed`

임시. 유도 요청이 확인되었습니다.

데이터 필드	유형	필수	설명
`requestId`	`string`	✅	해당 항목과 일치 `elicitation.requested`

하위 에이전트 및 기술 이벤트

`subagent.started`

사용자 지정 에이전트가 하위 에이전트로 호출되었습니다.

데이터 필드	유형	필수	설명
`toolCallId`	`string`	✅	이 하위 에이전트를 생성한 부모 도구 호출
`agentName`	`string`	✅	하위 에이전트의 내부 이름
`agentDisplayName`	`string`	✅	사람이 읽을 수 있는 표시 이름
`agentDescription`	`string`	✅	하위 에이전트가 수행하는 작업 설명

`subagent.completed`

하위 에이전트가 성공적으로 완료되었습니다.

데이터 필드	유형	필수	설명
`toolCallId`	`string`	✅	해당 항목과 일치 `subagent.started`
`agentName`	`string`	✅	내부 이름
`agentDisplayName`	`string`	✅	표시 이름

`subagent.failed`

하위 에이전트에 오류가 발생했습니다.

데이터 필드	유형	필수	설명
`toolCallId`	`string`	✅	해당 항목과 일치 `subagent.started`
`agentName`	`string`	✅	내부 이름
`agentDisplayName`	`string`	✅	표시 이름
`error`	`string`	✅	오류 메시지

`subagent.selected`

현재 요청을 처리하기 위해 사용자 지정 에이전트를 선택(유추)했습니다.

데이터 필드	유형	필수	설명
`agentName`	`string`	✅	선택한 에이전트의 내부 이름
`agentDisplayName`	`string`	✅	표시 이름
`tools`	`string[] \| null`	✅	이 에이전트에서 사용할 수 있는 도구 이름; `null` 모든 도구에 대해

`subagent.deselected`

사용자 지정 에이전트가 선택 취소되어 기본 에이전트로 돌아갑니다. 응답 페이로드는 비어 있습니다({}).

`skill.invoked`

현재 대화에 대한 기술이 활성화되었습니다.

데이터 필드	유형	필수	설명
`name`	`string`	✅	기술 이름
`path`	`string`	✅	SKILL.md 정의에 대한 파일 경로
`content`	`string`	✅	기술 콘텐츠 전체가 대화에 삽입됨
`allowedTools`	`string[]`
이 기술이 활성 상태일 때 자동으로 승인된 도구
`pluginName`	`string`
스킬이 기원한 플러그인
`pluginVersion`	`string`
플러그 인 버전

기타 이벤트

`abort`

현재 턴이 중단되었습니다.

데이터 필드	유형	필수	설명
`reason`	`string`	✅	순서가 중단된 이유(예: `"user initiated"`)

`user.message`

사용자가 메시지를 보냈습니다. 세션 타임라인을 위해 기록됩니다.

데이터 필드	유형	필수	설명
`content`	`string`	✅	사용자의 메시지 텍스트
`transformedContent`	`string`
전처리 후 변환된 버전
`attachments`	`Attachment[]`
파일, 디렉터리, 선택 영역, Blob 또는 GitHub 참조 첨부 파일
`source`	`string`
메시지 원본 식별자
`agentMode`	`string`
에이전트 모드: `"interactive"`, `"plan"`, `"autopilot"`또는 `"shell"`
`interactionId`	`string`
상호 작용 식별자

`system.message`

시스템 또는 개발자 프롬프트가 대화에 삽입되었습니다.

데이터 필드	유형	필수	설명
`content`	`string`	✅	프롬프트 텍스트
`role`	`"system" \| "developer"`	✅	메시지 역할
`name`	`string`
원본 식별자
`metadata`	`{ promptVersion?, variables? }`
프롬프트 템플릿 메타데이터

`external_tool.requested`

임시. 에이전트는 외부 도구(SDK 소비자가 제공하는 도구)를 호출하려고 합니다.

데이터 필드	유형	필수	설명
`requestId`	`string`	✅	이를 통해 응답하세요. `session.respondToExternalTool()`
`sessionId`	`string`	✅	이 요청이 속한 세션
`toolCallId`	`string`	✅	이 호출에 대한 도구 호출 ID
`toolName`	`string`	✅	외부 도구의 이름
`arguments`	`object`
도구의 인수

`external_tool.completed`

임시. 외부 도구 요청이 확인되었습니다.

데이터 필드	유형	필수	설명
`requestId`	`string`	✅	해당 항목과 일치 `external_tool.requested`

`exit_plan_mode.requested`

임시. 에이전트가 계획을 만들고 계획 모드를 종료하려고 합니다.

데이터 필드	유형	필수	설명
`requestId`	`string`	✅	이를 통해 응답하세요. `session.respondToExitPlanMode()`
`summary`	`string`	✅	계획 요약
`planContent`	`string`	✅	전체 계획 파일 콘텐츠
`actions`	`string[]`	✅	사용 가능한 사용자 작업(예: 승인, 편집, 거부)
`recommendedAction`	`string`	✅	제안된 작업

`exit_plan_mode.completed`

임시. 종료 계획 모드 요청이 해결되었습니다.

데이터 필드	유형	필수	설명
`requestId`	`string`	✅	해당 항목과 일치 `exit_plan_mode.requested`

`command.queued`

임시. 슬래시 명령이 실행을 위해 큐에 대기되었습니다.

데이터 필드	유형	필수	설명
`requestId`	`string`	✅	이를 통해 응답하세요. `session.respondToQueuedCommand()`
`command`	`string`	✅	슬래시 명령 텍스트(예: `/help`, `/clear`)

`command.completed`

임시. 큐에 대기된 명령이 해결되었습니다.

데이터 필드	유형	필수	설명
`requestId`	`string`	✅	해당 항목과 일치 `command.queued`

빠른 참조: 에이전시적 단계 흐름

일반적인 에이전트 동작은 다음 순서로 이벤트를 발생시킵니다.

assistant.turn_start          → Turn begins
├── assistant.intent          → What the agent plans to do (ephemeral)
├── assistant.reasoning_delta → Streaming thinking chunks (ephemeral, repeated)
├── assistant.reasoning       → Complete thinking block
├── assistant.message_delta   → Streaming response chunks (ephemeral, repeated)
├── assistant.message         → Complete response (may include toolRequests)
├── assistant.usage           → Token usage for this API call (ephemeral)
│
├── [If tools were requested:]
│   ├── permission.requested  → Needs user approval (ephemeral)
│   ├── permission.completed  → Approval result (ephemeral)
│   ├── tool.execution_start  → Tool begins
│   ├── tool.execution_partial_result  → Streaming tool output (ephemeral, repeated)
│   ├── tool.execution_progress        → Progress updates (ephemeral, repeated)
│   ├── tool.execution_complete        → Tool finished
│   │
│   └── [Agent loops: more reasoning → message → tool calls...]
│
assistant.turn_end            → Turn complete
session.idle                  → Ready for next message (ephemeral)

모든 이벤트 유형 한눈에 보기

이벤트 유형	Ephemeral	카테고리	키 데이터 필드
`assistant.turn_start`
도우미

          `turnId`, `interactionId?` |

누가 이 기능을 사용할 수 있나요?

이 기사에서