Guide

Gestione dei motivi di arresto

Rileva i rifiuti e altri motivi di arresto direttamente dai messaggi di risultato nell'Agent SDK

Il campo stop_reason sui messaggi di risultato ti dice perché il modello ha smesso di generare. Questo è il modo consigliato per rilevare i rifiuti, i limiti di token massimi e altre condizioni di terminazione (non è richiesta l'analisi del flusso).

stop_reason è disponibile su ogni ResultMessage, indipendentemente dal fatto che lo streaming sia abilitato. Non è necessario impostare include_partial_messages (Python) o includePartialMessages (TypeScript).

Lettura di stop_reason

Il campo stop_reason è presente sia sui messaggi di risultato di successo che su quelli di errore. Controllalo dopo aver iterato attraverso il flusso di messaggi:

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

Motivi di arresto disponibili

Motivo di arresto	Significato
`end_turn`	Il modello ha finito di generare la sua risposta normalmente.
`max_tokens`	La risposta ha raggiunto il limite massimo di token di output.
`stop_sequence`	Il modello ha generato una sequenza di arresto configurata.
`refusal`	Il modello ha rifiutato di soddisfare la richiesta.
`tool_use`	L'output finale del modello era una chiamata a uno strumento. Questo è raro nei risultati dell'SDK perché le chiamate agli strumenti vengono normalmente eseguite prima che il risultato venga restituito.
`null`	Nessuna risposta API è stata ricevuta; ad esempio, si è verificato un errore prima della prima richiesta, oppure il risultato è stato riprodotto da una sessione memorizzata nella cache.

Motivi di arresto sui risultati di errore

I risultati di errore (come error_max_turns o error_during_execution) portano anche stop_reason. Il valore riflette l'ultimo messaggio dell'assistente ricevuto prima che si verificasse l'errore:

Variante di risultato	valore `stop_reason`
`success`	Il motivo di arresto dal messaggio dell'assistente finale.
`error_max_turns`	Il motivo di arresto dall'ultimo messaggio dell'assistente prima che il limite di turni fosse raggiunto.
`error_max_budget_usd`	Il motivo di arresto dall'ultimo messaggio dell'assistente prima che il budget fosse superato.
`error_max_structured_output_retries`	Il motivo di arresto dall'ultimo messaggio dell'assistente prima che il limite di tentativi fosse raggiunto.
`error_during_execution`	L'ultimo motivo di arresto visto, o `null` se l'errore si è verificato prima di qualsiasi risposta 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())

Rilevamento dei rifiuti

stop_reason === "refusal" è il modo più semplice per rilevare quando il modello rifiuta una richiesta. In precedenza, il rilevamento dei rifiuti richiedeva l'abilitazione dello streaming parziale dei messaggi e la scansione manuale dei messaggi StreamEvent per gli eventi message_delta. Con stop_reason sul messaggio di risultato, puoi controllare direttamente:

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

Passaggi successivi

Trasmetti risposte in tempo reale: accedi agli eventi API grezzi incluso message_delta mentre arrivano
Output strutturati: ottieni risposte JSON tipizzate dall'agente
Tracciamento dei costi e dell'utilizzo: comprendi l'utilizzo dei token e la fatturazione dai messaggi di risultato

Was this page helpful?

Guide

Gestione dei motivi di arresto

Rileva i rifiuti e altri motivi di arresto direttamente dai messaggi di risultato nell'Agent SDK

Lettura di stop_reason

Il campo stop_reason è presente sia sui messaggi di risultato di successo che su quelli di errore. Controllalo dopo aver iterato attraverso il flusso di messaggi:

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

Motivi di arresto disponibili

Motivo di arresto	Significato
`end_turn`	Il modello ha finito di generare la sua risposta normalmente.
`max_tokens`	La risposta ha raggiunto il limite massimo di token di output.
`stop_sequence`	Il modello ha generato una sequenza di arresto configurata.
`refusal`	Il modello ha rifiutato di soddisfare la richiesta.
`tool_use`	L'output finale del modello era una chiamata a uno strumento. Questo è raro nei risultati dell'SDK perché le chiamate agli strumenti vengono normalmente eseguite prima che il risultato venga restituito.
`null`	Nessuna risposta API è stata ricevuta; ad esempio, si è verificato un errore prima della prima richiesta, oppure il risultato è stato riprodotto da una sessione memorizzata nella cache.

Motivi di arresto sui risultati di errore

Variante di risultato	valore `stop_reason`
`success`	Il motivo di arresto dal messaggio dell'assistente finale.
`error_max_turns`	Il motivo di arresto dall'ultimo messaggio dell'assistente prima che il limite di turni fosse raggiunto.
`error_max_budget_usd`	Il motivo di arresto dall'ultimo messaggio dell'assistente prima che il budget fosse superato.
`error_max_structured_output_retries`	Il motivo di arresto dall'ultimo messaggio dell'assistente prima che il limite di tentativi fosse raggiunto.
`error_during_execution`	L'ultimo motivo di arresto visto, o `null` se l'errore si è verificato prima di qualsiasi risposta 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())

Rilevamento dei rifiuti

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

Passaggi successivi

Trasmetti risposte in tempo reale: accedi agli eventi API grezzi incluso message_delta mentre arrivano
Output strutturati: ottieni risposte JSON tipizzate dall'agente
Tracciamento dei costi e dell'utilizzo: comprendi l'utilizzo dei token e la fatturazione dai messaggi di risultato

Was this page helpful?