ガイド

停止理由の処理

Agent SDKの結果メッセージから拒否やその他の停止理由を直接検出する

結果メッセージのstop_reasonフィールドは、モデルが生成を停止した理由を示します。これは、拒否、最大トークン制限、その他の終了条件を検出するための推奨方法です（ストリーム解析は不要です）。

stop_reasonは、ストリーミングが有効かどうかに関係なく、すべてのResultMessageで利用可能です。include_partial_messages（Python）やincludePartialMessages（TypeScript）を設定する必要はありません。

stop_reasonの読み取り

stop_reasonフィールドは、成功とエラーの両方の結果メッセージに存在します。メッセージストリームを反復処理した後に確認してください：

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

利用可能な停止理由

停止理由	意味
`end_turn`	モデルは正常にレスポンスの生成を完了しました。
`max_tokens`	レスポンスが最大出力トークン制限に達しました。
`stop_sequence`	モデルが設定されたストップシーケンスを生成しました。
`refusal`	モデルがリクエストの実行を拒否しました。
`tool_use`	モデルの最終出力がツール呼び出しでした。ツール呼び出しは通常、結果が返される前に実行されるため、SDKの結果ではこれは一般的ではありません。
`null`	APIレスポンスが受信されませんでした。例えば、最初のリクエストの前にエラーが発生した場合や、結果がキャッシュされたセッションから再生された場合です。

エラー結果の停止理由

エラー結果（error_max_turnsやerror_during_executionなど）にもstop_reasonが含まれます。値は、エラーが発生する前に受信された最後のアシスタントメッセージを反映します：

結果バリアント	`stop_reason`の値
`success`	最終アシスタントメッセージの停止理由。
`error_max_turns`	ターン制限に達する前の最後のアシスタントメッセージの停止理由。
`error_max_budget_usd`	予算を超過する前の最後のアシスタントメッセージの停止理由。
`error_max_structured_output_retries`	リトライ制限に達する前の最後のアシスタントメッセージの停止理由。
`error_during_execution`	最後に確認された停止理由、またはAPIレスポンスの前にエラーが発生した場合は`null`。

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

拒否の検出

stop_reason === "refusal"は、モデルがリクエストを拒否したことを検出する最も簡単な方法です。以前は、拒否を検出するには部分メッセージストリーミングを有効にし、StreamEventメッセージを手動でスキャンしてmessage_deltaイベントを探す必要がありました。結果メッセージのstop_reasonを使用すれば、直接確認できます：

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

次のステップ

リアルタイムでレスポンスをストリーミング：message_deltaを含む生のAPIイベントに到着時にアクセス
構造化出力：エージェントから型付きJSONレスポンスを取得
コストと使用量の追跡：結果メッセージからトークン使用量と課金を把握

Was this page helpful?

ガイド

停止理由の処理

Agent SDKの結果メッセージから拒否やその他の停止理由を直接検出する

stop_reasonの読み取り

stop_reasonフィールドは、成功とエラーの両方の結果メッセージに存在します。メッセージストリームを反復処理した後に確認してください：

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

利用可能な停止理由

停止理由	意味
`end_turn`	モデルは正常にレスポンスの生成を完了しました。
`max_tokens`	レスポンスが最大出力トークン制限に達しました。
`stop_sequence`	モデルが設定されたストップシーケンスを生成しました。
`refusal`	モデルがリクエストの実行を拒否しました。
`tool_use`	モデルの最終出力がツール呼び出しでした。ツール呼び出しは通常、結果が返される前に実行されるため、SDKの結果ではこれは一般的ではありません。
`null`	APIレスポンスが受信されませんでした。例えば、最初のリクエストの前にエラーが発生した場合や、結果がキャッシュされたセッションから再生された場合です。

エラー結果の停止理由

結果バリアント	`stop_reason`の値
`success`	最終アシスタントメッセージの停止理由。
`error_max_turns`	ターン制限に達する前の最後のアシスタントメッセージの停止理由。
`error_max_budget_usd`	予算を超過する前の最後のアシスタントメッセージの停止理由。
`error_max_structured_output_retries`	リトライ制限に達する前の最後のアシスタントメッセージの停止理由。
`error_during_execution`	最後に確認された停止理由、またはAPIレスポンスの前にエラーが発生した場合は`null`。

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

拒否の検出

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

次のステップ

リアルタイムでレスポンスをストリーミング：message_deltaを含む生のAPIイベントに到着時にアクセス
構造化出力：エージェントから型付きJSONレスポンスを取得
コストと使用量の追跡：結果メッセージからトークン使用量と課金を把握

Was this page helpful?