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 é restrita ao registro específico que a inicialização abandonada detinha; portanto, ela não pode remover uma tentativa de reexecução que já tenha assumido o mesmo ID de 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 aplicam contrapressão ao loop de eventos da sessão.
• Os consumidores que necessitam de uma visualização sem perdas de um grande pico de inicialização devem configurar uma capacidade que o comporte ou esvaziar a assinatura simultaneamente ao 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

Preterido. Use tool.shell_output para saída do terminal em tempo real. Esse evento efêmero permanece emitido junto com a substituição durante a migração; Assine apenas uma representação para evitar exibir a mesma saída duas vezes.

tool.shell_output

Efêmero. Saída somente para acréscimo de um comando de terminal anexado ou de um comando de terminal solicitado pelo usuário. Cada evento contém texto recentemente observado, com segredos filtrados, sem os separadores ou marcadores usados para formatar os resultados finais da ferramenta para o modelo.

text Acumular separadamente por toolCallId estream, ou unir as partes em ordem de sequência para uma exibição combinada. Um número de sequência identifica duplicatas e partes ausentes; ele não estabelece a ordenação exata entre gravações independentes do sistema operacional. Um assinante tardio pode receber uma primeira sequência maior que zero.

Esses eventos são somente ao vivo: eles não são persistidos ou reproduzidos após a retomada. Os resultados finais tool.execution_complete, a formatação voltada para o modelo e a captura de comando desanexada permanecem inalterados. O texto pode conter sequências de controle de terminal; os renderizadores devem aplicar sua manipulação normal de texto de terminal.

Um comando de terminal anexado pode continuar em execução depois de tool.execution_complete quando é executado de forma assíncrona ou continuar em execução além de initial_wait. A saída recebida ao continuar usa o toolCallId original e continua o mesmo sequence, em vez de reiniciar em zero. Os consumidores que exibem apenas chamadas ativas devem ignorar partes recebidas após a conclusão, em vez de recriar o estado de chamada concluída.

A filtragem de segredos opera em cada parte decodificada. O runtime não divide artificialmente as linhas, mas as leituras do sistema operacional podem dividir uma linha ou segredo entre partes; a reconstrução do segredo entre partes não é fornecida.

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.

Solicitações de gravação também podem incluir fileEdits em permissionRequest e promptRequest. Cada entrada contém instantâneos opcionais before e after, cada um com um path absoluto no namespace do sistema de arquivos da sessão e content UTF-8 completo. A ausência de before significa criação; a ausência de after significa exclusão. Uma cadeia de caracteres vazia content representa um arquivo vazio, não uma visualização indisponível. Um movimento pode ter caminhos diferentes em seus dois lados. Quando um movimento substitui um destino existente, entradas separadas descrevem a exclusão de origem e a substituição de destino.

Esses instantâneos descrevem a operação planejada, não uma leitura posterior do sistema de arquivos ativo. O runtime omite fileEdits quando não pode fornecer uma visualização de texto completa, incluindo solicitações feitas antes de ler um arquivo protegido por área restrita, conteúdo não UTF-8 ou um destino de movimentação ilegível ou não regular, como um pipe nomeado. Não infera uma exclusão de um valor herdado newFileContents vazio. Os campos existentes e as opções de aprovação permanecem disponíveis para consumidores que não usam visualizações.

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.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)

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.