Streaming session events

Overview

When streaming: true is set on a session, the SDK emits ephemeral events in real time (deltas, progress updates) alongside persisted events (complete messages, tool results). All events share a common envelope and carry a data payload whose shape depends on the event type.

Event envelope

Every session event, regardless of type, includes these fields:

Subscribing to events

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

Subscribing before a session starts

A session can emit events before its create or resume call returns. The agent may already be working—especially on resume with continuePendingWork—and ephemeral events such as session.idle are never written to the session log, so getMessages cannot recover them afterwards. A subscription installed after the session handle exists misses that startup window.

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_* is synchronous and inert: it validates the buffer capacity, allocates a local channel, and does nothing else. No session is registered and nothing reaches the CLI until start() is first polled. Dropping a prepared session that was never started leaves no state behind and closes its subscriptions; dropping the start() future cancels the in-flight startup and unregisters the session, so a retry with the same session ID succeeds. Cleanup is scoped to the exact registration the abandoned startup owned, so it cannot evict a retry that has already taken over the same session ID.

Startup buffering is worth planning for:

• The event buffer is finite—512 events unless event_buffer_capacity overrides it. A capacity of 0 is rejected with an invalid-config error rather than clamped.
• Slow subscribers observe a Lagged error reporting how many events were skipped. They never apply backpressure to the session's event loop.
• Consumers that need a lossless view of a large startup burst must either configure a capacity that covers it or drain the subscription concurrently with start().

Render only the parent agent response

Sub-agent events share the parent session stream and include envelope-level agentId. Root/main agent events and session-level events omit agentId, so main-chat renderers can ignore assistant events where agentId is set and route those events to traces or progress UI instead.

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 events

These events track the agent's response lifecycle—from turn start through streaming chunks to the final message.

assistant.turn_start

Emitted when the agent begins processing a turn.

assistant.intent

Ephemeral. Short description of what the agent is currently doing, updated as it works.

assistant.reasoning

Complete extended thinking block from the model. Emitted after reasoning is finished.

assistant.reasoning_delta

Ephemeral. Incremental chunk of the model's extended thinking, streamed in real time.

assistant.message

The assistant's complete response for this LLM call. May include tool invocation requests.

ToolRequest fields:

assistant.message_delta

Ephemeral. Incremental chunk of the assistant's text response, streamed in real time.

assistant.turn_end

Emitted when the agent finishes a turn (all tool executions complete, final response delivered).

assistant.usage

Ephemeral. Token usage and cost information for an individual API call.

assistant.streaming_delta

Ephemeral. Low-level network progress indicator—total bytes received from the streaming API response.

Tool execution events

These events track the full lifecycle of each tool invocation—from the model requesting a tool call through execution to completion.

tool.execution_start

Emitted when a tool begins executing.

tool.execution_partial_result

Ephemeral. Incremental output from a running tool (e.g., streaming bash output).

tool.execution_progress

Ephemeral. Human-readable progress status from a running tool (e.g., MCP server progress notifications).

tool.execution_complete

Emitted when a tool finishes executing—successfully or with an error.

Result fields:

tool.user_requested

Emitted when the user explicitly requests a tool invocation (rather than the model choosing to call one).

Session lifecycle events

session.idle

Ephemeral. The agent has finished all processing and is ready for the next message. This is the signal that a turn is fully complete.

session.error

An error occurred during session processing.

session.compaction_start

Context window compaction has begun. Data payload is empty ({}).

session.compaction_complete

Context window compaction finished.

session.title_changed

Ephemeral. The session's auto-generated title was updated.

session.context_changed

The session's working directory or repository context changed.

session.usage_info

Ephemeral. Context window utilization snapshot.

session.session_limits_changed

Session limits changed for the current accounting window. A null sessionLimits value means no limits are active.

session.usage_checkpoint

Durable aggregate usage checkpoint used to reconstruct accounting when a session is resumed.

session.task_complete

The agent has completed its assigned task.

session.shutdown

The session has ended.

Permission and user input events

These events are emitted when the agent needs approval or input from the user before continuing.

permission.requested

The agent needs permission to perform an action (run a command, write a file, etc.).

The permissionRequest is a discriminated union on kind:

All kind variants also include an optional toolCallId linking back to the tool call that triggered the request.

permission.completed

A permission request was resolved.

user_input.requested

Ephemeral. The agent is asking the user a question.

user_input.completed

Ephemeral. A user input request was resolved.

elicitation.requested

Ephemeral. The agent needs structured form input from the user (MCP elicitation protocol).

elicitation.completed

Ephemeral. An elicitation request was resolved.

Sub-agent and skill events

subagent.started

A custom agent was invoked as a sub-agent.

subagent.completed

A sub-agent finished successfully.

subagent.failed

A sub-agent encountered an error.

subagent.selected

A custom agent was selected (inferred) to handle the current request.

subagent.deselected

A custom agent was deselected, returning to the default agent. Data payload is empty ({}).

skill.invoked

A skill was activated for the current conversation.

Other events

abort

The current turn was aborted.

user.message

The user sent a message. Recorded for the session timeline.

system.message

A system or developer prompt was injected into the conversation.

external_tool.requested

The agent wants to invoke an external tool (one provided by the SDK consumer).

external_tool.completed

An external tool request was resolved.

exit_plan_mode.requested

Ephemeral. The agent has created a plan and wants to exit plan mode.

exit_plan_mode.completed

Ephemeral. An exit plan mode request was resolved.

command.queued

Ephemeral. A slash command was queued for execution.

command.completed

Ephemeral. A queued command was resolved.

session_limits_exhausted.requested

Ephemeral. The current session budget was exhausted and the runtime needs a user decision before continuing.

session_limits_exhausted.completed

Ephemeral. A pending exhausted-limit request was resolved.

Quick reference: agentic turn flow

A typical agentic turn emits events in this order:

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.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)

All event types at a glance

This table lists key data payload fields. Common envelope fields are documented above.