Streaming Session Events

Every action the Copilot agent takes — thinking, writing code, running tools — is emitted as a session event you can subscribe to. This guide is a field-level reference for each event type so you know exactly what data to expect without reading the SDK source.

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.

sequenceDiagram
    participant App as Your App
    participant SDK as SDK Session
    participant Agent as Copilot Agent

    App->>SDK: send({ prompt })
    SDK->>Agent: JSON-RPC

    Agent-->>SDK: assistant.turn_start
    SDK-->>App: event

    loop Streaming response
        Agent-->>SDK: assistant.message_delta (ephemeral)
        SDK-->>App: event
    end

    Agent-->>SDK: assistant.message
    SDK-->>App: event

    loop Tool execution
        Agent-->>SDK: tool.execution_start
        SDK-->>App: event
        Agent-->>SDK: tool.execution_complete
        SDK-->>App: event
    end

    Agent-->>SDK: assistant.turn_end
    SDK-->>App: event

    Agent-->>SDK: session.idle (ephemeral)
    SDK-->>App: event

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 import CopilotClient
from copilot.generated.session_events import SessionEventType

client = CopilotClient()

session = None  # assume session is created elsewhere

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

# session.on(handle)

from copilot.generated.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)

package main

import (
	"context"
	"fmt"
	copilot "github.com/github/copilot-sdk/go"
)

func main() {
	ctx := context.Background()
	client := copilot.NewClient(nil)

	session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
		Model:     "gpt-4.1",
		Streaming: true,
		OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
			return copilot.PermissionRequestResult{Kind: copilot.PermissionRequestResultKindApproved}, nil
		},
	})

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

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

using GitHub.Copilot.SDK;

public static class StreamingEventsExample
{
    public static async Task Example(CopilotSession session)
    {
        session.On(evt =>
        {
            if (evt is AssistantMessageDeltaEvent delta)
            {
                Console.Write(delta.Data.DeltaContent);
            }
        });
    }
}

session.On(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())
);

Tip (Python / Go): These SDKs use a single Data class/struct with all possible fields as optional/nullable. Only the fields listed in the tables below are populated for each event type — the rest will be None / nil.

Tip (.NET): The .NET SDK uses separate, strongly-typed data classes per event (e.g., AssistantMessageDeltaData), so only the relevant fields exist on each type.

Tip (TypeScript): The TypeScript SDK uses a discriminated union — when you match on event.type, the data payload is automatically narrowed to the correct shape.

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

The agent has completed its assigned task.

session.shutdown

The session has ended.

Permission & User Input Events

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

permission.requested

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

Ephemeral. 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 & 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

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

external_tool.completed

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

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

All Event Types at a Glance