Événements de session de streaming

Overview

Lorsqu’il streaming: true est défini sur une session, le SDK émet des événements éphémères en temps réel (deltas, mises à jour de progression) ainsi que des événements persistants (messages complets, résultats de l’outil). Tous les événements partagent une enveloppe commune et portent une data charge utile dont la forme dépend de l’événement type.

Enveloppe d’événement

Chaque événement de session, quel que soit le type, inclut les champs suivants :

Abonnement aux événements

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

Abonnement avant le démarrage d’une session

Une session peut émettre des événements avant son retour d’appel de création ou de reprise. L’agent est peut-être déjà en cours d’exécution — en particulier lors d’une reprise avec continuePendingWork — et des événements éphémères tels que session.idle ne sont jamais consignés dans le journal de session, de sorte que getMessages ne peut pas les récupérer par la suite. Un abonnement installé une fois l’identifiant de session créé ne bénéficie pas de cette fenêtre de démarrage.

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_* est synchrone et inerte : il valide la capacité de mémoire tampon, alloue un canal local et ne fait rien d’autre. Aucune session n’est enregistrée et rien n’arrive à l’interface de ligne de commande (CLI) tant que start() n’a pas fait l’objet d’une première interrogation. La suppression d’une session préparée qui n’a jamais été démarrée ne laisse aucun état résiduel et ferme ses abonnements ; la suppression du future start() annule le démarrage en cours et désinscrit la session, de sorte qu’une nouvelle tentative avec le même ID de session réussit. Le nettoyage est limité à l’enregistrement exact détenu par l’instance de démarrage abandonnée ; il ne peut donc pas évincer une nouvelle tentative qui a déjà repris le même ID de session.

La mise en mémoire tampon de démarrage vaut la peine de planifier :

• La mémoire tampon d’événements est limitée à 512 événements, à moins que event_buffer_capacity ne remplace cette valeur. Une capacité de 0 est rejetée avec une erreur « invalid-config » au lieu d’être bornée.
• Les abonnés lents voient apparaître une erreur Lagged indiquant combien d’événements ont été ignorés. Ils n’appliquent jamais de contre-pression à la boucle d’événements de la session.
• Les consommateurs qui ont besoin d’une vue sans perte d’une grande rafale de démarrage doivent configurer une capacité qui la couvre ou vider l’abonnement simultanément avec start().

Afficher uniquement la réponse de l’agent parent

Les événements des sous-agents partagent le flux de la session parente et incluent la balise agentId au niveau de l’enveloppe. Les événements de l’agent racine/principal et les événements au niveau de la session omettent agentId, de sorte que les renderers main-chat peuvent ignorer les événements d’assistant où agentId est défini et acheminer ces événements vers des traces ou une interface utilisateur de progression à la place.

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

Événements de l'Assistant

Ces événements effectuent le suivi du cycle de vie de réponse de l’agent, du début en passant par les flux en continu jusqu’au message final.

assistant.turn_start

Émis lorsque l'agent commence à traiter une itération.

assistant.intent

Éphémère. Brève description de ce que fait actuellement l’agent, et mise à jour à mesure qu’il travaille.

assistant.reasoning

Bloc de pensée étendu complet du modèle. Émis après la fin du raisonnement.

assistant.reasoning_delta

Éphémère. Partie incrémentielle de la pensée étendue du modèle, diffusée en temps réel.

assistant.message

Réponse complète de l’Assistant pour cet appel LLM. Peut inclure des demandes d’appel d’outil.

** ToolRequest Champs:**

assistant.message_delta

Éphémère. Segment incrémentiel de la réponse de texte de l’assistant, diffusé en temps réel.

assistant.turn_end

Émis lorsque l’agent termine un tour (toutes les exécutions d’outils sont terminées, réponse finale remise).

assistant.usage

Éphémère. Informations d’utilisation et de coût des jetons pour un appel d’API individuel.

assistant.streaming_delta

Éphémère. Indicateur de progression réseau de bas niveau : nombre total d’octets reçus de la réponse de l’API de diffusion en continu.

Événements d’exécution d’outils

Ces événements suivent le cycle de vie complet de chaque appel d'outil, depuis la demande d'appel d'outil par le modèle, à travers l'exécution, jusqu'à son achèvement.

tool.execution_start

Émis lorsqu’un outil commence à s’exécuter.

tool.execution_partial_result

Éphémère. Sortie incrémentielle d’un outil en cours d’exécution (par exemple, sortie bash en streaming).

tool.execution_progress

Éphémère. État de progression lisible par l’homme à partir d’un outil en cours d’exécution (par exemple, notifications de progression du serveur MCP).

tool.execution_complete

Émis lorsqu'un outil termine son exécution, avec succès ou avec une erreur.

** Result Champs:**

tool.user_requested

Émis lorsque l’utilisateur demande explicitement un appel d’outil (plutôt que le modèle choisissant d’en appeler un).

Événements de cycle de vie de session

session.idle

Éphémère. L’agent a terminé tout le traitement et est prêt pour le message suivant. Il s’agit du signal qu’un tour est entièrement terminé.

session.error

Une erreur s’est produite pendant le traitement de la session.

session.compaction_start

La compaction de la fenêtre de contexte a commencé. La charge utile des données est vide ({}).

session.compaction_complete

Compactage de fenêtre de contexte terminé.

session.title_changed

Éphémère. Le titre généré automatiquement de la session a été mis à jour.

session.context_changed

Le répertoire de travail ou le contexte du référentiel de la session a changé.

session.usage_info

Éphémère. Instantané d’utilisation de la fenêtre de contexte.

session.session_limits_changed

Les limites de session ont changé pour la fenêtre de comptabilité actuelle. Une null``sessionLimits valeur signifie qu’aucune limite n’est active.

session.usage_checkpoint

Point de contrôle de l’utilisation agrégée durable utilisé pour reconstituer la comptabilité lors de la reprise d’une session.

session.task_complete

L’agent a terminé sa tâche affectée.

session.shutdown

La session s’est terminée.

Événements d’autorisation et d’entrée utilisateur

Ces événements sont émis lorsque l’agent a besoin d’approbation ou d’entrée de l’utilisateur avant de continuer.

permission.requested

L’agent a besoin d’une autorisation pour effectuer une action (exécuter une commande, écrire un fichier, etc.).

Il permissionRequest s’agit d’une union discriminatoire sur kind:

Toutes les kind variantes incluent également une liaison facultative toolCallId vers l’appel d’outil qui a déclenché la demande.

permission.completed

Une demande d’autorisation a été résolue.

user_input.requested

Éphémère. L’agent pose une question à l’utilisateur.

user_input.completed

Éphémère. Une demande d’entrée utilisateur a été résolue.

elicitation.requested

Éphémère. L'agent a besoin d'une entrée de formulaire structurée de l'utilisateur (protocole MCP d'élucidation).

elicitation.completed

Éphémère. Une demande d’éciation a été résolue.

Événements de sous-agent et de compétence

subagent.started

Un agent personnalisé a été appelé en tant que sous-agent.

subagent.completed

Un sous-agent a terminé avec succès.

subagent.failed

Un sous-agent a rencontré une erreur.

subagent.selected

Un agent personnalisé a été sélectionné (déduit) pour gérer la requête actuelle.

subagent.deselected

Un agent personnalisé a été désélectionné, retournant à l’agent par défaut. La charge utile des données est vide ({}).

skill.invoked

Une compétence a été activée pour la conversation actuelle.

Autres événements

abort

Le tour actuel a été abandonné.

user.message

L’utilisateur a envoyé un message. Enregistré pour la chronologie de la session.

system.message

Une invite de système ou de développeur a été injectée dans la conversation.

external_tool.requested

L’agent souhaite appeler un outil externe (fourni par le consommateur du SDK).

external_tool.completed

Une demande d’outil externe a été résolue.

exit_plan_mode.requested

Éphémère. L’agent a créé un plan et souhaite quitter le mode plan.

exit_plan_mode.completed

Éphémère. Une demande de mode de plan de sortie a été résolue.

command.queued

Éphémère. Une commande slash a été mise en file d’attente pour exécution.

command.completed

Éphémère. Une commande mise en file d’attente a été résolue.

session_limits_exhausted.requested

Éphémère. Le budget de session actuel a été épuisé et le runtime a besoin d’une décision de l’utilisateur avant de continuer.

session_limits_exhausted.completed

Éphémère. Une demande de limite épuisée en attente a été résolue.

Référence rapide : flux de transformation agentique

Un tour agentique classique émet des événements dans cet ordre :

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)

Tous les types d’événements en un clin d’œil

Ce tableau répertorie les principaux champs de la charge utile data. Les champs d’enveloppe courants sont documentés ci-dessus.