AssistantMessage complet pour chaque bloc de contenu non vide, tel qu’un bloc de texte ou un appel d’outil, après que Claude ait terminé de générer ce bloc. Pour recevoir des mises à jour incrémentielles à mesure que le texte et les appels d’outils sont générés, activez la diffusion de messages partiels.
Activer la diffusion de sortie
Pour activer la diffusion, définissezinclude_partial_messages (Python) ou includePartialMessages (TypeScript) sur true dans vos options. Cela fait que le SDK produit des messages StreamEvent contenant les événements API bruts à mesure qu’ils arrivent, en plus des AssistantMessage et ResultMessage habituels.
Votre code doit alors :
- Vérifier le type de chaque message pour distinguer
StreamEventdes autres types de messages - Pour
StreamEvent, extraire le champeventet vérifier sontype - Rechercher les événements
content_block_deltaoùdelta.typeesttext_delta, qui contiennent les fragments de texte réels
StreamEvent, puis pour content_block_delta, puis pour text_delta :
Référence StreamEvent
Lorsque les messages partiels sont activés, vous recevez les événements de diffusion bruts de l’API Claude enveloppés dans un objet. Le type a des noms différents dans chaque SDK :- Python :
StreamEvent(importer depuisclaude_agent_sdk.types) - TypeScript :
SDKPartialAssistantMessageavectype: 'stream_event'
parent_tool_use_id est toujours None en Python et null en TypeScript. Les événements de diffusion sont émis pour la session principale uniquement ; les deltas au niveau des tokens des sous-agents ne sont pas transmis. Pour attribuer la sortie à un sous-agent, utilisez les messages complets, qui portent parent_tool_use_id. Voir Détecter l’invocation de sous-agent.
Claude Code définit user_message_uuid sur le premier événement de diffusion non-ping du tour, et à nouveau lorsque le message auquel le tour répond change, selon les conditions dans user_message_uuid. Le StreamEvent Python n’expose pas ce champ.
Le champ event contient l’événement de diffusion brut de l’API Claude. Les types d’événements courants incluent :
Flux des messages
Claude Code émet unAssistantMessage à chaque fois qu’un bloc de contenu non vide se termine, donc une réponse avec un bloc de texte et un appel d’outil produit deux objets AssistantMessage. Chacun ne porte que son propre bloc de contenu, et les deux partagent le même ID de message, que vous lisez comme message.message.id en TypeScript et message.message_id en Python. Avec les messages partiels activés, chaque AssistantMessage arrive avant l’événement content_block_stop de ce bloc, et vous recevez les messages dans cet ordre :
StreamEvent. Les types courants incluent SystemMessage (initialisation de session), AssistantMessage (blocs de contenu complets), ResultMessage (résultat final), et un message de limite compact indiquant quand l’historique de conversation a été compacté (SDKCompactBoundaryMessage en TypeScript ; SystemMessage avec le sous-type "compact_boundary" en Python).
Gérer un flux interrompu
Si un flux est interrompu au milieu d’un message, par exemple lorsque vous interrompez le tour ou que la connexion est coupée, vous recevez tout de même lemessage_stop de ce message avant la fin du tour. Un bloc de texte ou de réflexion interrompu reçoit également son content_block_stop. Ce n’est pas le cas d’un appel d’outil interrompu : si message_stop arrive alors que le bloc d’un appel d’outil est encore ouvert, considérez l’entrée de cet appel comme incomplète.
Avant Claude Code v2.1.290, un flux interrompu pouvait terminer le tour sans message_stop, de sorte qu’une réponse que vous affichez à partir des événements du flux pouvait rester affichée comme en cours. Le SDK Agent TypeScript intègre Claude Code v2.1.290 ou ultérieur à partir de la v0.3.290, et le SDK Agent Python à partir de la v0.2.164. Si une réponse reste affichée comme en cours après la fin du tour, mettez à jour le SDK.
Diffuser les appels d’outils
Les appels d’outils sont également diffusés de manière incrémentielles. Vous pouvez suivre quand les outils commencent, recevoir leur entrée à mesure qu’elle est générée, et voir quand ils se terminent. L’exemple ci-dessous suit l’outil actuellement appelé et accumule l’entrée JSON à mesure qu’elle est diffusée. Il utilise trois types d’événements :content_block_start: l’outil commencecontent_block_deltaavecinput_json_delta: les fragments d’entrée arriventcontent_block_stop: l’appel d’outil est complet
Construire une interface utilisateur de diffusion
Cet exemple combine la diffusion de texte et d’outils dans une interface utilisateur cohésive. Il suit si l’agent exécute actuellement un outil (en utilisant un drapeauin_tool) pour afficher des indicateurs de statut comme [Using Read...] pendant que les outils s’exécutent. Le texte se diffuse normalement quand il n’y a pas d’outil, et la fin de l’outil déclenche un message « done ». Ce modèle est utile pour les interfaces de chat qui doivent afficher la progression pendant les tâches d’agent multi-étapes.
Limitations connues
- Sortie structurée : avec les messages partiels activés, le JSON est diffusé en tant que chunks
input_json_deltanon validés d’un appel d’outil, et seul le résultat validé atteint leResultMessage.structured_outputfinal. Consultez les sorties structurées pour plus de détails.
Étapes suivantes
Maintenant que vous pouvez diffuser le texte et les appels d’outils en temps réel, explorez ces sujets connexes :- Requêtes interactives ou ponctuelles : choisissez entre les modes d’entrée pour votre cas d’usage
- Sorties structurées : obtenez des réponses JSON typées de l’agent
- Permissions : contrôlez les outils que l’agent peut utiliser