Eventos de streaming no SDK do Copilot

Observação

          SDK do Copilot está atualmente em versão prévia técnica. A funcionalidade e a disponibilidade estão sujeitas a alterações.

Cada ação que o Copilot agente executa, pensando, escrevendo código, executando ferramentas, é emitida como um evento de sessão que você pode assinar. Este artigo é uma referência de nível de campo para cada tipo de evento para que você saiba exatamente quais dados esperar.

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. Para obter um diagrama de sequência do fluxo de eventos completo, consulte o github/copilot-sdk repositório.

Conceito	Descrição

          **Evento efêmero** | Transitório; transmitido em tempo real, mas **não** persistido no log de sessão. Não reproduzido na retomada da sessão. |

| Evento persistente | Salvo no log de eventos da sessão no disco. Reiniciado ao retomar uma sessão. | | Evento Delta | Uma parte efêmera de streaming (texto ou raciocínio). Acumule deltas para construir o conteúdo completo. | | ** parentId Cadeia** | Cada evento em parentId aponta para o evento anterior, formando uma lista encadeada que você pode percorrer. |

Envelope de evento

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

Campo	Tipo	Descrição
`id`

          `string` (UUID v4) | Identificador de evento exclusivo |

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

Para obter exemplos em Python, Go e .NET, consulte o github/copilot-sdk repositório.

Dica

          **Python/Go:** Esses SDKs usam uma única `Data` classe/struct com todos os campos possíveis como opcionais/anuláveis. Somente os campos listados nas tabelas abaixo são preenchidos para cada tipo de evento– o restante será `None` / `nil`.

          **.NET:** O SDK do .NET usa classes de dados separadas e fortemente tipadas por evento (por exemplo, `AssistantMessageDeltaData`), portanto, somente os campos relevantes existem em cada tipo.

          **TypeScript:** O SDK do TypeScript usa uma união discriminada — quando você faz a correspondência em `event.type`, o payload `data` é restringido automaticamente à forma correta.

Eventos do assistente

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

`assistant.turn_start`

Emitido quando o agente começa a processar uma etapa da conversa.

Campo de dados	Tipo	Obrigatório	Descrição
`turnId`	`string`	✅	Identificador de turno (normalmente um número de turno em cadeia de caracteres)
`interactionId`	`string`
Identificador de interação para correlação de telemetria

`assistant.intent`

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

Campo de dados	Tipo	Obrigatório	Descrição
`intent`	`string`	✅	Intenção legível por humanos (por exemplo, "Explorando a base de código")

`assistant.reasoning`

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

Campo de dados	Tipo	Obrigatório	Descrição
`reasoningId`	`string`	✅	Identificador exclusivo para esse bloco de raciocínio
`content`	`string`	✅	O texto de pensamento estendido completo

`assistant.reasoning_delta`

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

Campo de dados	Tipo	Obrigatório	Descrição
`reasoningId`	`string`	✅	Corresponde ao evento correspondente `assistant.reasoning`
`deltaContent`	`string`	✅	Parte de texto a ser acrescentada ao conteúdo de raciocínio

`assistant.message`

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

Campo de dados	Tipo	Obrigatório	Descrição
`messageId`	`string`	✅	Identificador exclusivo para esta mensagem
`content`	`string`	✅	Resposta de texto do assistente
`toolRequests`	`ToolRequest[]`
Chamadas de ferramenta que o assistente deseja fazer (veja abaixo)
`reasoningOpaque`	`string`
Pensamento estendido criptografado (modelos antropáticos); associado à sessão
`reasoningText`	`string`
Texto claro de raciocínio a partir de pensamento aprofundado
`encryptedContent`	`string`
Conteúdo de raciocínio criptografado (modelos OpenAI); associado à sessão
`phase`	`string`
Fase de geração (por exemplo, `"thinking"` vs `"response"`)
`outputTokens`	`number`
Contagem real de tokens de saída na resposta da API
`interactionId`	`string`
Identificador de interação para telemetria
`parentToolCallId`	`string`
Definir quando essa mensagem se origina de um subagente

          **
          `ToolRequest` Campos:**

Campo	Tipo	Obrigatório	Descrição
`toolCallId`	`string`	✅	Identificação única para esta chamada de método
`name`	`string`	✅	Nome da ferramenta (por exemplo, `"bash"`, `"edit"`, `"grep"`)
`arguments`	`object`
Argumentos analisados para a ferramenta
`type`	`"function" \| "custom"`
Tipo de chamada; é definido como `"function"` caso esteja ausente

`assistant.message_delta`

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

Campo de dados	Tipo	Obrigatório	Descrição
`messageId`	`string`	✅	Corresponde ao evento correspondente `assistant.message`
`deltaContent`	`string`	✅	Parte de texto a ser acrescentada à mensagem
`parentToolCallId`	`string`
Defina quando se originar de um subagente

`assistant.turn_end`

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

Campo de dados	Tipo	Obrigatório	Descrição
`turnId`	`string`	✅	Corresponde ao evento correspondente `assistant.turn_start`

`assistant.usage`

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

Campo de dados	Tipo	Obrigatório	Descrição
`model`	`string`	✅	Identificador de modelo (por exemplo, `"gpt-4.1"`)
`inputTokens`	`number`
Tokens de entrada consumidos
`outputTokens`	`number`
Tokens de saída produzidos
`cacheReadTokens`	`number`
Tokens lidos do cache de mensagens de prompt
`cacheWriteTokens`	`number`
Tokens gravados no cache de prompt
`cost`	`number`
Custo do multiplicador de modelo para cobrança
`duration`	`number`
Duração da chamada à API em milissegundos
`initiator`	`string`
O que originou esta chamada (por exemplo, `"sub-agent"`); ausente se iniciada pelo usuário
`apiCallId`	`string`
ID de conclusão do provedor (por exemplo, `chatcmpl-abc123`)
`providerCallId`	`string`

          GitHub ID de rastreamento de solicitação (`x-github-request-id`) |

`assistant.streaming_delta`

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

Campo de dados	Tipo	Obrigatório	Descrição
`totalResponseSizeBytes`	`number`	✅	Bytes cumulativos recebidos até agora

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.

Campo de dados	Tipo	Obrigatório	Descrição
`toolCallId`	`string`	✅	Identificador exclusivo para esta chamada de ferramenta
`toolName`	`string`	✅	Nome da ferramenta (por exemplo, `"bash"`, , `"edit"`) `"grep"`
`arguments`	`object`
Argumentos analisados passados para a ferramenta
`mcpServerName`	`string`
Nome do servidor MCP, quando a ferramenta é fornecida por um servidor MCP
`mcpToolName`	`string`
Nome da ferramenta original no servidor MCP
`parentToolCallId`	`string`
Definir quando invocado por um subagente

`tool.execution_partial_result`

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

Campo de dados	Tipo	Obrigatório	Descrição
`toolCallId`	`string`	✅	Corresponde ao correspondente `tool.execution_start`
`partialOutput`	`string`	✅	Bloco de saída incremental

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

Campo de dados	Tipo	Obrigatório	Descrição
`toolCallId`	`string`	✅	Corresponde ao correspondente `tool.execution_start`
`progressMessage`	`string`	✅	Mensagem de status de progresso

`tool.execution_complete`

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

Campo de dados	Tipo	Obrigatório	Descrição
`toolCallId`	`string`	✅	Corresponde ao correspondente `tool.execution_start`
`success`	`boolean`	✅	Se a execução foi bem-sucedida
`model`	`string`
Modelo que gerou essa chamada de ferramenta
`interactionId`	`string`
Identificador de interação
`isUserRequested`	`boolean`

          `true` quando o usuário solicitou explicitamente essa chamada de ferramenta |

| result | Result | | Apresentar sobre o sucesso (veja abaixo) | | error | { message, code? } | | Exibido em caso de falha | | toolTelemetry | object | | Telemetria específica da ferramenta | | parentToolCallId | string | | Definir quando invocado por um subagente |

          **
          `Result` Campos:**

Campo	Tipo	Obrigatório	Descrição
`content`	`string`	✅	Resultado conciso enviado para a LLM (pode ser truncado para eficiência de token)
`detailedContent`	`string`
Resultado completo para exibição, preservando conteúdo completo como difusões
`contents`	`ContentBlock[]`
Blocos de conteúdo estruturados (texto, terminal, imagem, áudio, recurso)

`tool.user_requested`

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

Campo de dados	Tipo	Obrigatório	Descrição
`toolCallId`	`string`	✅	Identificador exclusivo para esta chamada de ferramenta
`toolName`	`string`	✅	Nome da ferramenta que o usuário deseja invocar
`arguments`	`object`
Argumentos para a invocação

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.

Campo de dados	Tipo	Obrigatório	Descrição
`backgroundTasks`	`BackgroundTasks`
Agentes/shells em segundo plano ainda em execução quando o agente ficou ocioso

`session.error`

Ocorreu um erro durante o processamento da sessão.

Campo de dados	Tipo	Obrigatório	Descrição
`errorType`	`string`	✅	Categoria de erro (por exemplo, `"authentication"`, `"quota"`, `"rate_limit"`)
`message`	`string`	✅	Mensagem de erro legível por humanos
`stack`	`string`
Rastreamento de pilha de erros
`statusCode`	`number`
Código de status HTTP da solicitação upstream
`providerCallId`	`string`

          GitHub Solicitação de ID de rastreamento para correlação de log no lado do servidor |

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

Campo de dados	Tipo	Obrigatório	Descrição
`success`	`boolean`	✅	Se a compactação foi bem-sucedida
`error`	`string`
Mensagem de erro se a compactação falhou
`preCompactionTokens`	`number`
Tokens anteriores à compactação
`postCompactionTokens`	`number`
Tokens após a compactação
`preCompactionMessagesLength`	`number`
Contagem de mensagens antes da compactação
`messagesRemoved`	`number`
Mensagens removidas
`tokensRemoved`	`number`
Tokens removidos
`summaryContent`	`string`
Resumo do histórico compactado gerado por LLM
`checkpointNumber`	`number`
Número de captura de ponto de verificação criado para recuperação
`checkpointPath`	`string`
Caminho do arquivo onde o ponto de verificação foi armazenado
`compactionTokensUsed`	`{ input, output, cachedInput }`
Uso de token para a chamada LLM de compactação
`requestId`	`string`

          GitHub ID de rastreamento de solicitação para a chamada de compactação |

`session.title_changed`

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

Campo de dados	Tipo	Obrigatório	Descrição
`title`	`string`	✅	Novo título da sessão

`session.context_changed`

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

Campo de dados	Tipo	Obrigatório	Descrição
`cwd`	`string`	✅	Diretório de trabalho atual
`gitRoot`	`string`
Raiz do repositório Git
`repository`	`string`
Repositório em `"owner/name"` formato
`branch`	`string`
Branch atual do Git

`session.usage_info`

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

Campo de dados	Tipo	Obrigatório	Descrição
`tokenLimit`	`number`	✅	Tokens máximos para a janela de contexto do modelo
`currentTokens`	`number`	✅	Tokens atuais na janela de contexto
`messagesLength`	`number`	✅	Contagem de mensagens atual na conversa

`session.task_complete`

O agente concluiu sua tarefa atribuída.

Campo de dados	Tipo	Obrigatório	Descrição
`summary`	`string`
Resumo da tarefa concluída

`session.shutdown`

A sessão foi encerrada.

Campo de dados	Tipo	Obrigatório	Descrição
`shutdownType`	`"routine" \| "error"`	✅	Desligamento normal ou falha
`errorReason`	`string`
Descrição do erro quando `shutdownType` é `"error"`
`totalPremiumRequests`	`number`	✅	Total de solicitações de API Premium usadas
`totalApiDurationMs`	`number`	✅	Tempo de chamada da API cumulativa em milissegundos
`sessionStartTime`	`number`	✅	Timestamp Unix (ms) quando a sessão começou
`codeChanges`	`{ linesAdded, linesRemoved, filesModified }`	✅	Métricas agregadas de alteração de código
`modelMetrics`	`Record<string, ModelMetric>`	✅	Detalhamento de uso por modelo
`currentModel`	`string`
Modelo selecionado durante o desligamento

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

Campo de dados	Tipo	Obrigatório	Descrição
`requestId`	`string`	✅	Use isso para responder via `session.respondToPermission()`
`permissionRequest`	`PermissionRequest`	✅	Detalhes da permissão que está sendo solicitada

A permissionRequest é uma união discriminada de kind:

`kind`	Campos de chave	Descrição
`"shell"`

          `fullCommandText`, `intention`, , `commands[]``possiblePaths[]` | Executar um comando de shell |

Todas as kind variantes 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.

Campo de dados	Tipo	Obrigatório	Descrição
`requestId`	`string`	✅	Corresponde ao correspondente `permission.requested`
`result.kind`	`string`	✅	Um de: `"approved"`, `"denied-by-rules"`, `"denied-interactively-by-user"`, `"denied-no-approval-rule-and-could-not-request-from-user"`, `"denied-by-content-exclusion-policy"`

`user_input.requested`

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

Campo de dados	Tipo	Obrigatório	Descrição
`requestId`	`string`	✅	Use isso para responder via `session.respondToUserInput()`
`question`	`string`	✅	A pergunta a ser apresentada ao usuário
`choices`	`string[]`
Opções predefinidas para o usuário
`allowFreeform`	`boolean`
Se a entrada de texto de forma livre é permitida

`user_input.completed`

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

Campo de dados	Tipo	Obrigatório	Descrição
`requestId`	`string`	✅	Corresponde ao correspondente `user_input.requested`

`elicitation.requested`

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

Campo de dados	Tipo	Obrigatório	Descrição
`requestId`	`string`	✅	Use isso para responder via `session.respondToElicitation()`
`message`	`string`	✅	Descrição de quais informações são necessárias
`mode`	`"form"`
Modo de elicitação (no momento, somente `"form"`)
`requestedSchema`	`{ type: "object", properties, required? }`	✅	Esquema JSON que descreve os campos de formulário

`elicitation.completed`

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

Campo de dados	Tipo	Obrigatório	Descrição
`requestId`	`string`	✅	Corresponde ao correspondente `elicitation.requested`

Eventos de subagente e habilidade

`subagent.started`

Um agente personalizado foi invocado como um subagente.

Campo de dados	Tipo	Obrigatório	Descrição
`toolCallId`	`string`	✅	Chamada de ferramenta-mãe que gerou este subagente
`agentName`	`string`	✅	Nome interno do subagente
`agentDisplayName`	`string`	✅	Nome de exibição legível por humanos
`agentDescription`	`string`	✅	Descrição do que o subagente faz

`subagent.completed`

Um subagente concluiu com sucesso.

Campo de dados	Tipo	Obrigatório	Descrição
`toolCallId`	`string`	✅	Corresponde ao correspondente `subagent.started`
`agentName`	`string`	✅	Nome interno
`agentDisplayName`	`string`	✅	Nome de exibição

`subagent.failed`

Um subagente encontrou um erro.

Campo de dados	Tipo	Obrigatório	Descrição
`toolCallId`	`string`	✅	Corresponde ao correspondente `subagent.started`
`agentName`	`string`	✅	Nome interno
`agentDisplayName`	`string`	✅	Nome de exibição
`error`	`string`	✅	Mensagem de erro

`subagent.selected`

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

Campo de dados	Tipo	Obrigatório	Descrição
`agentName`	`string`	✅	Nome interno do agente selecionado
`agentDisplayName`	`string`	✅	Nome de exibição
`tools`	`string[] \| null`	✅	Nomes de ferramentas disponíveis para este agente; `null` para todas as ferramentas

`subagent.deselected`

Um agente personalizado foi desselecionado, retornando ao agente padrão. O conteúdo da resposta estará vazio ({}).

`skill.invoked`

Uma habilidade foi ativada para a conversa atual.

Campo de dados	Tipo	Obrigatório	Descrição
`name`	`string`	✅	Nome da habilidade
`path`	`string`	✅	Caminho do arquivo para a definição de SKILL.md
`content`	`string`	✅	Conteúdo completo da competência injetado na conversa
`allowedTools`	`string[]`
Ferramentas aprovadas automaticamente enquanto essa habilidade está ativa
`pluginName`	`string`
Plugin da skill de origem
`pluginVersion`	`string`
Versão do plug-in

Outros eventos

`abort`

O turno atual foi abortado.

Campo de dados	Tipo	Obrigatório	Descrição
`reason`	`string`	✅	Por que a curva foi abortada (por exemplo, `"user initiated"`)

`user.message`

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

Campo de dados	Tipo	Obrigatório	Descrição
`content`	`string`	✅	O texto da mensagem do usuário
`transformedContent`	`string`
Versão transformada após o pré-processamento
`attachments`	`Attachment[]`
Anexos de arquivo, diretório, seleção, blob ou GitHub referência
`source`	`string`
Identificador de origem da mensagem
`agentMode`	`string`
Modo de agente: `"interactive"`, , `"plan"`, `"autopilot"`ou `"shell"`
`interactionId`	`string`
Identificador de interação

`system.message`

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

Campo de dados	Tipo	Obrigatório	Descrição
`content`	`string`	✅	O texto do prompt
`role`	`"system" \| "developer"`	✅	Função de mensagem
`name`	`string`
Identificador de origem
`metadata`	`{ promptVersion?, variables? }`
Metadados do modelo de prompt

`external_tool.requested`

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

Campo de dados	Tipo	Obrigatório	Descrição
`requestId`	`string`	✅	Use isso para responder via `session.respondToExternalTool()`
`sessionId`	`string`	✅	Sessão à qual esta solicitação pertence
`toolCallId`	`string`	✅	ID de chamada de ferramenta para essa invocação
`toolName`	`string`	✅	Nome da ferramenta externa
`arguments`	`object`
Argumentos para a ferramenta

`external_tool.completed`

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

Campo de dados	Tipo	Obrigatório	Descrição
`requestId`	`string`	✅	Corresponde ao correspondente `external_tool.requested`

`exit_plan_mode.requested`

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

Campo de dados	Tipo	Obrigatório	Descrição
`requestId`	`string`	✅	Use isso para responder via `session.respondToExitPlanMode()`
`summary`	`string`	✅	Resumo do plano
`planContent`	`string`	✅	Conteúdo completo do arquivo de plano
`actions`	`string[]`	✅	Ações de usuário disponíveis (por exemplo, aprovar, editar, rejeitar)
`recommendedAction`	`string`	✅	Ação sugerida

`exit_plan_mode.completed`

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

Campo de dados	Tipo	Obrigatório	Descrição
`requestId`	`string`	✅	Corresponde ao correspondente `exit_plan_mode.requested`

`command.queued`

Efêmero. Um comando colocado na fila para execução.

Campo de dados	Tipo	Obrigatório	Descrição
`requestId`	`string`	✅	Use isso para responder via `session.respondToQueuedCommand()`
`command`	`string`	✅	O texto do comando de barra (por exemplo, `/help`, `/clear`)

`command.completed`

Efêmero. Um comando enfileirado foi resolvido.

Campo de dados	Tipo	Obrigatório	Descrição
`requestId`	`string`	✅	Corresponde ao correspondente `command.queued`

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

Uma curva 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

Tipo de evento	Efêmero	Categoria	Campos de dados chave
`assistant.turn_start`
Assistente

          `turnId`, `interactionId?` |

Quem pode usar esse recurso?

Neste artigo