Guides

Gérer les raisons d'arrêt

Détecter les refus et autres raisons d'arrêt directement à partir des messages de résultat dans le SDK Agent

Le champ stop_reason sur les messages de résultat vous indique pourquoi le modèle a arrêté de générer. C'est la méthode recommandée pour détecter les refus, les limites de jetons maximaux et autres conditions d'arrêt (aucune analyse de flux requise).

stop_reason est disponible sur chaque ResultMessage, que la diffusion en continu soit activée ou non. Vous n'avez pas besoin de définir include_partial_messages (Python) ou includePartialMessages (TypeScript).

Lecture de stop_reason

Le champ stop_reason est présent sur les messages de résultat de succès et d'erreur. Vérifiez-le après avoir parcouru le flux de messages :

from claude_agent_sdk import query, ResultMessage
import asyncio

async def check_stop_reason():
    async for message in query(prompt="Write a poem about the ocean"):
        if isinstance(message, ResultMessage):
            print(f"Stop reason: {message.stop_reason}")
            if message.stop_reason == "refusal":
                print("The model declined this request.")

asyncio.run(check_stop_reason())

Raisons d'arrêt disponibles

Raison d'arrêt	Signification
`end_turn`	Le modèle a terminé la génération de sa réponse normalement.
`max_tokens`	La réponse a atteint la limite maximale de jetons de sortie.
`stop_sequence`	Le modèle a généré une séquence d'arrêt configurée.
`refusal`	Le modèle a refusé de répondre à la demande.
`tool_use`	La sortie finale du modèle était un appel d'outil. C'est rare dans les résultats du SDK car les appels d'outil sont normalement exécutés avant que le résultat soit retourné.
`null`	Aucune réponse API n'a été reçue ; par exemple, une erreur s'est produite avant la première demande, ou le résultat a été relu à partir d'une session en cache.

Raisons d'arrêt sur les résultats d'erreur

Les résultats d'erreur (tels que error_max_turns ou error_during_execution) portent également stop_reason. La valeur reflète le dernier message d'assistant reçu avant que l'erreur ne se produise :

Variante de résultat	valeur `stop_reason`
`success`	La raison d'arrêt du message d'assistant final.
`error_max_turns`	La raison d'arrêt du dernier message d'assistant avant que la limite de tours soit atteinte.
`error_max_budget_usd`	La raison d'arrêt du dernier message d'assistant avant que le budget soit dépassé.
`error_max_structured_output_retries`	La raison d'arrêt du dernier message d'assistant avant que la limite de tentatives soit atteinte.
`error_during_execution`	La dernière raison d'arrêt observée, ou `null` si l'erreur s'est produite avant toute réponse API.

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
import asyncio

async def handle_max_turns():
    options = ClaudeAgentOptions(max_turns=3)

    async for message in query(prompt="Refactor this module", options=options):
        if isinstance(message, ResultMessage):
            if message.subtype == "error_max_turns":
                print(f"Hit turn limit. Last stop reason: {message.stop_reason}")
                # stop_reason might be "end_turn" or "tool_use"
                # depending on what the model was doing when the limit hit

asyncio.run(handle_max_turns())

Détecter les refus

stop_reason === "refusal" est le moyen le plus simple de détecter quand le modèle refuse une demande. Auparavant, la détection des refus nécessitait d'activer la diffusion en continu des messages partiels et de scanner manuellement les messages StreamEvent pour les événements message_delta. Avec stop_reason sur le message de résultat, vous pouvez vérifier directement :

from claude_agent_sdk import query, ResultMessage
import asyncio

async def safe_query(prompt: str):
    async for message in query(prompt=prompt):
        if isinstance(message, ResultMessage):
            if message.stop_reason == "refusal":
                print("Request was declined. Please revise your prompt.")
                return None
            return message.result
    return None

asyncio.run(safe_query("Summarize this article"))

Étapes suivantes

Diffuser les réponses en temps réel : accédez aux événements API bruts, y compris message_delta à mesure qu'ils arrivent
Sorties structurées : obtenez des réponses JSON typées de l'agent
Suivi des coûts et de l'utilisation : comprenez l'utilisation des jetons et la facturation à partir des messages de résultat

Was this page helpful?

Guides

Gérer les raisons d'arrêt

Détecter les refus et autres raisons d'arrêt directement à partir des messages de résultat dans le SDK Agent

Lecture de stop_reason

Le champ stop_reason est présent sur les messages de résultat de succès et d'erreur. Vérifiez-le après avoir parcouru le flux de messages :

from claude_agent_sdk import query, ResultMessage
import asyncio

async def check_stop_reason():
    async for message in query(prompt="Write a poem about the ocean"):
        if isinstance(message, ResultMessage):
            print(f"Stop reason: {message.stop_reason}")
            if message.stop_reason == "refusal":
                print("The model declined this request.")

asyncio.run(check_stop_reason())

Raisons d'arrêt disponibles

Raison d'arrêt	Signification
`end_turn`	Le modèle a terminé la génération de sa réponse normalement.
`max_tokens`	La réponse a atteint la limite maximale de jetons de sortie.
`stop_sequence`	Le modèle a généré une séquence d'arrêt configurée.
`refusal`	Le modèle a refusé de répondre à la demande.
`tool_use`	La sortie finale du modèle était un appel d'outil. C'est rare dans les résultats du SDK car les appels d'outil sont normalement exécutés avant que le résultat soit retourné.
`null`	Aucune réponse API n'a été reçue ; par exemple, une erreur s'est produite avant la première demande, ou le résultat a été relu à partir d'une session en cache.

Raisons d'arrêt sur les résultats d'erreur

Variante de résultat	valeur `stop_reason`
`success`	La raison d'arrêt du message d'assistant final.
`error_max_turns`	La raison d'arrêt du dernier message d'assistant avant que la limite de tours soit atteinte.
`error_max_budget_usd`	La raison d'arrêt du dernier message d'assistant avant que le budget soit dépassé.
`error_max_structured_output_retries`	La raison d'arrêt du dernier message d'assistant avant que la limite de tentatives soit atteinte.
`error_during_execution`	La dernière raison d'arrêt observée, ou `null` si l'erreur s'est produite avant toute réponse API.

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
import asyncio

async def handle_max_turns():
    options = ClaudeAgentOptions(max_turns=3)

    async for message in query(prompt="Refactor this module", options=options):
        if isinstance(message, ResultMessage):
            if message.subtype == "error_max_turns":
                print(f"Hit turn limit. Last stop reason: {message.stop_reason}")
                # stop_reason might be "end_turn" or "tool_use"
                # depending on what the model was doing when the limit hit

asyncio.run(handle_max_turns())

Détecter les refus

from claude_agent_sdk import query, ResultMessage
import asyncio

async def safe_query(prompt: str):
    async for message in query(prompt=prompt):
        if isinstance(message, ResultMessage):
            if message.stop_reason == "refusal":
                print("Request was declined. Please revise your prompt.")
                return None
            return message.result
    return None

asyncio.run(safe_query("Summarize this article"))

Étapes suivantes

Diffuser les réponses en temps réel : accédez aux événements API bruts, y compris message_delta à mesure qu'ils arrivent
Sorties structurées : obtenez des réponses JSON typées de l'agent
Suivi des coûts et de l'utilisation : comprenez l'utilisation des jetons et la facturation à partir des messages de résultat

Was this page helpful?