AssistantMessage completo para cada bloque de contenido no vacío, como un bloque de texto o una llamada de herramienta, después de que Claude termina de generar ese bloque. Para recibir actualizaciones incrementales mientras se generan texto y llamadas de herramientas, habilite la transmisión de mensajes parciales.
Habilitar la transmisión de salida
Para habilitar la transmisión, establezcainclude_partial_messages (Python) o includePartialMessages (TypeScript) en true en sus opciones. Esto hace que el SDK produzca mensajes StreamEvent que contienen eventos de API sin procesar a medida que llegan, además de los AssistantMessage y ResultMessage habituales.
Su código entonces necesita:
- Verificar el tipo de cada mensaje para distinguir
StreamEventde otros tipos de mensaje - Para
StreamEvent, extraer el campoeventy verificar sutype - Buscar eventos
content_block_deltadondedelta.typeseatext_delta, que contienen los fragmentos de texto reales
StreamEvent, luego para content_block_delta, luego para text_delta:
Referencia de StreamEvent
Cuando los mensajes parciales están habilitados, recibe eventos de transmisión sin procesar de la API de Claude envueltos en un objeto. El tipo tiene nombres diferentes en cada SDK:- Python:
StreamEvent(importar desdeclaude_agent_sdk.types) - TypeScript:
SDKPartialAssistantMessagecontype: 'stream_event'
parent_tool_use_id siempre es None en Python y null en TypeScript. Los eventos de transmisión se emiten solo para la sesión principal; los deltas a nivel de token de los subagentes no se reenvían. Para atribuir la salida a un subagente, use mensajes completos, que llevan parent_tool_use_id. Consulte Detectar invocación de subagente.
Claude Code establece user_message_uuid en el primer evento de transmisión que no es ping del turno, y nuevamente cuando cambia el mensaje al que el turno está respondiendo, bajo las condiciones en user_message_uuid. El StreamEvent de Python no expone este campo.
El campo event contiene el evento de transmisión sin procesar de la API de Claude. Los tipos de eventos comunes incluyen:
Flujo de mensajes
Claude Code emite unAssistantMessage a medida que cada bloque de contenido no vacío se completa, por lo que una respuesta con un bloque de texto y una llamada de herramienta produce dos objetos AssistantMessage. Cada uno lleva solo su propio bloque de contenido, y ambos comparten el mismo ID de mensaje, que usted lee como message.message.id en TypeScript y message.message_id en Python. Con mensajes parciales habilitados, cada AssistantMessage llega antes del evento content_block_stop de ese bloque, y usted recibe mensajes en este orden:
StreamEvent. Los tipos comunes incluyen SystemMessage (inicialización de sesión), AssistantMessage (bloques de contenido completos), ResultMessage (resultado final), y un mensaje de límite compacto que indica cuándo se compactó el historial de conversación (SDKCompactBoundaryMessage en TypeScript; SystemMessage con subtipo "compact_boundary" en Python).
Manejar un stream que se corta
Si un stream se corta a mitad de un mensaje, por ejemplo cuando interrumpes el turno o se cae la conexión, igualmente recibes elmessage_stop de ese mensaje antes de que termine el turno. Un bloque de texto o de pensamiento cortado también recibe su content_block_stop. Una llamada a herramienta cortada no lo recibe, así que si message_stop llega mientras el bloque de una llamada a herramienta sigue abierto, trata la entrada de esa llamada como incompleta.
Antes de Claude Code v2.1.290, un stream cortado podía terminar el turno sin message_stop, por lo que una respuesta que renderizas a partir de eventos de stream podía seguir mostrándose como en curso. El Agent SDK de TypeScript incluye Claude Code v2.1.290 o posterior a partir de v0.3.290, y el Agent SDK de Python a partir de v0.2.164. Si una respuesta sigue mostrándose como en curso después de que termina el turno, actualiza el SDK.
Transmitir llamadas de herramientas
Las llamadas de herramientas también se transmiten incrementalmente. Puede rastrear cuándo comienzan las herramientas, recibir su entrada a medida que se genera y ver cuándo se completan. El ejemplo a continuación rastrea la herramienta actual que se está llamando y acumula la entrada JSON a medida que se transmite. Utiliza tres tipos de eventos:content_block_start: la herramienta comienzacontent_block_deltaconinput_json_delta: llegan fragmentos de entradacontent_block_stop: llamada de herramienta completada
Construir una interfaz de usuario de transmisión
Este ejemplo combina la transmisión de texto y herramientas en una interfaz de usuario coherente. Rastrea si el agente está ejecutando actualmente una herramienta (usando una banderain_tool) para mostrar indicadores de estado como [Using Read...] mientras se ejecutan las herramientas. El texto se transmite normalmente cuando no está en una herramienta, y la finalización de la herramienta desencadena un mensaje “done”. Este patrón es útil para interfaces de chat que necesitan mostrar progreso durante tareas de agente de varios pasos.
Limitaciones conocidas
- Structured output: con mensajes parciales habilitados, el JSON se transmite como chunks
input_json_deltano validados de una llamada de herramienta, y solo el resultado validado llega alResultMessage.structured_outputfinal. Consulte structured outputs para obtener detalles.
Próximos pasos
Ahora que puede transmitir texto y llamadas de herramientas en tiempo real, explore estos temas relacionados:- Interactive vs one-shot queries: elija entre modos de entrada para su caso de uso
- Structured outputs: obtenga respuestas JSON tipificadas del agente
- Permissions: controle qué herramientas puede usar el agente