Referencia de Tipos de Eventos de Streaming
Una tabla de consulta densa para cada tipo de evento que la API de Mensajes emite mientras transmite, sus campos y cuándo se activa en el ciclo de vida del evento.
Cómo Usar Esta Lista
- Lee la tabla Ciclo de Vida del Evento de arriba a abajo; es el orden en que los eventos llegan realmente para una respuesta típica.
- Usa la tabla Tipos Delta cuando estés dentro de un manejador de
content_block_deltay necesites saber qué puede serevent.delta.type. - Las tablas Referencia de Campos enumeran cada campo que leerás de cada objeto de evento en el SDK de Python.
- Compara con Cómo los Eventos Enviados por Servidor Potencian las Respuestas de Streaming de Claude para el modelo conceptual detrás de esta tabla.
Ciclo de Vida del Evento
| Orden | Tipo de Evento type | Se Activa | Propósito |
|---|---|---|---|
| 1 | message_start | Una vez, primero | Abre el mensaje; transporta id, model, role y el uso inicial (casi cero) usage. |
| 2 | content_block_start | Una vez por bloque de contenido | Abre un bloque; transporta el type (text, tool_use o thinking) y el index del bloque. |
| 3 | content_block_delta | Muchas veces por bloque | Transporta una parte incremental del contenido de ese bloque; consulta Tipos Delta a continuación. |
| 4 | content_block_stop | Una vez por bloque de contenido | Cierra un bloque; el contenido del bloque está ahora completo para ese index. |
| - | (pasos 2-4 se repiten) | Por bloque adicional | Una respuesta puede contener múltiples bloques (por ejemplo, thinking seguido de text seguido de tool_use) en secuencia. |
| 5 | message_delta | Una vez, cerca del final | Transporta stop_reason, stop_sequence y el usage finalizado (tokens de salida). |
| 6 | message_stop | Una vez, último | Señala que la transmisión está completa; no hay más eventos después. |
| - | ping | En cualquier momento (raro) | Un evento de mantenimiento de conexión sin carga útil; seguro de ignorar. |
| - | error | En cualquier momento | Señala un error a mitad de la transmisión (por ejemplo, un modelo sobrecargado); finaliza la transmisión. |
Tipos Delta (dentro de content_block_delta)
delta.type | Pertenece al tipo de bloque | Campo clave | Significado |
|---|---|---|---|
text_delta | text | delta.text | El siguiente fragmento de prosa generada. |
input_json_delta | tool_use | delta.partial_json | El siguiente fragmento de la cadena de argumentos JSON de una llamada a herramienta. |
thinking_delta | thinking | delta.thinking | El siguiente fragmento de texto de razonamiento de pensamiento extendido. |
signature_delta | thinking | delta.signature | Un fragmento de firma criptográfica para el bloque de pensamiento, enviado cerca de su cierre. |
Referencia de Campos: message_start
| Campo | Tipo | Descripción |
|---|---|---|
message.id | str | Identificador único para este mensaje. |
message.model | str | El modelo que generó la respuesta (por ejemplo, claude-sonnet-5). |
message.role | str | Siempre "assistant" para respuestas de API. |
message.usage.input_tokens | int | Conteo de tokens de entrada, conocido inmediatamente. |
message.usage.output_tokens | int | Casi cero en este punto; finalizado más tarde en message_delta. |
Referencia de Campos: content_block_start / content_block_stop
| Campo | Tipo | Descripción |
|---|---|---|
index | int | A qué bloque de contenido pertenece este evento; la clave para rastrear el estado por bloque. |
content_block.type | str | "text", "tool_use" o "thinking". |
content_block.name | str | Nombre de la herramienta; presente solo cuando type es "tool_use". |
content_block.id | str | El tool_use_id; presente solo cuando type es "tool_use". |
Referencia de Campos: message_delta / message_stop
| Campo | Tipo | Descripción |
|---|---|---|
delta.stop_reason | str | Por qué se detuvo la generación: "end_turn", "max_tokens", "tool_use", "stop_sequence". |
delta.stop_sequence | str | None | La secuencia de parada personalizada que coincidió, si stop_reason es "stop_sequence". |
usage.output_tokens | int | Conteo finalizado de tokens de salida para todo el mensaje. |
| (ninguno) | - | message_stop no transporta ninguna carga útil más allá de type; es una señal pura. |
Patrones de Acceso del SDK de Python
| Quieres | Usa |
|---|---|
| Solo el texto, a medida que llega | for text in stream.text_stream: |
| Cada evento crudo, todos los tipos | for event in stream: |
El Message completo después de la transmisión | stream.get_final_message() después de que la iteración finaliza |
| Equivalentes asíncronos | async for text in stream.text_stream: / async for event in stream: en AsyncAnthropic |
Preguntas Frecuentes
¿Cuál es el primer evento en cada transmisión?
message_start, siempre. Llega antes de que exista cualquier bloque de contenido.
¿Cuál es el último evento en cada transmisión?
message_stop, siempre; es un evento de señal pura sin carga útil propia.
¿Dónde encuentro los recuentos de uso de tokens?
Los tokens de entrada están en message_start.message.usage.input_tokens. Los tokens de salida se finalizan en message_delta.usage.output_tokens.
¿Cómo distingo un bloque de texto de un bloque `tool_use`?
Comprueba content_block.type en el evento content_block_start para el index de ese bloque; es "text", "tool_use" o "thinking".
¿Qué campo leo para los argumentos de herramientas transmitidos?
event.delta.partial_json en eventos content_block_delta donde event.delta.type == "input_json_delta"; acumula estos antes de analizarlos como JSON.
¿Es `ping` algo que necesito manejar?
No, es un mantenimiento de conexión sin carga útil. Seguro de ignorar en un dispatch basado en tipos (simplemente no coincidirá con ninguno de tus casos manejados).
¿Qué me dice `stop_reason`?
Por qué el modelo dejó de generar: "end_turn" (finalización natural), "max_tokens" (alcanzó el límite de tokens), "tool_use" (pausado para llamar a una herramienta) o "stop_sequence" (coincidió con una cadena de parada personalizada).
¿Puede una respuesta contener más de un bloque de contenido?
Sí; por ejemplo, un bloque thinking seguido de un bloque text, o un bloque text seguido de uno o más bloques tool_use, cada uno abierto y cerrado independientemente por index.
¿Para qué sirve `signature_delta`?
Transmite una firma criptográfica asociada con un bloque de pensamiento extendido, utilizada para verificar que el contenido de pensamiento no fue manipulado al ser devuelto en un turno posterior.
¿Significa un evento `error` que toda mi solicitud falló?
Significa que la transmisión terminó anormalmente a mitad de la generación. Trátalo igual que una conexión caída: cualquier contenido que llegó antes está incompleto y la solicitud generalmente debe reintentarse.
¿En qué se diferencia `content_block_delta` de `message_delta`?
content_block_delta transporta contenido incremental dentro de un bloque (fragmentos de texto, JSON o pensamiento). message_delta transporta metadatos a nivel de mensaje (stop_reason, uso final) que solo se conocen una vez que la generación está terminando.
¿Dónde encuentro el nombre del modelo que generó una respuesta?
message_start.message.model; repite el modelo que solicitaste (útil si tu código permite que un alias de modelo se resuelva a una instantánea específica con fecha).
Relacionado
- Cómo los Eventos Enviados por Servidor Potencian las Respuestas de Streaming de Claude - el modelo conceptual detrás de esta tabla.
- Conceptos Básicos de Respuestas de Streaming - ejemplos ejecutables usando estos tipos de eventos.
- Manejo de JSON Parcial Durante Llamadas a Herramientas Transmitidas - uso de
input_json_deltaen la práctica. - Transmisión de Bloques de Pensamiento Extendido al Frontend - uso de
thinking_deltaysignature_delta. - Referencia de Roles y Tipos de Bloques de Contenido de la API de Mensajes - el modelo de bloque de contenido no transmitido al que esto se mapea.
Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5 - y el SDK oficial de Python
anthropic(última versión 0.x). Los nombres de modelos, versiones de SDK y precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.