Leitfäden

Behandlung von Stop-Gründen

Erkennen Sie Ablehnungen und andere Stop-Gründe direkt aus Ergebnismeldungen im Agent SDK

Das Feld stop_reason in Ergebnismeldungen teilt Ihnen mit, warum das Modell die Generierung beendet hat. Dies ist die empfohlene Methode, um Ablehnungen, Maximale-Token-Limits und andere Beendigungsbedingungen zu erkennen (kein Stream-Parsing erforderlich).

stop_reason ist auf jeder ResultMessage verfügbar, unabhängig davon, ob Streaming aktiviert ist. Sie müssen include_partial_messages (Python) oder includePartialMessages (TypeScript) nicht festlegen.

Reading stop_reason

Das Feld stop_reason ist sowohl auf erfolgreichen als auch auf fehlerhaften Ergebnismeldungen vorhanden. Überprüfen Sie es nach dem Durchlaufen des Nachrichtenstroms:

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

Verfügbare Stop-Gründe

Stop-Grund	Bedeutung
`end_turn`	Das Modell hat seine Antwort normal beendet.
`max_tokens`	Die Antwort hat das maximale Ausgabe-Token-Limit erreicht.
`stop_sequence`	Das Modell hat eine konfigurierte Stop-Sequenz generiert.
`refusal`	Das Modell hat sich geweigert, die Anfrage zu erfüllen.
`tool_use`	Die endgültige Ausgabe des Modells war ein Werkzeugaufruf. Dies ist in SDK-Ergebnissen ungewöhnlich, da Werkzeugaufrufe normalerweise ausgeführt werden, bevor das Ergebnis zurückgegeben wird.
`null`	Es wurde keine API-Antwort empfangen; beispielsweise ist ein Fehler aufgetreten, bevor die erste Anfrage gestellt wurde, oder das Ergebnis wurde aus einer zwischengespeicherten Sitzung wiedergegeben.

Stop-Gründe bei Fehlerergebnissen

Fehlerergebnisse (wie error_max_turns oder error_during_execution) enthalten auch stop_reason. Der Wert spiegelt die letzte Assistenzmeldung wider, die vor dem Fehler empfangen wurde:

Ergebnisvariante	`stop_reason` Wert
`success`	Der Stop-Grund aus der endgültigen Assistenzmeldung.
`error_max_turns`	Der Stop-Grund aus der letzten Assistenzmeldung, bevor das Turnus-Limit erreicht wurde.
`error_max_budget_usd`	Der Stop-Grund aus der letzten Assistenzmeldung, bevor das Budget überschritten wurde.
`error_max_structured_output_retries`	Der Stop-Grund aus der letzten Assistenzmeldung, bevor das Wiederholungslimit erreicht wurde.
`error_during_execution`	Der zuletzt angetroffene Stop-Grund oder `null`, wenn der Fehler vor einer API-Antwort aufgetreten ist.

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

Ablehnungen erkennen

stop_reason === "refusal" ist die einfachste Methode, um zu erkennen, wenn das Modell eine Anfrage ablehnt. Zuvor erforderte das Erkennen von Ablehnungen das Aktivieren von Partial-Message-Streaming und das manuelle Scannen von StreamEvent-Meldungen auf message_delta-Ereignisse. Mit stop_reason in der Ergebnismeldung können Sie direkt überprüfen:

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

Nächste Schritte

Antworten in Echtzeit streamen: Greifen Sie auf rohe API-Ereignisse einschließlich message_delta zu, während sie ankommen
Strukturierte Ausgaben: Erhalten Sie typisierte JSON-Antworten vom Agent
Kosten und Nutzung verfolgen: Verstehen Sie die Token-Nutzung und Abrechnung aus Ergebnismeldungen

Was this page helpful?

Leitfäden

Behandlung von Stop-Gründen

Erkennen Sie Ablehnungen und andere Stop-Gründe direkt aus Ergebnismeldungen im Agent SDK

Reading stop_reason

Das Feld stop_reason ist sowohl auf erfolgreichen als auch auf fehlerhaften Ergebnismeldungen vorhanden. Überprüfen Sie es nach dem Durchlaufen des Nachrichtenstroms:

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

Verfügbare Stop-Gründe

Stop-Grund	Bedeutung
`end_turn`	Das Modell hat seine Antwort normal beendet.
`max_tokens`	Die Antwort hat das maximale Ausgabe-Token-Limit erreicht.
`stop_sequence`	Das Modell hat eine konfigurierte Stop-Sequenz generiert.
`refusal`	Das Modell hat sich geweigert, die Anfrage zu erfüllen.
`tool_use`	Die endgültige Ausgabe des Modells war ein Werkzeugaufruf. Dies ist in SDK-Ergebnissen ungewöhnlich, da Werkzeugaufrufe normalerweise ausgeführt werden, bevor das Ergebnis zurückgegeben wird.
`null`	Es wurde keine API-Antwort empfangen; beispielsweise ist ein Fehler aufgetreten, bevor die erste Anfrage gestellt wurde, oder das Ergebnis wurde aus einer zwischengespeicherten Sitzung wiedergegeben.

Stop-Gründe bei Fehlerergebnissen

Fehlerergebnisse (wie error_max_turns oder error_during_execution) enthalten auch stop_reason. Der Wert spiegelt die letzte Assistenzmeldung wider, die vor dem Fehler empfangen wurde:

Ergebnisvariante	`stop_reason` Wert
`success`	Der Stop-Grund aus der endgültigen Assistenzmeldung.
`error_max_turns`	Der Stop-Grund aus der letzten Assistenzmeldung, bevor das Turnus-Limit erreicht wurde.
`error_max_budget_usd`	Der Stop-Grund aus der letzten Assistenzmeldung, bevor das Budget überschritten wurde.
`error_max_structured_output_retries`	Der Stop-Grund aus der letzten Assistenzmeldung, bevor das Wiederholungslimit erreicht wurde.
`error_during_execution`	Der zuletzt angetroffene Stop-Grund oder `null`, wenn der Fehler vor einer API-Antwort aufgetreten ist.

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

Ablehnungen erkennen

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

Nächste Schritte

Antworten in Echtzeit streamen: Greifen Sie auf rohe API-Ereignisse einschließlich message_delta zu, während sie ankommen
Strukturierte Ausgaben: Erhalten Sie typisierte JSON-Antworten vom Agent
Kosten und Nutzung verfolgen: Verstehen Sie die Token-Nutzung und Abrechnung aus Ergebnismeldungen

Was this page helpful?