스트리밍 세션 이벤트

Overview

세션에서 설정되면 streaming: true SDK는 지속형 이벤트(전체 메시지, 도구 결과)와 함께 임시 이벤트(델타, 진행률 업데이트)를 실시간으로 내보냅니다. 모든 이벤트는 공통 엔벨로프를 공유하며, 이벤트 data 형식에 따라 달라지는 type 페이로드를 전달합니다.

이벤트 봉투

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

이벤트 구독

// 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);
});

from copilot.session_events import SessionEventType

def handle(event):
    if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
        print(event.data.delta_content, end="", flush=True)

session.on(handle)

session.On(func(event copilot.SessionEvent) {
    if d, ok := event.Data.(*copilot.AssistantMessageDeltaData); ok {
        fmt.Print(d.DeltaContent)
    }
})

session.On<SessionEvent>(evt =>
{
    if (evt is AssistantMessageDeltaEvent delta)
    {
        Console.Write(delta.Data.DeltaContent);
    }
});

// All events
session.on(event -> System.out.println(event.getType()));

// Specific event type — data is narrowed to the matching class
session.on(AssistantMessageDeltaEvent.class, event ->
    System.out.print(event.getData().deltaContent())
);

세션이 시작되기 전에 구독

세션은 만들기 또는 다시 시작 호출이 반환되기 전에 이벤트를 내보낼 수 있습니다. 에이전트가 이미 작업 중일 수 있으며—특히 continuePendingWork로 재개하는 경우에는 더욱 그렇고—getMessages와 같은 일시적 이벤트는 세션 로그에 절대 기록되지 않으므로, session.idle는 나중에 이를 복구할 수 없습니다. 세션 핸들이 생성된 후에 설치된 구독은 해당 시작 시점을 놓치게 됩니다.

use github_copilot_sdk::{Client, SessionConfig};

async fn create_without_missing_startup_events(
    client: &Client,
) -> Result<(), github_copilot_sdk::Error> {
    let prepared = client.prepare_session(
        SessionConfig::default().with_event_buffer_capacity(2048),
    )?;

    // Installed before any wire activity: nothing is dropped for lack of a receiver.
    let mut events = prepared.subscribe();
    tokio::spawn(async move {
        while let Ok(event) = events.recv().await {
            println!("{}", event.event_type);
        }
    });

    let session = prepared.start().await?;
    let _ = session;
    Ok(())
}

prepare_* 는 동기적이며 불활성입니다. 버퍼 용량의 유효성을 검사하고 로컬 채널을 할당하며 다른 작업은 수행하지 않습니다. 세션은 등록되지 않으며 start()이 처음 폴링되기 전까지는 CLI에 아무것도 도달하지 않습니다. 시작되지 않은 준비된 세션을 폐기해도 어떤 상태도 남기지 않고 해당 구독을 종료합니다. start() future를 폐기하면 진행 중인 시작 작업이 취소되고 세션 등록이 해제되므로, 동일한 세션 ID로 다시 시도해도 성공합니다. 정리 작업은 중단된 시작 작업이 소유했던 바로 그 등록 항목에만 한정되므로, 동일한 세션 ID를 이미 이어받은 재시도를 제거할 수 없습니다.

초기 버퍼링은 미리 대비할 가치가 있습니다.

• 이벤트 버퍼는 유한하며, event_buffer_capacity가 이를 재정의하지 않는 한 512개 이벤트로 제한됩니다. 0 용량이 고정되지 않고 잘못된 구성 오류로 거부됩니다.
• 느린 구독자에게는 건너뛴 이벤트 수를 보고하는 Lagged 오류가 표시됩니다. 세션의 이벤트 루프에는 역압을 적용하지 않습니다.
• 시작 시 대규모 버스트를 데이터 손실 없이 확인해야 하는 소비자는 해당 버스트를 감당할 수 있는 용량을 구성하거나 start()와 동시에 구독의 데이터를 소진해야 합니다.

부모 에이전트 응답만 렌더링

하위 에이전트 이벤트는 상위 세션 스트림을 공유하며, 엔벌로프 수준의 agentId를 포함합니다. 루트/메인 에이전트 이벤트와 세션 수준 이벤트에는 agentId가 포함되지 않으므로, 메인 채팅 렌더러는 agentId가 설정된 assistant 이벤트를 무시하고 대신 해당 이벤트를 트레이스 또는 진행률 UI로 라우팅할 수 있습니다.

import type { CopilotSession } from "@github/copilot-sdk";

export function subscribeParentResponse(session: CopilotSession): void {
    session.on("assistant.message_delta", (event) => {
        if (!event.agentId) {
            process.stdout.write(event.data.deltaContent);
        }
    });
}

from copilot import CopilotSession, SessionEvent, SessionEventType
from copilot.session_events import AssistantMessageDeltaData

def subscribe_parent_response(session: CopilotSession) -> None:
    def handle(event: SessionEvent) -> None:
        if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA and event.agent_id is None:
            data = event.data
            if isinstance(data, AssistantMessageDeltaData):
                print(data.delta_content, end="", flush=True)

    session.on(handle)

package example

import (
    "fmt"

    copilot "github.com/github/copilot-sdk/go"
)

func subscribeParentResponse(session *copilot.Session) {
    session.On(func(event copilot.SessionEvent) {
        if event.AgentID != nil {
            return
        }

        if d, ok := event.Data.(*copilot.AssistantMessageDeltaData); ok {
            fmt.Print(d.DeltaContent)
        }
    })
}

using System;
using GitHub.Copilot;

static class ParentAgentResponseExample
{
    public static void SubscribeParentResponse(CopilotSession session)
    {
        session.On<AssistantMessageDeltaEvent>(evt =>
        {
            if (evt.AgentId is null)
            {
                Console.Write(evt.Data.DeltaContent);
            }
        });
    }
}

import com.github.copilot.CopilotSession;
import com.github.copilot.generated.AssistantMessageDeltaEvent;

final class ParentAgentResponseExample {
    static void subscribeParentResponse(CopilotSession session) {
        session.on(AssistantMessageDeltaEvent.class, event -> {
            if (event.getAgentId() == null) {
                System.out.print(event.getData().deltaContent());
            }
        });
    }
}

use github_copilot_sdk::session::Session;

async fn subscribe_parent_response(session: &Session) {
    let mut events = session.subscribe();

    while let Ok(event) = events.recv().await {
        if event.event_type == "assistant.message_delta" && event.agent_id.is_none() {
            if let Some(delta) = event.data.get("deltaContent").and_then(|v| v.as_str()) {
                print!("{delta}");
            }
        }
    }
}

도우미 이벤트

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

assistant.turn_start

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

assistant.intent

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

assistant.reasoning

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

assistant.reasoning_delta

임시. 실시간으로 스트리밍되는 모델의 확장된 사고의 증분 조각.

assistant.message

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

** ToolRequest 필드:**

assistant.message_delta

임시. 실시간으로 스트리밍되는 도우미 텍스트 응답의 증분 조각.

assistant.turn_end

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

assistant.usage

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

assistant.streaming_delta

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

도구 실행 이벤트

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

tool.execution_start

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

tool.execution_partial_result

Deprecated. tool.shell_output를 라이브 터미널 출력에 사용합니다. 이 임시 이벤트는 마이그레이션 중에 교체와 함께 계속 내보내집니다. 동일한 출력을 두 번 표시하지 않도록 하나의 표현만 구독하세요.

tool.shell_output

임시. 연결된 터미널 명령 또는 사용자가 요청한 터미널 명령의 추가 전용 출력입니다. 각 이벤트에는 모델의 최종 도구 결과의 서식을 지정하는 데 사용되는 구분 기호 또는 표식이 없는 새로 관찰된 비밀이 필터링된 텍스트가 포함됩니다.

text toolCallId 및 stream별로 개별적으로 누적하거나, 결합된 표시를 위해 청크를 순서대로 조인합니다. 시퀀스 번호는 중복된 청크 및 누락된 청크를 식별합니다. 독립 운영 체제 쓰기 간에 정확한 순서를 설정하지 않습니다. 늦은 구독자는 0보다 큰 첫 번째 시퀀스를 받을 수 있습니다.

이러한 이벤트는 라이브 전용입니다. 다시 시작 후 저장되거나 재생되지 않습니다. 최종 tool.execution_complete 결과, 모델 대상 서식 및 분리된 명령 캡처는 변경되지 않습니다. 텍스트는 터미널 컨트롤 시퀀스를 포함할 수 있습니다. 렌더러는 각 렌더러의 일반적인 터미널 텍스트 처리를 적용해야 합니다.

연결된 터미널 명령은 비동기적으로 실행되거나 tool.execution_complete을(를) 넘어 계속되는 경우 initial_wait 이후에도 계속 실행될 수 있습니다. 계속하는 동안 받은 출력은 0부터 다시 시작하는 대신 원래의 toolCallId 및 동일한 sequence를 사용합니다. 활성 호출만 표시하는 소비자는 완료된 호출 상태를 다시 만드는 대신 완료 후 받은 청크를 무시해야 합니다.

비밀 필터링은 디코딩된 각 청크에 대해 작동합니다. 런타임은 줄을 인위적으로 나누지 않지만 운영 체제 읽기는 줄 또는 비밀을 청크 간에 나눌 수 있습니다. 청크 간 비밀 재구성은 제공되지 않습니다.

tool.execution_progress

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

tool.execution_complete

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

** Result 필드:**

tool.user_requested

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

세션 수명 주기 이벤트

session.idle

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

session.error

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

session.compaction_start

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

session.compaction_complete

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

session.title_changed

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

session.context_changed

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

session.usage_info

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

session.session_limits_changed

현재 회계 기간의 세션 제한이 변경되었습니다. 값은 null``sessionLimits 제한이 활성화되지 않음을 의미합니다.

session.usage_checkpoint

세션이 다시 시작될 때 회계를 다시 구성하는 데 사용되는 지속성 집계 사용 검사점입니다.

session.task_complete

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

session.shutdown

세션이 종료되었습니다.

권한 및 사용자 입력 이벤트

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

permission.requested

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

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

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

쓰기 요청은 promptRequest와 permissionRequest 모두에 fileEdits를 포함할 수도 있습니다. 각 항목에는 선택적 path 및 after 스냅샷이 포함되며, 각 스냅샷에는 세션 파일 시스템 네임스페이스의 절대 content 및 완전한 UTF-8 before가 있습니다. 누락된 before는 생성을 의미하고, 누락된 after는 삭제를 의미합니다. 빈 content 문자열은 사용할 수 없는 미리 보기가 아닌 빈 파일을 나타냅니다. 이동의 두 면에는 서로 다른 경로가 있을 수 있습니다. 이동 작업이 기존 대상을 덮어쓰는 경우 개별 항목은 원본 삭제 및 대상 대체를 설명합니다.

이러한 스냅샷은 라이브 파일 시스템을 나중에 읽은 결과가 아니라 계획된 작업을 설명합니다. 런타임은 샌드박스로 보호된 파일, UTF-8이 아닌 콘텐츠 또는 명명된 파이프와 같이 읽을 수 없거나 일반 파일이 아닌 이동 대상을 읽기 전에 수행한 요청을 포함하여 전체 텍스트 미리 보기를 제공할 수 없는 경우 fileEdits를 생략합니다. 빈 레거시 newFileContents 값에서 삭제를 유추하지 마세요. 미리 보기를 사용하지 않는 소비자는 기존 필드 및 승인 선택을 계속 사용할 수 있습니다.

permission.completed

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

user_input.requested

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

user_input.completed

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

elicitation.requested

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

elicitation.completed

임시. 유도 요청이 해결되었습니다.

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

subagent.started

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

subagent.completed

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

subagent.failed

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

subagent.selected

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

subagent.deselected

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

skill.invoked

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

기타 이벤트

abort

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

user.message

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

system.message

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

external_tool.requested

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

external_tool.completed

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

exit_plan_mode.requested

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

exit_plan_mode.completed

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

command.queued

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

command.completed

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

session_limits_exhausted.requested

임시. 현재 세션 예산이 소진되었으며 계속하기 전에 런타임에 사용자 결정이 필요합니다.

session_limits_exhausted.completed

임시. 대기 중인 한도 초과 요청이 해결되었습니다.

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

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

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
│   ├── permission.completed  → Approval result
│   ├── tool.execution_start  → Tool begins
│   ├── tool.shell_output              → Stream-tagged terminal 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)

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

이 표에는 키 data 페이로드 필드가 나열됩니다. 일반적인 봉투 필드는 위에 설명되어 있습니다.