指南

处理停止原因

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