Ereignisse einer Streaming-Sitzung

Übersicht

Wenn streaming: true für eine Sitzung festgelegt wird, sendet das SDK kurzlebige Ereignisse in Echtzeit (Deltas, Statusaktualisierungen) neben dauerhaften Ereignissen (vollständige Nachrichten, Toolergebnisse). Alle Ereignisse teilen einen gemeinsamen Umschlag und tragen eine data Nutzlast, deren Shape vom Ereignis typeabhängt.

Ereignishülle

Jedes Sitzungsereignis umfasst unabhängig vom Typ die folgenden Felder:

Abonnieren von Ereignissen

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

Abonnieren vor Beginn einer Sitzung

Eine Sitzung kann Ereignisse ausgeben, bevor ihr create- oder resume-Aufruf zurückkehrt. Der Agent arbeitet möglicherweise bereits – insbesondere bei Fortsetzung mit continuePendingWork – und kurzlebige Ereignisse wie session.idle werden niemals in das Sitzungsprotokoll geschrieben, sodass getMessages sie anschließend nicht wiederherstellen kann. Ein Abonnement, das erst eingerichtet wird, nachdem das Sitzungs-Handle bereits existiert, verpasst dieses Startfenster.

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_* ist synchron und inert: Er überprüft die Pufferkapazität, weist einen lokalen Kanal zu und führt nichts anderes aus. Es ist keine Sitzung registriert, und nichts erreicht die CLI, bis start() erstmals abgefragt wird. Das Ablegen einer vorbereiteten Sitzung, die nie gestartet wurde, hinterlässt keinen Zustand und schließt seine Abonnements; Wenn Sie die start() Zukunft löschen, wird der In-Flight-Start abgebrochen und die Registrierung der Sitzung aufgehoben, sodass ein Wiederholungsversuche mit derselben Sitzungs-ID erfolgreich ist. Die Bereinigung ist auf genau die Registrierung des abgebrochenen Startvorgangs beschränkt, sodass sie keinen Wiederholungsversuch verdrängen kann, der dieselbe Sitzungs-ID bereits übernommen hat.

Es lohnt sich, die Pufferung beim Start einzuplanen:

• Der Ereignispuffer ist begrenzt – auf 512 Ereignisse, sofern dies nicht durch event_buffer_capacity überschrieben wird. Eine Kapazität von 0 wird mit einem „invalid-config“-Fehler abgelehnt, anstatt begrenzt zu werden.
• Langsame Abonnenten beobachten einen Lagged Fehler, der meldet, wie viele Ereignisse übersprungen wurden. Sie üben niemals Backpressure auf die Ereignisschleife der Sitzung aus.
• Verbraucher, die einen lückenlosen Überblick über einen großen Start-Burst benötigen, müssen entweder eine Kapazität konfigurieren, die dies abdeckt, oder das Abonnement gleichzeitig mit start() aufbrauchen.

Nur die Antwort des übergeordneten Agenten anzeigen

Subagent-Ereignisse teilen den übergeordneten Sitzungsdatenstrom und umfassen agentId auf Envelope-Ebene. Ereignisse des Root-/Haupt-Agenten und Ereignisse auf Sitzungsebene lassen agentId aus, sodass Renderer des Hauptchats Assistentenereignisse, bei denen agentId gesetzt ist, ignorieren und stattdessen an Traces oder die Fortschritts-UI weiterleiten können.

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

Ereignisse des Assistenten

Diese Ereignisse verfolgen den Lebenszyklus der Antwort des Agents - vom Start der Abzweigung über die Streaming Chunks bis zur endgültigen Nachricht.

assistant.turn_start

Wird ausgelöst, wenn der Agent mit der Verarbeitung eines Ablaufschritts beginnt.

assistant.intent

Flüchtig Kurze Beschreibung dessen, was der Agent gerade tut, aktualisiert während der Vorgang läuft.

assistant.reasoning

Schließen Sie die erweiterte Denkblockade des Modells ab. Wird nach Abschluss der Begründung ausgegeben.

assistant.reasoning_delta

Flüchtig Inkrementeller Chunk des erweiterten Denkens des Modells, das in Echtzeit gestreamt wird.

assistant.message

Die vollständige Antwort des Assistenten für diesen LLM-Aufruf. Kann Toolaufrufanforderungen enthalten.

** ToolRequest Felder:**

assistant.message_delta

Flüchtig Inkrementeller Chunk der Text-Antwort des Assistenten, der in Echtzeit gestreamt wird.

assistant.turn_end

Wird ausgegeben, wenn der Agent eine Runde abschließt (alle Tool-Ausführungen abgeschlossen, endgültige Antwort geliefert).

assistant.usage

Flüchtig Tokenverwendungs- und Kosteninformationen für einen einzelnen API-Aufruf.

assistant.streaming_delta

Flüchtig Niedrigrangige Fortschrittsanzeige – Gesamtanzahl der Bytes, die von der Streaming-API-Antwort empfangen wurden.

Toolausführungsereignisse

Diese Ereignisse verfolgen den vollständigen Lebenszyklus jedes Toolaufrufs, von der Anforderung durch das Modell über die Ausführung bis zur Fertigstellung.

tool.execution_start

Wird ausgegeben, wenn ein Tool mit der Ausführung beginnt.

tool.execution_partial_result

Deprecated. Verwenden Sie tool.shell_output für die Live-Terminalausgabe. Dieses kurzlebige Ereignis wird während der Migration weiterhin zusammen mit dem Ersatz ausgegeben; abonnieren Sie nur eine Darstellung, um zu vermeiden, dass die gleiche Ausgabe zweimal angezeigt wird.

tool.shell_output

Flüchtig Ausgabe nur im Anhängemodus eines Befehls in einem verbundenen Terminal oder eines vom Benutzer angeforderten Terminalbefehls. Jedes Ereignis enthält neu beobachteten, von Geheimnissen bereinigten Text, ohne die Trennzeichen oder Markierungen, die zum Formatieren der endgültigen Toolergebnisse für das Modell verwendet werden.

Sammeln Sie separat nach stream und text, oder verbinden Sie die Blöcke in Sequenzreihenfolge für eine kombinierte Anzeige. Eine Sequenznummer identifiziert Duplikate und fehlende Blöcke; es wird keine exakte Reihenfolge zwischen unabhängigen Betriebssystemschreibvorgängen festgelegt. Ein verspäteter Abonnent kann eine erste Sequenz größer als 0 empfangen.

Diese Ereignisse sind nur live: Sie werden nach dem Fortsetzen nicht beibehalten oder erneut gesendet. Endergebnisse tool.execution_complete , modellorientierte Formatierung und getrennte Befehlserfassung sind unverändert. Text kann Terminalsteuerungssequenzen enthalten; Renderer müssen ihre normale Terminaltextbehandlung anwenden.

Ein angefügter Terminalbefehl kann nach tool.execution_complete weiterhin ausgeführt werden, wenn er asynchron ausgeführt wird oder über initial_wait hinaus fortgesetzt wird. Die Ausgabe, die empfangen wird, während sie fortgesetzt wird, verwendet das ursprüngliche toolCallId und setzt dasselbe sequence fort, anstatt bei null neu zu starten. Verbraucher, die nur aktive Aufrufe anzeigen, müssen nach Abschluss empfangene Chunks ignorieren, anstatt den Status eines abgeschlossenen Aufrufs neu zu erstellen.

Die Filterung von Geheimnissen wird für jeden decodierten Block ausgeführt. Die Laufzeit teilt Zeilen nicht künstlich auf, aber Lesevorgänge des Betriebssystems können eine Zeile oder ein Geheimnis über Blöcke hinweg aufteilen; eine Rekonstruktion von Geheimnissen über Blockgrenzen hinweg wird nicht bereitgestellt.

tool.execution_progress

Flüchtig Menschenlesbarer Fortschrittsstatus von einem laufenden Tool (z. B. Fortschrittsbenachrichtigungen des MCP-Servers).

tool.execution_complete

Wird ausgegeben, wenn die Ausführung eines Tools abgeschlossen ist – erfolgreich oder mit einem Fehler.

** Result Felder:**

tool.user_requested

Wird ausgegeben, wenn der Benutzende explizit einen Tool-Aufruf anfordert (und nicht das Modell selbst einen Aufruf vornimmt).

Sitzungslebenszyklusereignisse

session.idle

Flüchtig Der Agent hat die gesamte Verarbeitung abgeschlossen und ist bereit für die nächste Nachricht. Dies ist das Signal, dass eine Drehung vollständig abgeschlossen ist.

session.error

Ein Fehler ist während der Sitzungsverarbeitung aufgetreten.

session.compaction_start

Die Verdichtung des Kontextfensters hat begonnen. Die Datennutzlast ist leer ({}).

session.compaction_complete

Die Verdichtung des Kontextfensters wurde abgeschlossen.

session.title_changed

Flüchtig Der automatisch generierte Titel der Sitzung wurde aktualisiert.

session.context_changed

Der Arbeitsverzeichnis- oder Repositorykontext der Sitzung wurde geändert.

session.usage_info

Flüchtig Momentaufnahme der Kontextfensterverwendung.

session.session_limits_changed

Die Sitzungslimits wurden für den aktuellen Abrechnungszeitraum geändert. Ein null``sessionLimits Wert bedeutet, dass keine Grenzwerte aktiv sind.

session.usage_checkpoint

Dauerhafter Aggregatverwendungsprüfpunkt, der zum Rekonstruieren der Buchhaltung verwendet wird, wenn eine Sitzung fortgesetzt wird.

session.task_complete

Der Agent hat seine zugewiesene Aufgabe abgeschlossen.

session.shutdown

Die Sitzung wurde beendet.

Berechtigungs- und Benutzereingabeereignisse

Diese Ereignisse werden ausgegeben, wenn der Agent eine Genehmigung oder Eingabe des Benutzers benötigt, bevor er fortfahren kann.

permission.requested

Der Agent benötigt die Berechtigung zum Ausführen einer Aktion (Ausführen eines Befehls, Schreiben einer Datei usw.).

Der permissionRequest ist ein discriminated union auf kind:

Alle kind Varianten enthalten auch eine optionale toolCallId Verknüpfung mit dem Toolaufruf, der die Anforderung ausgelöst hat.

Schreibanforderungen können auch fileEdits sowohl in permissionRequest als auch in promptRequest enthalten. Jeder Eintrag enthält einen optionalen before und einen path Snapshot, jeweils mit einem absoluten content im Namespace des Sitzungsdateisystems und einem vollständigen UTF-8-after. Ein fehlendes before bedeutet Erstellung; ein fehlendes after bedeutet Löschung. Eine leere content Zeichenfolge stellt eine leere Datei dar, keine nicht verfügbare Vorschau. Eine Bewegung kann unterschiedliche Pfade auf ihren beiden Seiten haben. Wenn eine Verschiebung ein vorhandenes Ziel überschreibt, beschreiben separate Einträge den Quelllöschvorgang und den Zielersetzungsvorgang.

Diese Momentaufnahmen beschreiben den geplanten Vorgang, nicht ein späteres Auslesen des Live-Dateisystems. Die Laufzeit lässt fileEdits aus, wenn keine vollständige Textvorschau bereitgestellt werden kann, einschließlich Anfragen, die vor dem Lesen einer sandbox-geschützten Datei gestellt werden, Inhalte, die nicht in UTF-8 codiert sind, oder eines nicht lesbaren oder nicht regulären Verschiebungsziels, z. B. einer benannten Pipe. Leiten Sie keinen Löschvorgang aus einem leeren Legacy-Wert newFileContents ab. Die vorhandenen Felder und Genehmigungsoptionen bleiben für Verbraucher verfügbar, die keine Vorschau verwenden.

permission.completed

Eine Berechtigungsanfrage wurde gelöst.

user_input.requested

Flüchtig Der Agent stellt dem Benutzer eine Frage.

user_input.completed

Flüchtig Eine Benutzereingabeanforderung wurde aufgelöst.

elicitation.requested

Flüchtig Der Agent benötigt strukturierte Formulareingaben vom Benutzer (MCP-Elicitationsprotokoll).

elicitation.completed

Flüchtig Eine Anfrage wurde behoben.

Sub-Agenten und Skill-Ereignisse

subagent.started

Ein angepasster Agent wurde als Sub-Agent aufgerufen.

subagent.completed

Ein Sub-Agent wurde erfolgreich abgeschlossen.

subagent.failed

Bei einem Unter-Agent ist ein Fehler aufgetreten.

subagent.selected

Ein benutzerdefinierter Agent wurde ausgewählt (abgeleitet), um die aktuelle Anforderung zu verarbeiten.

subagent.deselected

Ein benutzerdefinierter Agent wurde deaktiviert und kehrt zum Standard-Agent zurück. Die Datennutzlast ist leer ({}).

skill.invoked

Für die aktuelle Unterhaltung wurde eine Fähigkeit aktiviert.

Andere Ereignisse

abort

Die aktuelle Drehung wurde abgebrochen.

user.message

Der Benutzer hat eine Nachricht gesendet. Aufgezeichnet für den Sitzungsverlauf.

system.message

Eine System- oder Entwickleraufforderung wurde in die Unterhaltung eingefügt.

external_tool.requested

Der Agent möchte ein externes Tool aufrufen (eines, das vom SDK-Consumer bereitgestellt wird).

external_tool.completed

Eine externe Toolanforderung wurde aufgelöst.

exit_plan_mode.requested

Flüchtig Der Agent hat einen Plan erstellt und möchte den Planmodus beenden.

exit_plan_mode.completed

Flüchtig Eine Anforderung für den Exit-Plan-Modus wurde aufgelöst.

command.queued

Flüchtig Ein Slash-Befehl wurde zur Ausführung in die Warteschlange gestellt.

command.completed

Flüchtig Ein Befehl in der Warteschlange wurde aufgelöst.

session_limits_exhausted.requested

Flüchtig Das aktuelle Sitzungsbudget wurde ausgeschöpft und die Laufzeit erfordert eine Entscheidung des Benutzers, bevor fortgefahren werden kann.

session_limits_exhausted.completed

Flüchtig Eine ausstehende Anfrage wegen eines ausgeschöpften Limits wurde bearbeitet.

Kurzübersicht: Agentischer Handlungsfluss

Ein typischer Agent gibt Ereignisse in dieser Reihenfolge aus:

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)

Alle Ereignistypen auf einen Blick

In dieser Tabelle sind die wichtigsten data Nutzlastfelder aufgeführt. Allgemeine Umschlagfelder sind oben dokumentiert.