Eventos de la sesión de transmisión

Visión general

Cuando streaming: true se establece en una sesión, el SDK emite eventos efímeros en tiempo real (deltas, actualizaciones de progreso) junto con eventos persistentes (mensajes completos, resultados de la herramienta). Todos los eventos comparten un sobre común y llevan una data carga cuya forma depende del evento type.

Contenedor de eventos

Cada evento de sesión, independientemente del tipo, incluye estos campos:

Suscribirse a eventos

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

Suscribirse antes de que se inicie una sesión

Una sesión puede emitir eventos antes de que se devuelva su llamada de creación o reanudación. Es posible que el agente ya esté trabajando —especialmente al reanudar con continuePendingWork—, y los eventos efímeros, como session.idle, nunca se escriben en el registro de la sesión, por lo que getMessages no puede recuperarlos después. Una suscripción instalada después de que exista el descriptor de sesión pierde esa ventana de inicio.

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_* es sincrónico e inert: valida la capacidad del búfer, asigna un canal local y no hace nada más. No hay ninguna sesión registrada y nada llega a la CLI hasta que se consulta start() por primera vez. Descartar una sesión preparada que nunca se inició no deja ningún estado residual y cierra sus suscripciones; al descartar el valor futuro start(), se cancela el inicio en curso y se cancela el registro de la sesión, por lo que un reintento con el mismo identificador de sesión tiene éxito. La limpieza tiene como ámbito el registro exacto que posee el inicio abandonado, por lo que no puede expulsar un reintento que ya haya tomado el mismo identificador de sesión.

Conviene planificar el almacenamiento en búfer al iniciar:

• El búfer de eventos es finito: 512 eventos, a menos que event_buffer_capacity lo anule. Se rechaza una capacidad de 0 con un error de configuración no válida en lugar de limitarla.
• Los suscriptores lentos observan un Lagged error que informa de cuántos eventos se han omitido. Nunca ejercen contrapresión sobre el bucle de eventos de la sesión.
• Los consumidores que necesiten una visión sin pérdida de una gran ráfaga de arranque deben configurar una capacidad que la cubra o vaciar la suscripción simultáneamente con start().

Representar solo la respuesta del agente primario

Los eventos de los subagentes comparten el flujo de la sesión principal e incluyen agentId en el nivel de sobre. Los eventos del agente raíz/principal y los eventos en el nivel de sesión omiten agentId, por lo que los renderizadores del chat principal pueden ignorar los eventos del asistente en los que se ha establecido agentId y, en su lugar, redirigir dichos eventos a trazas o a la interfaz de usuario de progreso.

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

Eventos del asistente

Estos eventos realizan un seguimiento del ciclo de vida de respuesta del agente, desde el inicio del turno mediante fragmentos transmitidos en streaming hasta el mensaje final.

assistant.turn_start

Se genera cuando el agente inicia a procesar un turno.

assistant.intent

Efímero. Descripción breve de lo que el agente está haciendo actualmente, actualizado a medida que funciona.

assistant.reasoning

Bloque completo de razonamiento ampliado del modelo. Emitido después de finalizar el razonamiento.

assistant.reasoning_delta

Efímero. Fragmento incremental del razonamiento ampliado del modelo, transmitido en tiempo real.

assistant.message

Respuesta completa del asistente para esta llamada al LLM. Puede incluir solicitudes de invocación de herramientas.

** ToolRequest campos:**

assistant.message_delta

Efímero. Fragmento incremental de la respuesta de texto del asistente, transmitido en tiempo real.

assistant.turn_end

Se genera cuando el agente finaliza un turno (todas las ejecuciones de herramientas se completan y se entrega la respuesta final).

assistant.usage

Efímero. Información de costos y uso de tokens para una llamada API individual.

assistant.streaming_delta

Efímero. Indicador de progreso de red de bajo nivel: bytes totales recibidos de la respuesta de la API de streaming.

Eventos de ejecución de herramientas

Estos eventos realizan un seguimiento del ciclo de vida completo de cada invocación de herramienta, desde el modelo que solicita una llamada de herramienta a través de la ejecución hasta la finalización.

tool.execution_start

Se genera cuando una herramienta comienza a ejecutarse.

tool.execution_partial_result

Efímero. Salida incremental de una herramienta en ejecución (p. ej., salida de bash en streaming).

tool.execution_progress

Efímero. Estado de progreso legible de una herramienta en ejecución (por ejemplo, notificaciones de progreso del servidor MCP).

tool.execution_complete

Se genera cuando una herramienta termina de ejecutarse correctamente o con un error.

** Result campos:**

tool.user_requested

Se activa cuando el usuario solicita explícitamente una invocación de herramienta, en lugar de que el modelo decida llamarla.

Eventos del ciclo de vida de la sesión

session.idle

Efímero. El agente ha terminado todo el procesamiento y está listo para el siguiente mensaje. Esta es la señal de que un turno ha finalizado por completo.

session.error

Error durante el procesamiento de la sesión.

session.compaction_start

Se ha iniciado la compactación de ventanas de contexto. La carga de datos está vacía ({}).

session.compaction_complete

La compactación de la ventana de contexto finalizó.

session.title_changed

Efímero. Se actualizó el título generado automáticamente de la sesión.

session.context_changed

Se ha cambiado el directorio de trabajo o el contexto del repositorio de la sesión.

session.usage_info

Efímero. Instantánea de uso de la ventana de contexto.

session.session_limits_changed

Se han cambiado los límites de sesión para la ventana de contabilidad actual. Un null``sessionLimits valor significa que no hay límites activos.

session.usage_checkpoint

Punto de control de uso agregado duradero que se usa para reconstruir la contabilidad cuando se reanuda una sesión.

session.task_complete

El agente ha completado su tarea asignada.

session.shutdown

La sesión finalizó.

Permisos y eventos de entrada de usuario

Estos eventos se emiten cuando el agente necesita aprobación o entrada del usuario antes de continuar.

permission.requested

El agente necesita permiso para realizar una acción (ejecutar un comando, escribir un archivo, etc.).

El permissionRequest es una unión discriminada en kind:

Todas las variantes kind también incluyen un enlace opcional toolCallId que retorna a la llamada de herramienta que desencadenó la solicitud.

permission.completed

Se resolvió una solicitud de permiso.

user_input.requested

Efímero. El agente está haciendo una pregunta al usuario.

user_input.completed

Efímero. Se resolvió una solicitud de entrada de usuario.

elicitation.requested

Efímero. El agente necesita una entrada de formulario estructurada del usuario (protocolo de elicitación MCP).

elicitation.completed

Efímero. Se resolvió una solicitud de elicitación.

Eventos de subagentes y aptitudes

subagent.started

Se invocó un agente personalizado como subagente.

subagent.completed

Un subagente finalizó correctamente.

subagent.failed

Un subagente encontró un error.

subagent.selected

Se ha seleccionado (deducido) un agente personalizado para administrar la solicitud actual.

subagent.deselected

Se deseleccionó un agente personalizado y se devolvió al agente predeterminado. La carga de datos está vacía ({}).

skill.invoked

Se activó una habilidad en la conversación actual.

Otros eventos

abort

Se anuló el turno actual.

user.message

El usuario envió un mensaje. Registrado para la línea de tiempo de la sesión.

system.message

Se insertó un mensaje del sistema o del desarrollador en la conversación.

external_tool.requested

El agente quiere invocar una herramienta externa (una proporcionada por el consumidor del SDK).

external_tool.completed

Se resolvió una solicitud de herramienta externa.

exit_plan_mode.requested

Efímero. El agente ha creado un plan y quiere salir del modo de plan.

exit_plan_mode.completed

Efímero. Se resolvió una solicitud de modo de plan de salida.

command.queued

Efímero. Se ha puesto en cola un comando de barra para su ejecución.

command.completed

Efímero. Se ha resuelto un comando en cola.

session_limits_exhausted.requested

Efímero. El presupuesto de sesión actual se agotó y el tiempo de ejecución necesita una decisión de usuario antes de continuar.

session_limits_exhausted.completed

Efímero. Se resolvió una solicitud de límite agotado pendiente.

Referencia rápida: flujo de turnos de agentes

Un turno agente típico emite eventos en este orden:

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)

Todos los tipos de eventos de un vistazo

En esta tabla se enumeran los campos de carga clave data . Los campos comunes de la envolvente se describen más arriba.