/copilot-sdk

Event System

The Copilot SDK emits a rich stream of session events. Event names and payloads have expanded since early preview builds, so older examples are often incomplete.

Event envelope

Every event includes the same top-level structure:

Subscription patterns

TypeScript

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

session.on("assistant.message_delta", (event) => {
  process.stdout.write(event.data.deltaContent ?? "");
});

Python

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)

Go

session.On(func(event copilot.SessionEvent) {
    if event.Type == "assistant.message_delta" && event.Data.DeltaContent != nil {
        fmt.Print(*event.Data.DeltaContent)
    }
})

.NET

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

Java

session.on(AssistantMessageDeltaEvent.class, event -> {
    System.out.print(event.getData().deltaContent());
});

Typical turn flow

Exact order varies, but a normal streamed turn often looks like this:

1. user.message
2. assistant.turn_start
3. assistant.intent
4. assistant.reasoning_delta / assistant.reasoning
5. assistant.message_delta
6. tool.execution_start
7. tool.execution_partial_result / tool.execution_progress
8. tool.execution_complete
9. assistant.message
10. assistant.turn_end
11. session.idle
12. session.usage_info

For a completed task you may also see session.task_complete.

High-signal event types

Assistant events

Tool events

Session lifecycle events

Permission, user input, and elicitation

Sub-agent and skill events

Other useful events

Streaming behavior

• streaming: true adds delta events such as assistant.message_delta.
• Final events like assistant.message still fire even when streaming is enabled.
• Tool partial/progress events are often ephemeral and should be treated as live UI updates, not durable history.

Data access conventions by language

Practical guidance

1. Use assistant.message_delta for live rendering.
2. Use assistant.message for the final canonical text.
3. Use session.idle to know when a turn is done.
4. Use assistant.usage for per-call accounting and session.usage_info for session totals.
5. If you need every detail for audits or replay, store the full event stream from getMessages().