MessagesDévelopper avec Claude

Raisons d'arrêt et repli

Découvrez la signification de chaque valeur stop_reason et comment gérer la troncature, l'utilisation d'outils, les tours mis en pause et les refus dans votre application.

Chaque réponse de l'API Messages inclut un champ stop_reason qui vous indique pourquoi Claude a cessé de générer. Vérifiez ce champ pour décider si vous devez utiliser la réponse telle quelle, poursuivre la conversation, réessayer ou vous replier sur un autre modèle.

Pour le schéma complet de la réponse, consultez la référence de l'API Messages.

Référence rapide

Valeur	Quand cela se produit	Que faire
`end_turn`	Claude a terminé sa réponse naturellement.	Utilisez la réponse.
`max_tokens`	La réponse a atteint votre limite `max_tokens`.	Augmentez `max_tokens` ou poursuivez la réponse.
`stop_sequence`	Claude a émis l'une de vos `stop_sequences`.	Lisez `stop_sequence` pour voir laquelle s'est déclenchée.
`tool_use`	Claude appelle un outil.	Exécutez l'outil et renvoyez le résultat.
`pause_turn`	Une boucle d'outil serveur a atteint sa limite d'itérations.	Renvoyez le contenu de l'assistant pour continuer.
`refusal`	Claude a refusé de répondre.	Lisez `stop_details` et réessayez sur un modèle de repli.
`model_context_window_exceeded`	La réponse a rempli la fenêtre de contexte du modèle.	Traitez la réponse comme tronquée.

Le champ stop_reason

Le champ stop_reason fait partie de chaque réponse réussie de l'API Messages. Contrairement aux erreurs, qui indiquent des échecs dans le traitement de votre requête, stop_reason vous indique pourquoi Claude a terminé la génération de sa réponse.

Example response

{
  "id": "msg_01234",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Here's the answer to your question..."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "stop_details": null,
  "usage": {
    "input_tokens": 100,
    "output_tokens": 50
  }
}

Valeurs de stop_reason

end_turn

La raison d'arrêt la plus courante. Indique que Claude a terminé sa réponse naturellement.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
if response.stop_reason == "end_turn":
    # Traiter la réponse complète
    print(response.content[0].text)

max_tokens

Claude s'est arrêté parce qu'il a atteint la limite max_tokens spécifiée dans votre requête.

client = anthropic.Anthropic()
# Requête avec un nombre limité de tokens
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=10,
    messages=[{"role": "user", "content": "Explain quantum physics"}],
)

if response.stop_reason == "max_tokens":
    # La réponse a été tronquée
    print("Response was cut off at token limit")
    # Envisagez d'effectuer une autre requête pour continuer

stop_sequence

Claude a rencontré l'une de vos séquences d'arrêt personnalisées.

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    stop_sequences=["END", "STOP"],
    messages=[{"role": "user", "content": "Generate text until you say END"}],
)

if response.stop_reason == "stop_sequence":
    print(f"Stopped at sequence: {response.stop_sequence}")

tool_use

Claude appelle un outil et s'attend à ce que vous l'exécutiez.

Pour la plupart des implémentations d'utilisation d'outils, utilisez le tool runner, qui gère automatiquement l'exécution des outils, le formatage des résultats et la gestion de la conversation.

client = anthropic.Anthropic()
weather_tool = {
    "name": "get_weather",
    "description": "Get the current weather in a given location",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {"type": "string", "description": "City and state"},
        },
        "required": ["location"],
    },
}


def execute_tool(name, tool_input):
    """Execute a tool and return the result."""
    return f"Weather in {tool_input.get('location', 'unknown')}: 72°F"


response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
)

if response.stop_reason == "tool_use":
    # Extraire et exécuter l'outil
    for block in response.content:
        if block.type == "tool_use":
            result = execute_tool(block.name, block.input)
            # Renvoyer le résultat à Claude pour la réponse finale

pause_turn

Renvoyé lorsque la boucle d'échantillonnage côté serveur atteint sa limite d'itérations lors de l'exécution d'outils serveur comme la recherche web ou la récupération web. La limite par défaut est de 10 itérations par requête.

Lorsque cela se produit, la réponse peut contenir un bloc server_tool_use sans server_tool_result correspondant. Pour permettre à Claude de terminer le traitement, poursuivez la conversation en renvoyant la réponse telle quelle.

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    messages=[{"role": "user", "content": "Search for latest AI news"}],
)

if response.stop_reason == "pause_turn":
    # Poursuivez la conversation en renvoyant la réponse
    messages = [
        {"role": "user", "content": "Search for latest AI news"},
        {"role": "assistant", "content": response.content},
    ]
    continuation = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=4096,
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search"}],
    )

Votre application doit gérer pause_turn dans toute boucle d'agent qui utilise des outils serveur. Ajoutez la réponse de l'assistant à votre tableau de messages et effectuez une autre requête API pour permettre à Claude de continuer.

refusal

Claude a refusé de générer une réponse. Sur Claude Fable 5, les classificateurs de sécurité renvoient cette raison d'arrêt sous forme de réponse HTTP 200 normale, et non d'erreur.

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "[Unsafe request]"}],
)

if response.stop_reason == "refusal":
    # Claude a refusé de répondre
    print("Claude was unable to process this request")
    # Envisagez de reformuler ou de modifier la requête

Si vous rencontrez fréquemment des raisons d'arrêt refusal lors de l'utilisation de Claude Sonnet 4.5 ou Opus 4.1 (obsolète), vous pouvez essayer de mettre à jour vos appels API pour utiliser Haiku 4.5 (claude-haiku-4-5-20251001), qui a des restrictions d'utilisation différentes. En savoir plus sur la compréhension des filtres de sécurité API de Sonnet 4.5.

Lors d'un refus, l'objet stop_details identifie la catégorie de politique qui l'a déclenché. Les catégories et la forme complète de la réponse de refus sont décrites dans Refus et repli. stop_details est null pour toutes les raisons d'arrêt autres que refusal.

Une requête refusée sur Claude Fable 5 peut généralement être traitée en réessayant sur un autre modèle Claude, et Refus et repli montre comment configurer cette nouvelle tentative, côté serveur ou dans votre client. Crédit de repli explique comment éviter de payer deux fois le coût de la mise en cache des prompts lorsque vous implémentez vous-même la nouvelle tentative.

model_context_window_exceeded

Claude s'est arrêté parce qu'il a atteint la limite de la « context window » (fenêtre de contexte) du modèle. Cela vous permet de demander le maximum de tokens possible sans connaître la taille exacte de l'entrée.

Cette raison d'arrêt n'est actuellement typée que dans l'espace de noms beta des SDK, c'est pourquoi les exemples suivants appellent client.beta.messages et utilisent les types préfixés par Beta. Sur Sonnet 4.5 et les modèles plus récents, l'API renvoie cette valeur sans en-tête bêta. Pour les modèles antérieurs, ajoutez l'en-tête bêta model-context-window-exceeded-2025-08-26 pour l'activer.

# Requête avec le maximum de tokens pour obtenir autant que possible
response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=20000,  # Python SDK requires streaming for max_tokens above ~21k (Opus 4.8 supports 128k with streaming)
    messages=[
        {"role": "user", "content": "Large input that uses most of context window..."}
    ],
)

if response.stop_reason == "model_context_window_exceeded":
    # La réponse a atteint la limite de la fenêtre de contexte avant max_tokens
    print("Response reached model's context window limit")
    # La réponse reste valide mais a été limitée par la fenêtre de contexte

Bonnes pratiques pour gérer les raisons d'arrêt

Toujours vérifier stop_reason

Prenez l'habitude de vérifier stop_reason dans votre logique de traitement des réponses :

def handle_response(response):
    if response.stop_reason == "tool_use":
        return handle_tool_use(response)
    elif response.stop_reason == "max_tokens":
        return handle_truncation(response)
    elif response.stop_reason == "model_context_window_exceeded":
        return handle_context_limit(response)
    elif response.stop_reason == "pause_turn":
        return handle_pause(response)
    elif response.stop_reason == "refusal":
        return handle_refusal(response)
    else:
        # Gérer end_turn et les autres cas
        return response.content[0].text

Gérer les réponses tronquées avec élégance

Lorsqu'une réponse est tronquée en raison des limites de tokens ou de la fenêtre de contexte, ajoutez un avertissement pour que le lecteur sache que la sortie est incomplète. Pour continuer la génération à partir de l'endroit où la réponse s'est arrêtée, consultez Garantir des réponses complètes.

def handle_truncated_response(response):
    if response.stop_reason in ["max_tokens", "model_context_window_exceeded"]:
        if response.stop_reason == "max_tokens":
            note = "[Response truncated due to max_tokens limit]"
        else:
            note = "[Response truncated due to context window limit]"
        return f"{response.content[0].text}\n\n{note}"
    return response.content[0].text

Implémenter une logique de nouvelle tentative pour pause_turn

Lors de l'utilisation d'outils serveur, l'API peut renvoyer pause_turn si la boucle d'échantillonnage côté serveur atteint sa limite d'itérations (10 par défaut). Gérez cela en poursuivant la conversation :

def handle_server_tool_conversation(client, user_query, tools, max_continuations=5):
    """
    Handle server tool conversations that may require multiple continuations.

    The server runs a sampling loop when executing server tools. If the loop
    reaches its iteration limit, the API returns pause_turn. Continue the
    conversation by sending the response back to let Claude finish.
    """
    messages = [{"role": "user", "content": user_query}]

    for _ in range(max_continuations):
        response = client.messages.create(
            model="claude-opus-4-8", max_tokens=4096, messages=messages, tools=tools
        )

        if response.stop_reason != "pause_turn":
            # Claude a terminé le traitement - retourner la réponse finale
            return response

        # pause_turn : remplacer la liste complète des messages pour maintenir l'alternance des rôles
        messages = [
            {"role": "user", "content": user_query},
            {"role": "assistant", "content": response.content},
        ]

    # Nombre maximal de continuations atteint - retourner la dernière réponse
    return response

Raisons d'arrêt vs erreurs

Il est important de distinguer les valeurs stop_reason des erreurs réelles :

Raisons d'arrêt (réponses réussies)

Font partie du corps de la réponse.
Indiquent pourquoi la génération s'est arrêtée normalement.
La réponse contient du contenu valide.

Erreurs (requêtes échouées)

Codes de statut HTTP 4xx ou 5xx.
Indiquent des échecs de traitement de la requête.
La réponse contient les détails de l'erreur.

client = anthropic.Anthropic()

try:
    response = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello!"}],
    )

    # Gérer la réponse réussie avec stop_reason
    if response.stop_reason == "max_tokens":
        print("Response was truncated")

except anthropic.APIStatusError as e:
    # Gérer les erreurs réelles
    if e.status_code == 429:
        print("Rate limit exceeded")
    elif e.status_code == 500:
        print("Server error")

Considérations relatives au streaming

Lors de l'utilisation du streaming, stop_reason est :

null dans l'événement initial message_start.
Fourni dans l'événement message_delta.
Non fourni dans les autres événements.

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
) as stream:
    for event in stream:
        if event.type == "message_delta":
            stop_reason = event.delta.stop_reason
            if stop_reason:
                print(f"Stream ended with: {stop_reason}")

Schémas courants

Gestion des workflows d'utilisation d'outils

Plus simple avec le tool runner : l'exemple suivant montre la gestion manuelle des outils. Pour la plupart des cas d'usage, le tool runner gère automatiquement l'exécution des outils avec beaucoup moins de code.

def complete_tool_workflow(client, user_query, tools):
    messages = [{"role": "user", "content": user_query}]

    while True:
        response = client.messages.create(
            model="claude-opus-4-8", max_tokens=1024, messages=messages, tools=tools
        )

        if response.stop_reason == "tool_use":
            # Exécuter les outils et continuer
            tool_results = execute_tools(response.content)
            messages.append({"role": "assistant", "content": response.content})
            messages.append({"role": "user", "content": tool_results})
        else:
            # Réponse finale
            return response

Garantir des réponses complètes

def get_complete_response(client, prompt, max_attempts=3):
    messages = [{"role": "user", "content": prompt}]
    full_response = ""

    for _ in range(max_attempts):
        response = client.messages.create(
            model="claude-opus-4-8", messages=messages, max_tokens=4096
        )

        full_response += response.content[0].text

        if response.stop_reason != "max_tokens":
            break

        # Continuer là où il s'est arrêté
        messages = [
            {"role": "user", "content": prompt},
            {"role": "assistant", "content": full_response},
            {"role": "user", "content": "Please continue from where you left off."},
        ]

    return full_response

Obtenir le maximum de tokens sans connaître la taille de l'entrée

Avec la raison d'arrêt model_context_window_exceeded, vous pouvez demander le maximum de tokens possible sans calculer la taille de l'entrée :

def get_max_possible_tokens(client, prompt):
    """
    Get as many tokens as possible within the model's context window
    without needing to calculate input token count
    """
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        messages=[{"role": "user", "content": prompt}],
        max_tokens=20000,  # Python SDK requires streaming for max_tokens above ~21k
    )

    if response.stop_reason == "model_context_window_exceeded":
        # Nombre maximal de tokens possible obtenu compte tenu de la taille de l'entrée
        print(
            f"Generated {response.usage.output_tokens} tokens (context limit reached)"
        )
    elif response.stop_reason == "max_tokens":
        # Nombre exact de tokens demandés obtenu
        print(f"Generated {response.usage.output_tokens} tokens (max_tokens reached)")
    else:
        # Complétion naturelle
        print(f"Generated {response.usage.output_tokens} tokens (natural completion)")

    return response.content[0].text

Étapes suivantes

Refus et repli

Réessayez les requêtes refusées sur un modèle de repli, côté serveur ou dans votre client.

Tool Runner (SDK)

Laissez le SDK gérer la boucle tool_use, le formatage des résultats et les nouvelles tentatives pour vous.

Messages en streaming

Lisez stop_reason depuis l'événement message_delta lors du streaming.

Erreurs

Gérez les erreurs HTTP 4xx et 5xx, qui sont distinctes des raisons d'arrêt.

Was this page helpful?

MessagesDévelopper avec Claude

Raisons d'arrêt et repli

Découvrez la signification de chaque valeur stop_reason et comment gérer la troncature, l'utilisation d'outils, les tours mis en pause et les refus dans votre application.

Pour le schéma complet de la réponse, consultez la référence de l'API Messages.

Référence rapide

Valeur	Quand cela se produit	Que faire
`end_turn`	Claude a terminé sa réponse naturellement.	Utilisez la réponse.
`max_tokens`	La réponse a atteint votre limite `max_tokens`.	Augmentez `max_tokens` ou poursuivez la réponse.
`stop_sequence`	Claude a émis l'une de vos `stop_sequences`.	Lisez `stop_sequence` pour voir laquelle s'est déclenchée.
`tool_use`	Claude appelle un outil.	Exécutez l'outil et renvoyez le résultat.
`pause_turn`	Une boucle d'outil serveur a atteint sa limite d'itérations.	Renvoyez le contenu de l'assistant pour continuer.
`refusal`	Claude a refusé de répondre.	Lisez `stop_details` et réessayez sur un modèle de repli.
`model_context_window_exceeded`	La réponse a rempli la fenêtre de contexte du modèle.	Traitez la réponse comme tronquée.

Le champ stop_reason

Example response

{
  "id": "msg_01234",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Here's the answer to your question..."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "stop_details": null,
  "usage": {
    "input_tokens": 100,
    "output_tokens": 50
  }
}

Valeurs de stop_reason

end_turn

La raison d'arrêt la plus courante. Indique que Claude a terminé sa réponse naturellement.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
if response.stop_reason == "end_turn":
    # Traiter la réponse complète
    print(response.content[0].text)

max_tokens

Claude s'est arrêté parce qu'il a atteint la limite max_tokens spécifiée dans votre requête.

client = anthropic.Anthropic()
# Requête avec un nombre limité de tokens
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=10,
    messages=[{"role": "user", "content": "Explain quantum physics"}],
)

if response.stop_reason == "max_tokens":
    # La réponse a été tronquée
    print("Response was cut off at token limit")
    # Envisagez d'effectuer une autre requête pour continuer

stop_sequence

Claude a rencontré l'une de vos séquences d'arrêt personnalisées.

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    stop_sequences=["END", "STOP"],
    messages=[{"role": "user", "content": "Generate text until you say END"}],
)

if response.stop_reason == "stop_sequence":
    print(f"Stopped at sequence: {response.stop_sequence}")

tool_use

Claude appelle un outil et s'attend à ce que vous l'exécutiez.

Pour la plupart des implémentations d'utilisation d'outils, utilisez le tool runner, qui gère automatiquement l'exécution des outils, le formatage des résultats et la gestion de la conversation.

client = anthropic.Anthropic()
weather_tool = {
    "name": "get_weather",
    "description": "Get the current weather in a given location",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {"type": "string", "description": "City and state"},
        },
        "required": ["location"],
    },
}


def execute_tool(name, tool_input):
    """Execute a tool and return the result."""
    return f"Weather in {tool_input.get('location', 'unknown')}: 72°F"


response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
)

if response.stop_reason == "tool_use":
    # Extraire et exécuter l'outil
    for block in response.content:
        if block.type == "tool_use":
            result = execute_tool(block.name, block.input)
            # Renvoyer le résultat à Claude pour la réponse finale

pause_turn

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    messages=[{"role": "user", "content": "Search for latest AI news"}],
)

if response.stop_reason == "pause_turn":
    # Poursuivez la conversation en renvoyant la réponse
    messages = [
        {"role": "user", "content": "Search for latest AI news"},
        {"role": "assistant", "content": response.content},
    ]
    continuation = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=4096,
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search"}],
    )

refusal

Claude a refusé de générer une réponse. Sur Claude Fable 5, les classificateurs de sécurité renvoient cette raison d'arrêt sous forme de réponse HTTP 200 normale, et non d'erreur.

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "[Unsafe request]"}],
)

if response.stop_reason == "refusal":
    # Claude a refusé de répondre
    print("Claude was unable to process this request")
    # Envisagez de reformuler ou de modifier la requête

model_context_window_exceeded

# Requête avec le maximum de tokens pour obtenir autant que possible
response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=20000,  # Python SDK requires streaming for max_tokens above ~21k (Opus 4.8 supports 128k with streaming)
    messages=[
        {"role": "user", "content": "Large input that uses most of context window..."}
    ],
)

if response.stop_reason == "model_context_window_exceeded":
    # La réponse a atteint la limite de la fenêtre de contexte avant max_tokens
    print("Response reached model's context window limit")
    # La réponse reste valide mais a été limitée par la fenêtre de contexte

Bonnes pratiques pour gérer les raisons d'arrêt

Toujours vérifier stop_reason

Prenez l'habitude de vérifier stop_reason dans votre logique de traitement des réponses :

def handle_response(response):
    if response.stop_reason == "tool_use":
        return handle_tool_use(response)
    elif response.stop_reason == "max_tokens":
        return handle_truncation(response)
    elif response.stop_reason == "model_context_window_exceeded":
        return handle_context_limit(response)
    elif response.stop_reason == "pause_turn":
        return handle_pause(response)
    elif response.stop_reason == "refusal":
        return handle_refusal(response)
    else:
        # Gérer end_turn et les autres cas
        return response.content[0].text

Gérer les réponses tronquées avec élégance

def handle_truncated_response(response):
    if response.stop_reason in ["max_tokens", "model_context_window_exceeded"]:
        if response.stop_reason == "max_tokens":
            note = "[Response truncated due to max_tokens limit]"
        else:
            note = "[Response truncated due to context window limit]"
        return f"{response.content[0].text}\n\n{note}"
    return response.content[0].text

Implémenter une logique de nouvelle tentative pour pause_turn

def handle_server_tool_conversation(client, user_query, tools, max_continuations=5):
    """
    Handle server tool conversations that may require multiple continuations.

    The server runs a sampling loop when executing server tools. If the loop
    reaches its iteration limit, the API returns pause_turn. Continue the
    conversation by sending the response back to let Claude finish.
    """
    messages = [{"role": "user", "content": user_query}]

    for _ in range(max_continuations):
        response = client.messages.create(
            model="claude-opus-4-8", max_tokens=4096, messages=messages, tools=tools
        )

        if response.stop_reason != "pause_turn":
            # Claude a terminé le traitement - retourner la réponse finale
            return response

        # pause_turn : remplacer la liste complète des messages pour maintenir l'alternance des rôles
        messages = [
            {"role": "user", "content": user_query},
            {"role": "assistant", "content": response.content},
        ]

    # Nombre maximal de continuations atteint - retourner la dernière réponse
    return response

Raisons d'arrêt vs erreurs

Il est important de distinguer les valeurs stop_reason des erreurs réelles :

Raisons d'arrêt (réponses réussies)

Font partie du corps de la réponse.
Indiquent pourquoi la génération s'est arrêtée normalement.
La réponse contient du contenu valide.

Erreurs (requêtes échouées)

Codes de statut HTTP 4xx ou 5xx.
Indiquent des échecs de traitement de la requête.
La réponse contient les détails de l'erreur.

client = anthropic.Anthropic()

try:
    response = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello!"}],
    )

    # Gérer la réponse réussie avec stop_reason
    if response.stop_reason == "max_tokens":
        print("Response was truncated")

except anthropic.APIStatusError as e:
    # Gérer les erreurs réelles
    if e.status_code == 429:
        print("Rate limit exceeded")
    elif e.status_code == 500:
        print("Server error")

Considérations relatives au streaming

Lors de l'utilisation du streaming, stop_reason est :

null dans l'événement initial message_start.
Fourni dans l'événement message_delta.
Non fourni dans les autres événements.

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
) as stream:
    for event in stream:
        if event.type == "message_delta":
            stop_reason = event.delta.stop_reason
            if stop_reason:
                print(f"Stream ended with: {stop_reason}")

Schémas courants

Gestion des workflows d'utilisation d'outils

def complete_tool_workflow(client, user_query, tools):
    messages = [{"role": "user", "content": user_query}]

    while True:
        response = client.messages.create(
            model="claude-opus-4-8", max_tokens=1024, messages=messages, tools=tools
        )

        if response.stop_reason == "tool_use":
            # Exécuter les outils et continuer
            tool_results = execute_tools(response.content)
            messages.append({"role": "assistant", "content": response.content})
            messages.append({"role": "user", "content": tool_results})
        else:
            # Réponse finale
            return response

Garantir des réponses complètes

def get_complete_response(client, prompt, max_attempts=3):
    messages = [{"role": "user", "content": prompt}]
    full_response = ""

    for _ in range(max_attempts):
        response = client.messages.create(
            model="claude-opus-4-8", messages=messages, max_tokens=4096
        )

        full_response += response.content[0].text

        if response.stop_reason != "max_tokens":
            break

        # Continuer là où il s'est arrêté
        messages = [
            {"role": "user", "content": prompt},
            {"role": "assistant", "content": full_response},
            {"role": "user", "content": "Please continue from where you left off."},
        ]

    return full_response

Obtenir le maximum de tokens sans connaître la taille de l'entrée

Avec la raison d'arrêt model_context_window_exceeded, vous pouvez demander le maximum de tokens possible sans calculer la taille de l'entrée :

def get_max_possible_tokens(client, prompt):
    """
    Get as many tokens as possible within the model's context window
    without needing to calculate input token count
    """
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        messages=[{"role": "user", "content": prompt}],
        max_tokens=20000,  # Python SDK requires streaming for max_tokens above ~21k
    )

    if response.stop_reason == "model_context_window_exceeded":
        # Nombre maximal de tokens possible obtenu compte tenu de la taille de l'entrée
        print(
            f"Generated {response.usage.output_tokens} tokens (context limit reached)"
        )
    elif response.stop_reason == "max_tokens":
        # Nombre exact de tokens demandés obtenu
        print(f"Generated {response.usage.output_tokens} tokens (max_tokens reached)")
    else:
        # Complétion naturelle
        print(f"Generated {response.usage.output_tokens} tokens (natural completion)")

    return response.content[0].text

Étapes suivantes

Refus et repli

Réessayez les requêtes refusées sur un modèle de repli, côté serveur ou dans votre client.

Tool Runner (SDK)

Laissez le SDK gérer la boucle tool_use, le formatage des résultats et les nouvelles tentatives pour vous.

Messages en streaming

Lisez stop_reason depuis l'événement message_delta lors du streaming.

Erreurs

Gérez les erreurs HTTP 4xx et 5xx, qui sont distinctes des raisons d'arrêt.

Was this page helpful?

Référence rapide

Le champ stop_reason

Valeurs de stop_reason

end_turn

Réponses vides avec end_turn

max_tokens

Blocs tool_use incomplets

stop_sequence

tool_use

pause_turn

refusal

model_context_window_exceeded

Bonnes pratiques pour gérer les raisons d'arrêt

Toujours vérifier stop_reason

Gérer les réponses tronquées avec élégance

Implémenter une logique de nouvelle tentative pour pause_turn

Raisons d'arrêt vs erreurs

Raisons d'arrêt (réponses réussies)

Erreurs (requêtes échouées)

Considérations relatives au streaming

Schémas courants

Gestion des workflows d'utilisation d'outils

Garantir des réponses complètes

Obtenir le maximum de tokens sans connaître la taille de l'entrée

Étapes suivantes

Référence rapide

Le champ stop_reason

Valeurs de stop_reason

end_turn

Réponses vides avec end_turn

max_tokens

Blocs tool_use incomplets

stop_sequence

tool_use

pause_turn

refusal

model_context_window_exceeded

Bonnes pratiques pour gérer les raisons d'arrêt

Toujours vérifier stop_reason

Gérer les réponses tronquées avec élégance

Implémenter une logique de nouvelle tentative pour pause_turn

Raisons d'arrêt vs erreurs

Raisons d'arrêt (réponses réussies)

Erreurs (requêtes échouées)

Considérations relatives au streaming

Schémas courants

Gestion des workflows d'utilisation d'outils

Garantir des réponses complètes

Obtenir le maximum de tokens sans connaître la taille de l'entrée

Étapes suivantes

Référence rapide

Le champ stop_reason

Valeurs de stop_reason

end_turn

max_tokens

stop_sequence

tool_use

pause_turn

refusal

model_context_window_exceeded

Bonnes pratiques pour gérer les raisons d'arrêt

Toujours vérifier stop_reason

Gérer les réponses tronquées avec élégance

Implémenter une logique de nouvelle tentative pour pause_turn

Raisons d'arrêt vs erreurs

Raisons d'arrêt (réponses réussies)

Erreurs (requêtes échouées)

Considérations relatives au streaming

Schémas courants

Gestion des workflows d'utilisation d'outils

Garantir des réponses complètes

Obtenir le maximum de tokens sans connaître la taille de l'entrée

Étapes suivantes

Référence rapide

Le champ stop_reason

Valeurs de stop_reason

end_turn

max_tokens

stop_sequence

tool_use

pause_turn

refusal

model_context_window_exceeded

Bonnes pratiques pour gérer les raisons d'arrêt

Toujours vérifier stop_reason

Gérer les réponses tronquées avec élégance

Implémenter une logique de nouvelle tentative pour pause_turn

Raisons d'arrêt vs erreurs

Raisons d'arrêt (réponses réussies)

Erreurs (requêtes échouées)

Considérations relatives au streaming

Schémas courants

Gestion des workflows d'utilisation d'outils

Garantir des réponses complètes

Obtenir le maximum de tokens sans connaître la taille de l'entrée

Étapes suivantes