Streaming de eventos en el SDK de Copilot

Nota:

          SDK de Copilot actualmente está en Versión preliminar técnica. La funcionalidad y la disponibilidad están sujetas a cambios.

Cada acción que toma el Copilot agente , pensando, escribiendo código, ejecutando herramientas, se emite como un evento de sesión al que puede suscribirse. Este artículo es una referencia de nivel de campo para cada tipo de evento para saber exactamente qué datos esperar.

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. Para obtener un diagrama de secuencia del flujo de eventos completo, consulte el github/copilot-sdk repositorio.

Concepto	Descripción

          **Evento efímero** | Transitorio; se transmite en tiempo real, pero **no** se conserva en el registro de sesión. No se reproduce al reanudar la sesión. |

| Evento persistente | Guardado en el registro de eventos de sesión en el disco. Se reproduce al reanudar una sesión. | | Evento Delta | Un fragmento de streaming efímero (texto o razonamiento). Acumula deltas para compilar el contenido completo. | | ** parentId cadena** | Cada evento parentId apunta al evento anterior, formando una lista enlazada que se puede recorrer. |

Contenedor de eventos

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

Campo	Tipo	Descripción
`id`

          `string` (UUID v4) | Identificador de evento único |

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

Para obtener ejemplos en Python, Go y .NET, consulte el github/copilot-sdk repositorio.

Sugerencia

          **Python/Go:** Estos SDK usan una sola `Data` clase o estructura con todos los campos posibles como opcionales o que aceptan valores NULL. Solo los campos enumerados en las tablas siguientes se rellenan para cada tipo de evento; el resto será `None` / `nil`.

          **.NET:** El SDK de .NET usa clases de datos independientes y fuertemente tipadas por evento (por ejemplo, `AssistantMessageDeltaData`), por lo que solo existen los campos pertinentes en cada tipo.

          **TypeScript:** El SDK de TypeScript usa una unión discriminada; cuando coincide con `event.type`, la `data` carga útil se limita automáticamente a la forma correcta.

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.

Campo de datos	Tipo	Obligatorio	Descripción
`turnId`	`string`	✅	Identificador de turno (normalmente un número de turno con cadena)
`interactionId`	`string`
Identificador de interacción para la correlación de telemetría

`assistant.intent`

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

Campo de datos	Tipo	Obligatorio	Descripción
`intent`	`string`	✅	Intención legible para personas (por ejemplo, "Exploración del código base")

`assistant.reasoning`

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

Campo de datos	Tipo	Obligatorio	Descripción
`reasoningId`	`string`	✅	Identificador único de este bloque de razonamiento
`content`	`string`	✅	Texto completo de pensamiento avanzado

`assistant.reasoning_delta`

Efímero. Fragmento incremental del pensamiento extendido del modelo, transmitido en tiempo real.

Campo de datos	Tipo	Obligatorio	Descripción
`reasoningId`	`string`	✅	Coincide con el evento correspondiente `assistant.reasoning` .
`deltaContent`	`string`	✅	Fragmento de texto que se va a anexar al contenido de razonamiento

`assistant.message`

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

Campo de datos	Tipo	Obligatorio	Descripción
`messageId`	`string`	✅	Identificador único de este mensaje
`content`	`string`	✅	Respuesta de texto del asistente
`toolRequests`	`ToolRequest[]`
Llamadas a herramientas que el asistente desea realizar (ver abajo)
`reasoningOpaque`	`string`
Pensamiento extendido cifrado (modelos antrópicos); vinculado a sesión
`reasoningText`	`string`
Texto de razonamiento legible a partir del pensamiento ampliado
`encryptedContent`	`string`
Contenido de razonamiento cifrado (modelos de OpenAI); vinculado a la sesión
`phase`	`string`
La fase de generación (por ejemplo, `"thinking"` frente a `"response"`)
`outputTokens`	`number`
Recuento real de tokens de salida de la respuesta de la API
`interactionId`	`string`
Identificador de interacción para la telemetría
`parentToolCallId`	`string`
Establecer cuándo se origina este mensaje desde un subagente

          **
          `ToolRequest` campos:**

Campo	Tipo	Obligatorio	Descripción
`toolCallId`	`string`	✅	Identificador único para esta llamada de herramienta
`name`	`string`	✅	Nombre de la herramienta (por ejemplo, `"bash"`, `"edit"`, `"grep"`)
`arguments`	`object`
Argumentos analizados para la herramienta
`type`	`"function" \| "custom"`
Tipo de llamada; el valor predeterminado es `"function"` cuando está ausente.

`assistant.message_delta`

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

Campo de datos	Tipo	Obligatorio	Descripción
`messageId`	`string`	✅	Coincide con el evento correspondiente `assistant.message` .
`deltaContent`	`string`	✅	Fragmento de texto que se va a anexar al mensaje
`parentToolCallId`	`string`
Se establece al originar por un subagente

`assistant.turn_end`

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

Campo de datos	Tipo	Obligatorio	Descripción
`turnId`	`string`	✅	Coincide con el evento correspondiente `assistant.turn_start` .

`assistant.usage`

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

Campo de datos	Tipo	Obligatorio	Descripción
`model`	`string`	✅	Identificador de modelo (por ejemplo, `"gpt-4.1"`)
`inputTokens`	`number`
Tokens de entrada consumidos
`outputTokens`	`number`
Tokens de salida generados
`cacheReadTokens`	`number`
Tokens leídos de la caché de prompt
`cacheWriteTokens`	`number`
Tokens escritos para solicitar caché
`cost`	`number`
Coste del multiplicador de modelos para la facturación
`duration`	`number`
Duración de la llamada API en milisegundos
`initiator`	`string`
Lo que desencadenó esta llamada (por ejemplo, `"sub-agent"`) estará ausente si es iniciado por el usuario
`apiCallId`	`string`
Identificador de finalización del proveedor (por ejemplo, `chatcmpl-abc123`)
`providerCallId`	`string`

          GitHub id. de seguimiento de solicitudes (`x-github-request-id`) |

`assistant.streaming_delta`

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

Campo de datos	Tipo	Obligatorio	Descripción
`totalResponseSizeBytes`	`number`	✅	Bytes acumulados recibidos hasta ahora

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.

Campo de datos	Tipo	Obligatorio	Descripción
`toolCallId`	`string`	✅	Identificador único de esta llamada de herramienta
`toolName`	`string`	✅	Nombre de la herramienta (por ejemplo, `"bash"`, `"edit"`, `"grep"`)
`arguments`	`object`
Argumentos analizados pasados a la herramienta
`mcpServerName`	`string`
Nombre del servidor MCP, cuando un servidor MCP proporciona la herramienta
`mcpToolName`	`string`
Nombre de la herramienta original en el servidor MCP
`parentToolCallId`	`string`
Establecer cuando lo invoca un subagente

`tool.execution_partial_result`

Efímero. Salida incremental de una herramienta en ejecución (por ejemplo, salida de Bash en transmisión).

Campo de datos	Tipo	Obligatorio	Descripción
`toolCallId`	`string`	✅	Coincide con el correspondiente `tool.execution_start`
`partialOutput`	`string`	✅	Fragmento de salida incremental

`tool.execution_progress`

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

Campo de datos	Tipo	Obligatorio	Descripción
`toolCallId`	`string`	✅	Coincide con el elemento correspondiente `tool.execution_start`
`progressMessage`	`string`	✅	Mensaje de estado de progreso

`tool.execution_complete`

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

Campo de datos	Tipo	Obligatorio	Descripción
`toolCallId`	`string`	✅	Coincide con el elemento correspondiente `tool.execution_start`
`success`	`boolean`	✅	Si la ejecución se realizó correctamente
`model`	`string`
Modelo que generó esta invocación de herramienta
`interactionId`	`string`
Identificador de interacción
`isUserRequested`	`boolean`

          `true` cuando el usuario solicitó explícitamente el uso de esta herramienta |

| result | Result | | Mostrar en caso de éxito (consulte a continuación) | | error | { message, code? } | | Presente en caso de error | | toolTelemetry | object | | Telemetría específica de la herramienta | | parentToolCallId | string | | Establecer cuando lo invoca un subagente |

          **
          `Result` campos:**

Campo	Tipo	Obligatorio	Descripción
`content`	`string`	✅	Resultado conciso enviado al LLM (podría truncarse para la eficacia del uso de tokens)
`detailedContent`	`string`
Resultado completo para mostrar, conservando contenido completo como diferencias
`contents`	`ContentBlock[]`
Bloques de contenido estructurados (texto, terminal, imagen, audio, recurso)

`tool.user_requested`

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

Campo de datos	Tipo	Obligatorio	Descripción
`toolCallId`	`string`	✅	Identificador único de esta llamada de herramienta
`toolName`	`string`	✅	Nombre de la herramienta que el usuario quiere invocar
`arguments`	`object`
Argumentos para la invocación

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 giro está completamente completo.

Campo de datos	Tipo	Obligatorio	Descripción
`backgroundTasks`	`BackgroundTasks`
Los agentes o shells en segundo plano siguen ejecutándose cuando el agente queda inactivo

`session.error`

Error durante el procesamiento de la sesión.

Campo de datos	Tipo	Obligatorio	Descripción
`errorType`	`string`	✅	Categoría de error (por ejemplo, `"authentication"`, `"quota"`, `"rate_limit"`)
`message`	`string`	✅	Mensaje de error legible por humanos
`stack`	`string`
Seguimiento de pila de errores
`statusCode`	`number`
Código de estado HTTP de la solicitud ascendente
`providerCallId`	`string`

          GitHub identificador de seguimiento de solicitudes para la correlación del registro del lado servidor |

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

Campo de datos	Tipo	Obligatorio	Descripción
`success`	`boolean`	✅	Si la compactación se realizó correctamente
`error`	`string`
Mensaje de error si se produjo un error en la compactación
`preCompactionTokens`	`number`
Tokens antes de la compactación
`postCompactionTokens`	`number`
Tokens después de la compactación
`preCompactionMessagesLength`	`number`
Recuento de mensajes antes de la compactación
`messagesRemoved`	`number`
Mensajes quitados
`tokensRemoved`	`number`
Tokens eliminados
`summaryContent`	`string`
Resumen generado por LLM del historial compacto
`checkpointNumber`	`number`
Número de instantánea de punto de control creado para la recuperación
`checkpointPath`	`string`
Ruta del archivo donde se almacenó el punto de control
`compactionTokensUsed`	`{ input, output, cachedInput }`
Uso de tokens para la llamada LLM de compactación
`requestId`	`string`

          GitHub identificador de seguimiento de solicitudes para la llamada de compactación |

`session.title_changed`

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

Campo de datos	Tipo	Obligatorio	Descripción
`title`	`string`	✅	Nuevo título de sesión

`session.context_changed`

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

Campo de datos	Tipo	Obligatorio	Descripción
`cwd`	`string`	✅	Directorio de trabajo actual
`gitRoot`	`string`
Raíz del repositorio de Git
`repository`	`string`
Repositorio en `"owner/name"` formato
`branch`	`string`
Rama de Git actual

`session.usage_info`

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

Campo de datos	Tipo	Obligatorio	Descripción
`tokenLimit`	`number`	✅	Número máximo de tokens para la ventana de contexto del modelo
`currentTokens`	`number`	✅	Tokens actuales en la ventana de contexto
`messagesLength`	`number`	✅	Recuento de mensajes actual en la conversación

`session.task_complete`

El agente ha completado su tarea asignada.

Campo de datos	Tipo	Obligatorio	Descripción
`summary`	`string`
Resumen de la tarea completada

`session.shutdown`

La sesión finalizó.

Campo de datos	Tipo	Obligatorio	Descripción
`shutdownType`	`"routine" \| "error"`	✅	Apagado normal o fallo
`errorReason`	`string`
Descripción del error cuando `shutdownType` está `"error"`
`totalPremiumRequests`	`number`	✅	Total de solicitudes de API Premium usadas
`totalApiDurationMs`	`number`	✅	Tiempo de llamada API acumulado en milisegundos
`sessionStartTime`	`number`	✅	Marca de tiempo de Unix (ms) cuando se inició la sesión
`codeChanges`	`{ linesAdded, linesRemoved, filesModified }`	✅	Métricas agregadas de cambio de código
`modelMetrics`	`Record<string, ModelMetric>`	✅	Desglose del uso por modelo
`currentModel`	`string`
Modelo seleccionado en el momento de apagado

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`

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

Campo de datos	Tipo	Obligatorio	Descripción
`requestId`	`string`	✅	Usa esto para responder a través de `session.respondToPermission()`
`permissionRequest`	`PermissionRequest`	✅	Detalles del permiso que se solicita

es permissionRequest una unión discriminada en kind:

`kind`	Campos clave	Descripción
`"shell"`

          `fullCommandText`, `intention`, , `commands[]`, `possiblePaths[]` | Ejecutar un comando de shell |

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

`permission.completed`

Efímero. Se resolvió una solicitud de permiso.

Campo de datos	Tipo	Obligatorio	Descripción
`requestId`	`string`	✅	Coincide con el elemento correspondiente `permission.requested`
`result.kind`	`string`	✅	Uno 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. El agente está haciendo una pregunta al usuario.

Campo de datos	Tipo	Obligatorio	Descripción
`requestId`	`string`	✅	Úselo para responder a través de `session.respondToUserInput()`
`question`	`string`	✅	Pregunta que se va a presentar al usuario
`choices`	`string[]`
Opciones predefinidas para el usuario
`allowFreeform`	`boolean`
Indica si se permite la entrada de texto de forma libre

`user_input.completed`

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

Campo de datos	Tipo	Obligatorio	Descripción
`requestId`	`string`	✅	Coincide con el correspondiente `user_input.requested`

`elicitation.requested`

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

Campo de datos	Tipo	Obligatorio	Descripción
`requestId`	`string`	✅	Usa esto para responder a través de `session.respondToElicitation()`
`message`	`string`	✅	Descripción de la información necesaria
`mode`	`"form"`
Modo de elicitación (actualmente solo `"form"`)
`requestedSchema`	`{ type: "object", properties, required? }`	✅	Esquema JSON que describe los campos de formulario

`elicitation.completed`

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

Campo de datos	Tipo	Obligatorio	Descripción
`requestId`	`string`	✅	Coincide con el correspondiente `elicitation.requested`

Subagente y eventos de habilidades

`subagent.started`

Se invocó un agente personalizado como subagente.

Campo de datos	Tipo	Obligatorio	Descripción
`toolCallId`	`string`	✅	Llamada a la herramienta primaria que generó este subagente
`agentName`	`string`	✅	Nombre interno del subagente
`agentDisplayName`	`string`	✅	Nombre para mostrar legible por el usuario
`agentDescription`	`string`	✅	Descripción de lo que hace el subagente

`subagent.completed`

Un subagente finalizó correctamente.

Campo de datos	Tipo	Obligatorio	Descripción
`toolCallId`	`string`	✅	Corresponde con el correspondiente `subagent.started`
`agentName`	`string`	✅	Nombre interno
`agentDisplayName`	`string`	✅	Nombre para mostrar

`subagent.failed`

Un subagente encontró un error.

Campo de datos	Tipo	Obligatorio	Descripción
`toolCallId`	`string`	✅	Coincide con el elemento correspondiente `subagent.started`
`agentName`	`string`	✅	Nombre interno
`agentDisplayName`	`string`	✅	Nombre para mostrar
`error`	`string`	✅	Mensaje de error

`subagent.selected`

Se seleccionó (inferido) un agente personalizado para gestionar la solicitud actual.

Campo de datos	Tipo	Obligatorio	Descripción
`agentName`	`string`	✅	Nombre interno del agente seleccionado
`agentDisplayName`	`string`	✅	Nombre para mostrar
`tools`	`string[] \| null`	✅	Nombres de herramientas disponibles para este agente; `null` para todas las herramientas

`subagent.deselected`

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

`skill.invoked`

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

Campo de datos	Tipo	Obligatorio	Descripción
`name`	`string`	✅	Nombre de la habilidad
`path`	`string`	✅	Ruta de acceso al archivo de la definición en SKILL.md
`content`	`string`	✅	Contenido completo de habilidades inyectado en la conversación
`allowedTools`	`string[]`
Herramientas aprobadas automáticamente mientras esta habilidad está activa
`pluginName`	`string`
Plugin de la habilidad originada en
`pluginVersion`	`string`
Versión del complemento

Otros eventos

`abort`

Se anuló el turno actual.

Campo de datos	Tipo	Obligatorio	Descripción
`reason`	`string`	✅	¿Por qué se anuló el turno (por ejemplo, `"user initiated"`)

`user.message`

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

Campo de datos	Tipo	Obligatorio	Descripción
`content`	`string`	✅	Texto del mensaje del usuario
`transformedContent`	`string`
Versión transformada después del preprocesamiento
`attachments`	`Attachment[]`
Archivos, directorios, selección, blob o GitHub datos adjuntos de referencia
`source`	`string`
Identificador de origen del mensaje
`agentMode`	`string`
Modo de agente: `"interactive"`, `"plan"`, `"autopilot"`o `"shell"`
`interactionId`	`string`
Identificador de interacción

`system.message`

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

Campo de datos	Tipo	Obligatorio	Descripción
`content`	`string`	✅	Texto del mensaje
`role`	`"system" \| "developer"`	✅	Rol de mensaje
`name`	`string`
Identificador de origen
`metadata`	`{ promptVersion?, variables? }`
Metadatos de plantilla de solicitud

`external_tool.requested`

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

Campo de datos	Tipo	Obligatorio	Descripción
`requestId`	`string`	✅	Usa esto para responder a través de `session.respondToExternalTool()`
`sessionId`	`string`	✅	Sesión a la que pertenece esta solicitud
`toolCallId`	`string`	✅	ID de llamada de herramienta para esta invocación
`toolName`	`string`	✅	Nombre de la herramienta externa
`arguments`	`object`
Argumentos de la herramienta

`external_tool.completed`

Efímero. Se resolvió una solicitud de herramienta externa.

Campo de datos	Tipo	Obligatorio	Descripción
`requestId`	`string`	✅	Coincide con el elemento correspondiente `external_tool.requested`

`exit_plan_mode.requested`

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

Campo de datos	Tipo	Obligatorio	Descripción
`requestId`	`string`	✅	Usa esto para responder a través de `session.respondToExitPlanMode()`
`summary`	`string`	✅	Resumen del plan
`planContent`	`string`	✅	Contenido completo del archivo de plan
`actions`	`string[]`	✅	Acciones de usuario disponibles (por ejemplo, aprobar, editar, rechazar)
`recommendedAction`	`string`	✅	Acción sugerida

`exit_plan_mode.completed`

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

Campo de datos	Tipo	Obligatorio	Descripción
`requestId`	`string`	✅	Coincide con el elemento correspondiente `exit_plan_mode.requested`

`command.queued`

Efímero. Se puso en cola un comando slash para su ejecución.

Campo de datos	Tipo	Obligatorio	Descripción
`requestId`	`string`	✅	Usa esto para responder a través de `session.respondToQueuedCommand()`
`command`	`string`	✅	Texto del comando de barra diagonal (por ejemplo, `/help` y `/clear`)

`command.completed`

Efímero. Se resolvió un comando en cola.

Campo de datos	Tipo	Obligatorio	Descripción
`requestId`	`string`	✅	Coincide con el elemento correspondiente `command.queued`

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 (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 los tipos de eventos de un vistazo

Tipo de evento	Efímero	Categoría	Campos de datos clave
`assistant.turn_start`
Asistente

          `turnId`, `interactionId?` |

¿Quién puede utilizar esta característica?

En este artículo