Guias

Tratando razões de parada

Detecte recusas e outras razões de parada diretamente de mensagens de resultado no Agent SDK

O campo stop_reason em mensagens de resultado informa por que o modelo parou de gerar. Esta é a forma recomendada de detectar recusas, limites de token máximo e outras condições de encerramento (nenhuma análise de stream necessária).

stop_reason está disponível em toda ResultMessage, independentemente de o streaming estar ativado. Você não precisa definir include_partial_messages (Python) ou includePartialMessages (TypeScript).

Lendo stop_reason

O campo stop_reason está presente em mensagens de resultado de sucesso e erro. Verifique-o após iterar pelo fluxo de mensagens:

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())

Razões de parada disponíveis

Razão de parada	Significado
`end_turn`	O modelo terminou de gerar sua resposta normalmente.
`max_tokens`	A resposta atingiu o limite máximo de tokens de saída.
`stop_sequence`	O modelo gerou uma sequência de parada configurada.
`refusal`	O modelo recusou cumprir a solicitação.
`tool_use`	A saída final do modelo foi uma chamada de ferramenta. Isto é incomum em resultados do SDK porque as chamadas de ferramenta são normalmente executadas antes do resultado ser retornado.
`null`	Nenhuma resposta da API foi recebida; por exemplo, um erro ocorreu antes da primeira solicitação, ou o resultado foi reproduzido de uma sessão em cache.

Razões de parada em resultados de erro

Resultados de erro (como error_max_turns ou error_during_execution) também carregam stop_reason. O valor reflete a última mensagem do assistente recebida antes do erro ocorrer:

Variante de resultado	valor de `stop_reason`
`success`	A razão de parada da mensagem final do assistente.
`error_max_turns`	A razão de parada da última mensagem do assistente antes do limite de turnos ser atingido.
`error_max_budget_usd`	A razão de parada da última mensagem do assistente antes do orçamento ser excedido.
`error_max_structured_output_retries`	A razão de parada da última mensagem do assistente antes do limite de tentativas ser atingido.
`error_during_execution`	A última razão de parada vista, ou `null` se o erro ocorreu antes de qualquer resposta da 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())

Detectando recusas

stop_reason === "refusal" é a forma mais simples de detectar quando o modelo recusa uma solicitação. Anteriormente, detectar recusas exigia ativar o streaming de mensagens parciais e verificar manualmente mensagens StreamEvent para eventos message_delta. Com stop_reason na mensagem de resultado, você pode verificar diretamente:

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"))

Próximas etapas

Transmitir respostas em tempo real: acesse eventos brutos da API incluindo message_delta conforme chegam
Saídas estruturadas: obtenha respostas JSON tipadas do agente
Rastreando custos e uso: entenda o uso de tokens e faturamento de mensagens de resultado

Was this page helpful?

Lendo stop_reason

O campo stop_reason está presente em mensagens de resultado de sucesso e erro. Verifique-o após iterar pelo fluxo de mensagens:

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())

Razões de parada disponíveis

Razão de parada	Significado
`end_turn`	O modelo terminou de gerar sua resposta normalmente.
`max_tokens`	A resposta atingiu o limite máximo de tokens de saída.
`stop_sequence`	O modelo gerou uma sequência de parada configurada.
`refusal`	O modelo recusou cumprir a solicitação.
`tool_use`	A saída final do modelo foi uma chamada de ferramenta. Isto é incomum em resultados do SDK porque as chamadas de ferramenta são normalmente executadas antes do resultado ser retornado.
`null`	Nenhuma resposta da API foi recebida; por exemplo, um erro ocorreu antes da primeira solicitação, ou o resultado foi reproduzido de uma sessão em cache.

Razões de parada em resultados de erro

Resultados de erro (como error_max_turns ou error_during_execution) também carregam stop_reason. O valor reflete a última mensagem do assistente recebida antes do erro ocorrer:

Variante de resultado	valor de `stop_reason`
`success`	A razão de parada da mensagem final do assistente.
`error_max_turns`	A razão de parada da última mensagem do assistente antes do limite de turnos ser atingido.
`error_max_budget_usd`	A razão de parada da última mensagem do assistente antes do orçamento ser excedido.
`error_max_structured_output_retries`	A razão de parada da última mensagem do assistente antes do limite de tentativas ser atingido.
`error_during_execution`	A última razão de parada vista, ou `null` se o erro ocorreu antes de qualquer resposta da 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())

Detectando recusas

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"))