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 import CopilotClient
from copilot.generated.session_events import SessionEventType

client = CopilotClient()

session = None  # assume session is created elsewhere

def handle(event):
    if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
        print(event.data.delta_content, end="", flush=True)

# session.on(handle)

from copilot.generated.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)

package main

import (
    "context"
    "fmt"
    copilot "github.com/github/copilot-sdk/go"
    "github.com/github/copilot-sdk/go/rpc"
)

func main() {
    ctx := context.Background()
    client := copilot.NewClient(nil)

    session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
        Model:     "gpt-4.1",
        Streaming: copilot.Bool(true),
        OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {
            return &rpc.PermissionDecisionApproveOnce{}, nil
        },
    })

    session.On(func(event copilot.SessionEvent) {
        if d, ok := event.Data.(*copilot.AssistantMessageDeltaData); ok {
            fmt.Print(d.DeltaContent)
        }
    })
    _ = session
}

session.On(func(event copilot.SessionEvent) {
    if d, ok := event.Data.(*copilot.AssistantMessageDeltaData); ok {
        fmt.Print(d.DeltaContent)
    }
})

using GitHub.Copilot;

public static class StreamingEventsExample
{
    public static async Task Example(CopilotSession session)
    {
        session.On<SessionEvent>(evt =>
        {
            if (evt is AssistantMessageDeltaEvent delta)
            {
                Console.Write(delta.Data.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())
);

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

Efêmero. 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

Efêmero. 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

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

external_tool.completed

Efêmero. 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.

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 (ephemeral)
│   ├── permission.completed  → Approval result (ephemeral)
│   ├── 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