指南

處理停止原因

在 Agent SDK 中直接從結果訊息偵測拒絕和其他停止原因

結果訊息上的 stop_reason 欄位告訴您模型為何停止生成。這是偵測拒絕、最大 token 限制和其他終止條件的建議方式（無需解析串流）。

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`	回應達到了最大輸出 token 限制。
`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"))

後續步驟

即時串流回應：存取原始 API 事件，包括即時到達的 message_delta
結構化輸出：從代理取得型別化的 JSON 回應
追蹤成本和用量：從結果訊息了解 token 使用量和計費資訊

Was this page helpful?

讀取 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`	回應達到了最大輸出 token 限制。
`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())

偵測拒絕

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