Messages en continu

Lors de la création d'un Message, vous pouvez définir "stream": true pour diffuser la réponse de manière incrémentale en utilisant les événements envoyés par le serveur (SSE).

Streaming avec les SDK

Les SDK Python et TypeScript offrent plusieurs façons de faire du streaming. Le SDK PHP fournit le streaming via createStream(). Le SDK Python permet à la fois les flux synchrones et asynchrones. Consultez la documentation de chaque SDK pour plus de détails.

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    model="claude-opus-4-7",
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Obtenir le message final sans traiter les événements

Si vous n'avez pas besoin de traiter le texte à mesure qu'il arrive, les SDK fournissent un moyen d'utiliser le streaming en arrière-plan tout en retournant l'objet Message complet, identique à ce que .create() retourne. Ceci est particulièrement utile pour les requêtes avec de grandes valeurs max_tokens, où les SDK nécessitent le streaming pour éviter les délais d'expiration HTTP.

L'appel .stream() maintient la connexion HTTP active avec les événements envoyés par le serveur, puis .get_final_message() (Python) ou .finalMessage() (TypeScript) accumule tous les événements et retourne l'objet Message complet. En Go, vous appelez message.Accumulate(event) à l'intérieur de la boucle de streaming pour construire le même Message complet. En Java, utilisez MessageAccumulator.create() et appelez accumulator.accumulate(event) sur chaque événement. En Ruby, appelez .accumulated_message sur le flux. Dans le SDK PHP, vous itérez manuellement sur les événements de flux pour accumuler la réponse.

Types d'événements

Chaque événement envoyé par le serveur inclut un type d'événement nommé et des données JSON associées. Chaque événement utilise un nom d'événement SSE (par exemple event: message_stop), et inclut le type d'événement correspondant dans ses données.

Chaque flux utilise le flux d'événements suivant :

message_start : contient un objet Message avec un content vide.
Une série de blocs de contenu, dont chacun a un événement content_block_start, un ou plusieurs événements content_block_delta, et un événement content_block_stop. Chaque bloc de contenu a un index qui correspond à son index dans le tableau content du Message final.
Un ou plusieurs événements message_delta, indiquant les changements au niveau supérieur de l'objet Message final.
Un événement message_stop final.

Les comptages de jetons affichés dans le champ usage de l'événement message_delta sont cumulatifs.

Événements ping

Les flux d'événements peuvent également inclure un nombre quelconque d'événements ping.

Événements d'erreur

L'API peut occasionnellement envoyer des erreurs dans le flux d'événements. Par exemple, pendant les périodes d'utilisation intensive, vous pouvez recevoir une overloaded_error, qui correspondrait normalement à un HTTP 529 dans un contexte non-streaming :

Exemple d'erreur

event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

Autres événements

Conformément à la politique de versioning, de nouveaux types d'événements peuvent être ajoutés, et votre code doit gérer les types d'événements inconnus avec élégance.

Types de delta de bloc de contenu

Chaque événement content_block_delta contient un delta d'un type qui met à jour le bloc content à un index donné.

Delta de texte

Un delta de bloc de contenu text ressemble à :

Delta de texte

event: content_block_delta
data: {"type": "content_block_delta","index": 0,"delta": {"type": "text_delta", "text": "ello frien"}}

Delta JSON d'entrée

Les deltas pour les blocs de contenu tool_use correspondent aux mises à jour du champ input du bloc. Pour supporter la granularité maximale, les deltas sont des chaînes JSON partielles, tandis que le tool_use.input final est toujours un objet.

Vous pouvez accumuler les deltas de chaîne et analyser le JSON une fois que vous recevez un événement content_block_stop, en utilisant une bibliothèque comme Pydantic pour faire une analyse JSON partielle, ou en utilisant les SDK, qui fournissent des assistants pour accéder aux valeurs incrémentales analysées.

Un delta de bloc de contenu tool_use ressemble à :

Delta JSON d'entrée

event: content_block_delta
data: {"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}

Remarque : Les modèles actuels ne supportent l'émission que d'une seule propriété de clé et de valeur complète de input à la fois. En tant que tel, lors de l'utilisation d'outils, il peut y avoir des délais entre les événements de streaming pendant que le modèle travaille. Une fois qu'une clé et une valeur input sont accumulées, elles sont émises sous forme de plusieurs événements content_block_delta avec du json partiel fragmenté afin que le format puisse automatiquement supporter une granularité plus fine dans les modèles futurs.

Delta de réflexion

Lors de l'utilisation de la réflexion étendue avec le streaming activé, vous recevrez le contenu de réflexion via des événements thinking_delta. Ces deltas correspondent au champ thinking des blocs de contenu thinking.

Pour le contenu de réflexion, un événement signature_delta spécial est envoyé juste avant l'événement content_block_stop. Cette signature est utilisée pour vérifier l'intégrité du bloc de réflexion.

Lorsque display: "omitted" est défini sur la configuration de réflexion, aucun événement thinking_delta n'est envoyé. Le bloc de réflexion s'ouvre, reçoit un seul signature_delta, et se ferme. Voir Contrôle de l'affichage de la réflexion.

Un delta de réflexion typique ressemble à :

Delta de réflexion

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}}

Le delta de signature ressemble à :

Delta de signature

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

Réponse complète du flux HTTP

Utilisez les SDK clients lors de l'utilisation du mode streaming. Cependant, si vous construisez une intégration API directe, vous devez gérer ces événements vous-même.

Une réponse de flux est composée de :

Un événement message_start
Potentiellement plusieurs blocs de contenu, dont chacun contient :
- Un événement content_block_start
- Potentiellement plusieurs événements content_block_delta
- Un événement content_block_stop
Un événement message_delta
Un événement message_stop

Il peut y avoir des événements ping dispersés tout au long de la réponse également. Voir Types d'événements pour plus de détails sur le format.

Requête de streaming basique

Réponse

event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-7", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

event: ping
data: {"type": "ping"}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}

event: message_stop
data: {"type": "message_stop"}

Demande de streaming avec utilisation d'outils

L'utilisation d'outils prend en charge le streaming à granularité fine pour les valeurs de paramètres. Activez-le par outil avec eager_input_streaming.

Cette demande demande à Claude d'utiliser un outil pour signaler la météo.

Response

event: message_start
data: {"type":"message_start","message":{"id":"msg_014p7gG3wDgGV9EUtLvnow3U","type":"message","role":"assistant","model":"claude-opus-4-7","stop_sequence":null,"usage":{"input_tokens":472,"output_tokens":2},"content":[],"stop_reason":null}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: ping
data: {"type": "ping"}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Okay"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":","}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" let"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"'s"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" check"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" the"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" weather"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" for"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" San"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Francisco"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":","}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" CA"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":":"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"tool_use","id":"toolu_01T1x1fJ34qAmk2tNTrN7Up6","name":"get_weather","input":{}}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"location\":"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" \"San"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" Francisc"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"o,"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" CA\""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":","}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" "}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"\"unit\": \"fah"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"renheit\"}"}}

event: content_block_stop
data: {"type":"content_block_stop","index":1}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"tool_use","stop_sequence":null},"usage":{"output_tokens":89}}

event: message_stop
data: {"type":"message_stop"}

Demande de streaming avec réflexion étendue

Cette demande active la réflexion étendue avec streaming pour voir le raisonnement étape par étape de Claude.

Response

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-7", "stop_reason": null, "stop_sequence": null}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": "", "signature": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n462 = 3 × 147 + 21"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n147 = 7 × 21 + 0"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\nThe remainder is 0, so GCD(1071, 462) = 21."}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "The greatest common divisor of 1071 and 462 is **21**."}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 1}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}

event: message_stop
data: {"type": "message_stop"}

Demande de streaming avec utilisation d'outil de recherche web

Cette demande demande à Claude de rechercher sur le web des informations météorologiques actuelles.

Response

event: message_start
data: {"type":"message_start","message":{"id":"msg_01G...","type":"message","role":"assistant","model":"claude-opus-4-7","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":2679,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":3}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"I'll check"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" the current weather in New York City for you"}}

event: ping
data: {"type": "ping"}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"."}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"server_tool_use","id":"srvtoolu_014hJH82Qum7Td6UV8gDXThB","name":"web_search","input":{}}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"query"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"\":"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" \"weather"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" NY"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"C to"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"day\"}"}}

event: content_block_stop
data: {"type":"content_block_stop","index":1 }

event: content_block_start
data: {"type":"content_block_start","index":2,"content_block":{"type":"web_search_tool_result","tool_use_id":"srvtoolu_014hJH82Qum7Td6UV8gDXThB","content":[{"type":"web_search_result","title":"Weather in New York City in May 2025 (New York) - detailed Weather Forecast for a month","url":"https://world-weather.info/forecast/usa/new_york/may-2025/","encrypted_content":"Ev0DCioIAxgCIiQ3NmU4ZmI4OC1k...","page_age":null},...]}}

event: content_block_stop
data: {"type":"content_block_stop","index":2}

event: content_block_start
data: {"type":"content_block_start","index":3,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":"Here's the current weather information for New York"}}

event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":" City:\n\n# Weather"}}

event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":" in New York City"}}

event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":"\n\n"}}

...

event: content_block_stop
data: {"type":"content_block_stop","index":17}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":10682,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":510,"server_tool_use":{"web_search_requests":1}}}

event: message_stop
data: {"type":"message_stop"}

Récupération des erreurs

Claude 4.5 et versions antérieures

Pour les modèles Claude 4.5 et antérieurs, vous pouvez récupérer une demande de streaming qui a été interrompue en raison de problèmes réseau, de délais d'expiration ou d'autres erreurs en reprenant à partir du point d'interruption du flux. Cette approche vous permet d'éviter de retraiter la réponse entière.

La stratégie de récupération de base implique :

Capturer la réponse partielle : Enregistrez tout le contenu qui a été reçu avec succès avant l'erreur
Construire une demande de continuation : Créez une nouvelle demande API qui inclut la réponse partielle de l'assistant comme début d'un nouveau message d'assistant
Reprendre le streaming : Continuez à recevoir le reste de la réponse à partir du point d'interruption

Claude 4.6

Pour les modèles Claude 4.6, vous devez ajouter un message utilisateur qui demande au modèle de continuer à partir du point où il s'est arrêté. Par exemple :

Sample prompt

Your previous response was interrupted and ended with [previous_response]. Continue from where you left off.

Meilleures pratiques de récupération des erreurs

Utiliser les fonctionnalités du SDK : Exploitez les capacités intégrées d'accumulation de messages et de gestion des erreurs du SDK
Gérer les types de contenu : Soyez conscient que les messages peuvent contenir plusieurs blocs de contenu (text, tool_use, thinking). Les blocs d'utilisation d'outils et de réflexion étendue ne peuvent pas être partiellement récupérés. Vous pouvez reprendre le streaming à partir du bloc de texte le plus récent.

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=128000,
    messages=[{"role": "user", "content": "Write a detailed analysis..."}],
    model="claude-opus-4-7",
) as stream:
    message = stream.get_final_message()

print(message.content[0].text)

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-7",
    messages=[{"role": "user", "content": "Hello"}],
    max_tokens=256,
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]

with client.messages.stream(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "any"},
    messages=[
        {"role": "user", "content": "What is the weather like in San Francisco?"}
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-7",
    max_tokens=20000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
) as stream:
    for event in stream:
        if event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
    messages=[
        {"role": "user", "content": "What is the weather like in New York City today?"}
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)