Eventos de sessão de streaming

Overview

Quando streaming: true é definido em uma sessão, o SDK emite eventos efêmeros em tempo real (deltas, atualizações de progresso) junto com eventos persistentes (mensagens completas, resultados da ferramenta). Todos os eventos compartilham um envelope comum e carregam uma data carga cuja forma depende do evento type.

Envelope de evento

Cada evento de sessão, independentemente do tipo, inclui estes campos:

Inscrevendo-se para 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())
);

Assinatura antes do início de uma sessão

Uma sessão pode emitir eventos antes que sua chamada de criação ou retomada seja retornada. O agente pode já estar em execução — especialmente na retomada com continuePendingWork — e eventos efêmeros, como session.idle, nunca são gravados no log de sessão; portanto, getMessages não consegue recuperá-los depois. Uma assinatura instalada depois que o identificador de sessão existe perde essa janela de inicialização.

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_* é síncrono e inerte: valida a capacidade do buffer, aloca um canal local e não faz mais nada. Nenhuma sessão fica registrada e nada chega à CLI até que start() seja sondado pela primeira vez. Descartar uma sessão preparada que nunca foi iniciada não deixa nenhum estado para trás e fecha suas assinaturas; descartar o start() future cancela a inicialização em andamento e remove o registro da sessão, de modo que uma nova tentativa com o mesmo ID de sessão seja bem-sucedida. A limpeza se limita ao registro exato que a inicialização abandonada possuía, portanto não pode descartar uma nova tentativa que já tenha assumido o mesmo ID da sessão.

Vale a pena planejar o buffer de inicialização para:

• O buffer de eventos é finito— 512 eventos, a menos que event_buffer_capacity o substitua. Uma capacidade de 0 é rejeitada com um erro de configuração inválida em vez de fixada.
• Assinantes lentos observam um Lagged erro relatando quantos eventos foram ignorados. Eles nunca impõem controle de pressão ao loop de eventos da sessão.
• Os consumidores que precisam de uma exibição sem perdas de uma grande intermitência de inicialização devem configurar uma capacidade que a cobre ou esvaziar a assinatura simultaneamente.start()

Renderize somente a resposta do agente principal

Os eventos do subagente compartilham o fluxo da sessão principal e incluem o nível de envelope agentId. Os eventos do agente raiz/principal e os eventos de nível de sessão omitem agentId, portanto, os renderizadores do chat principal podem ignorar os eventos do assistente onde agentId está definido e encaminhar esses eventos para rastreamentos ou para a interface de progresso.

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 do assistente

Esses eventos acompanham o ciclo de vida de resposta do agente, desde o início da vez, passando pelos fragmentos de streaming até a mensagem final.

assistant.turn_start

Emitido quando o agente começa a processar uma rodada.

assistant.intent

Efêmero. Breve descrição do que o agente está fazendo no momento, atualizada conforme funciona.

assistant.reasoning

Conclua o bloco de pensamento estendido do modelo. Emitido após a conclusão do raciocínio.

assistant.reasoning_delta

Efêmero. Bloco incremental do pensamento estendido do modelo, transmitido em tempo real.

assistant.message

Resposta completa do assistente para esta chamada LLM. Pode incluir solicitações de invocação de ferramentas.

** ToolRequest Campos:**

assistant.message_delta

Efêmero. Porção incremental da resposta de texto do assistente, transmitida em tempo real.

assistant.turn_end

Emitido quando o agente conclui um turno (todas as execuções de ferramentas são concluídas, resposta final fornecida).

assistant.usage

Efêmero. Informações de uso e custo de token para uma chamada de API individual.

assistant.streaming_delta

Efêmero. Indicador de progresso de rede de baixo nível – total de bytes recebidos da resposta da API de streaming.

Eventos de execução de ferramentas

Esses eventos acompanham o ciclo de vida completo de cada invocação de ferramenta, desde o modelo que solicita uma chamada de ferramenta até a execução até a conclusão.

tool.execution_start

Emitido quando uma ferramenta começa a ser executada.

tool.execution_partial_result

Efêmero. Saída incremental de uma ferramenta em execução (por exemplo, saída de bash em streaming).

tool.execution_progress

Efêmero. Status de progresso legível por humanos de uma ferramenta em execução (por exemplo, notificações de progresso do servidor MCP).

tool.execution_complete

Emitido quando uma ferramenta termina de executar— com êxito ou com um erro.

** Result Campos:**

tool.user_requested

Emitido quando o usuário solicita explicitamente uma invocação de ferramenta (em vez do modelo optando por chamar uma).

Eventos de ciclo de vida da sessão

session.idle

Efêmero. O agente concluiu todo o processamento e está pronto para a próxima mensagem. Esse é o sinal de que uma curva está totalmente concluída.

session.error

Ocorreu um erro durante o processamento da sessão.

session.compaction_start

A compactação da janela de contexto começou. A carga de dados está vazia ({}).

session.compaction_complete

Compactação da janela de contexto concluída.

session.title_changed

Efêmero. O título gerado automaticamente da sessão foi atualizado.

session.context_changed

O diretório de trabalho ou o contexto do repositório da sessão foi alterado.

session.usage_info

Efêmero. Instantâneo de utilização da janela de contexto.

session.session_limits_changed

Os limites da sessão foram alterados para o período contábil atual. Um null``sessionLimits valor significa que nenhum limite está ativo.

session.usage_checkpoint

Ponto de verificação durável do uso agregado usado para reconstruir a contabilização quando uma sessão é retomada.

session.task_complete

O agente concluiu sua tarefa atribuída.

session.shutdown

A sessão foi encerrada.

Eventos de permissão e de interação do usuário

Esses eventos são emitidos quando o agente precisa de aprovação ou entrada do usuário antes de continuar.

permission.requested

O agente precisa de permissão para executar uma ação (executar um comando, gravar um arquivo etc.).

A permissionRequest é uma união discriminada de kind:

Todas as variantes kind também incluem uma vinculação opcional toolCallId de volta à chamada de ferramenta que disparou a solicitação.

permission.completed

Uma solicitação de permissão foi resolvida.

user_input.requested

Efêmero. O agente está fazendo uma pergunta ao usuário.

user_input.completed

Efêmero. Uma solicitação de entrada do usuário foi resolvida.

elicitation.requested

Efêmero. O agente precisa de entrada estruturada de dados do usuário (protocolo de elicitação MCP).

elicitation.completed

Efêmero. Uma solicitação de elicitação foi resolvida.

Eventos de subagente e habilidade

subagent.started

Um agente personalizado foi invocado como um subagente.

subagent.completed

Um subagente concluiu com sucesso.

subagent.failed

Um subagente encontrou um erro.

subagent.selected

Um agente personalizado foi selecionado (inferido) para lidar com a solicitação atual.

subagent.deselected

Um agente personalizado foi desselecionado, retornando ao agente padrão. A carga de dados está vazia ({}).

skill.invoked

Uma habilidade foi ativada para a conversa atual.

Outros eventos

abort

O turno atual foi abortado.

user.message

O usuário enviou uma mensagem. Gravado na linha do tempo da sessão.

system.message

Um prompt do sistema ou do desenvolvedor foi injetado na conversa.

external_tool.requested

O agente deseja invocar uma ferramenta externa (uma fornecida pelo consumidor do SDK).

external_tool.completed

Uma solicitação de ferramenta externa foi resolvida.

exit_plan_mode.requested

Efêmero. O agente criou um plano e deseja sair do modo de plano.

exit_plan_mode.completed

Efêmero. Uma solicitação de modo de plano de saída foi resolvida.

command.queued

Efêmero. Um comando barra "/" foi colocado na fila para execução.

command.completed

Efêmero. Um comando enfileirado foi resolvido.

session_limits_exhausted.requested

Efêmero. O orçamento atual da sessão foi esgotado e o runtime precisa de uma decisão do usuário antes de continuar.

session_limits_exhausted.completed

Efêmero. Uma solicitação pendente de limite esgotado foi resolvida.

Referência rápida: fluxo de agentes em turnos

Uma rodada de agente típica emite eventos nesta ordem:

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 os tipos de evento em um relance

Esta tabela lista os principais data campos de conteúdo. Campos de envelope comuns estão documentados acima.