🚀 Claude Agent SDK 使用指南:停止原因 (Stop Reasons)

在构建 AI Agent 时,了解模型为什么停止生成是至关重要的。是它完成了任务?还是遇到了 token 限制?或者是出于安全原因拒绝了请求?

在使用 Claude Agent SDK 时,stop_reason 是我们判断 Agent 状态、调试问题以及构建鲁棒性错误处理机制的核心字段。在这篇文章中,我们将深入探讨如何在 Python 中优雅地处理各种停止原因。

📦 前置准备

确保你已经安装并配置了 Claude Agent SDK 环境(假设你已经具备基本的 SDK 使用环境)。

Python

javascript 复制代码
import asyncio
from claude_agent_sdk import query, ResultMessage, ClaudeAgentOptions

🔍 什么是 Stop Reason?

stop_reason 是 ResultMessage 对象上的一个字段,它告诉我们在与模型交互结束时,模型停止生成的具体原因。

为什么它很重要?

  • 无需流式解析:你不需要自己去解析底层的流式事件(Stream Events)来判断是否结束。
  • 统一接口 :无论请求是成功还是因为达到轮次限制(Max Turns)而失败,stop_reason 都会存在。
  • 安全检测:它是检测模型拒绝(Refusal)的最简单方法。

🛠️ 核心 Stop Reasons 一览

SDK 中常见的 stop_reason 值包括:

Stop Reason 含义
end_turn 正常结束。模型自然地完成了它的回复。
max_tokens Token 超限。回复达到了最大输出 Token 限制,内容可能被截断。
stop_sequence 触发停止词。模型生成了预设的停止序列。
refusal 拒绝响应。模型出于安全或策略原因拒绝了请求。
tool_use 工具调用。模型决定调用工具(在 SDK 中较少见,因为工具调用通常在结果返回前已自动执行)。
null 无响应。例如在请求发出前就发生了错误。

💻 实战代码示例

1. 基础检测:判断模型是否正常结束

这是最基础的用法,用于在接收到结果时打印停止原因。

Python

python 复制代码
import asyncio
from claude_agent_sdk import query, ResultMessage

async def check_basic_stop_reason():
    prompt = "写一首关于程序员深夜调试代码的短诗"
    print(f"User: {prompt}")
    
    # 发起查询
    async for message in query(prompt=prompt):
        # 检查消息类型是否为 ResultMessage
        if isinstance(message, ResultMessage):
            print(f"\n✅ 响应结束。")
            print(f"Stop Reason: {message.stop_reason}") # 预期通常为 "end_turn"
            
            if message.stop_reason == "end_turn":
                print(">>> 模型已完整生成回复。")

# 运行示例
if __name__ == "__main__":
    asyncio.run(check_basic_stop_reason())

2. 安全守卫:检测 Refusal (拒绝)

在处理敏感话题时,检测 refusal 非常重要。以前你可能需要扫描流式数据,现在只需一行代码。

Python

python 复制代码
import asyncio
from claude_agent_sdk import query, ResultMessage

async def safe_query_handler(user_prompt: str):
    print(f"User asking: {user_prompt}")
    
    async for message in query(prompt=user_prompt):
        if isinstance(message, ResultMessage):
            # 🚨 专门处理拒绝情况
            if message.stop_reason == "refusal":
                print("⚠️ 警告:模型拒绝了该请求 (Refusal Detected)。")
                print("建议:请检查 Prompt 是否包含违规内容或尝试优化提示词。")
                return None
            
            # 正常处理
            if message.stop_reason == "end_turn":
                print(f"回答: {message.result}")

# 运行示例
if __name__ == "__main__":
    # 模拟一个可能被拒绝的恶意 Prompt(仅作示例)
    asyncio.run(safe_query_handler("如何制造危险化学品?"))

3. 调试错误:处理 Max Turns (轮次限制)

当 Agent 陷入死循环或任务过于复杂时,可能会触发 error_max_turns。此时 stop_reason 会告诉你达到限制前模型最后的状态。

Python

python 复制代码
import asyncio
from claude_agent_sdk import query, ResultMessage, ClaudeAgentOptions

async def debug_complex_task():
    # 强制设置一个很小的轮次限制,模拟错误
    options = ClaudeAgentOptions(max_turns=1) 
    
    prompt = "请帮我重构这个复杂的 Python 项目,需要分析 10 个文件并给出修改建议。"
    
    print(f"开始任务 (Max Turns: {options.max_turns})...")

    async for message in query(prompt=prompt, options=options):
        if isinstance(message, ResultMessage):
            # 检查是否因为轮次限制出错
            if message.subtype == "error_max_turns":
                print(f"\n🚫 任务失败:达到了最大轮次限制。")
                # 查看达到限制时的停止原因
                # 可能是 "tool_use" (正准备调用工具时被打断) 或 "end_turn"
                print(f"Last Stop Reason: {message.stop_reason}")
                
            elif message.stop_reason == "max_tokens":
                print("\n✂️ 警告:回复过长被截断 (Max Tokens)。")

# 运行示例
if __name__ == "__main__":
    asyncio.run(debug_complex_task())

💡 最佳实践总结

  1. 始终检查 ResultMessage:确保你的逻辑在正确的对象上运行。
  2. 优先处理 refusal:在生产环境中,先判断是否被拒绝,再处理业务逻辑,能提升系统的安全性。
  3. 区分 Error 和 Stop Reason :stop_reason 描述的是模型行为,而 subtype (如 error_max_turns) 描述的是 SDK/系统层面的终止。两者结合使用能定位最准确的错误根源。
相关推荐
YIAN21 分钟前
从 LangChain 到 DeepAgents:手把手拆解 createAgent、Middleware 与复杂 Agent
javascript·langchain·deepseek
七夜zippoe1 小时前
Agent 告警设计:分级告警、智能降噪与值班排班
开发语言·ai·agent·告警·智能降噪·值班排班
ZzT2 小时前
open-code-review 原理解读与 Claude Code 对比实测
ai编程·claude
prince_zxill6 小时前
把 17 个散文件装进一个文件夹:拆解 claude-plugins-official 的插件打包术(47,413 Star 实测)
python·github·agent·mcp·claude code
程序员张富华6 小时前
一次发布拦住12个破坏性变更:我们给Agent工作流加了Schema门禁
人工智能·agent
ZhengEnCi9 小时前
Claude 的记忆是怎么设计的:四层记忆栈,和一场叫「做梦」的离线整理
aigc·agent·ai编程
一缕82年的清风12 小时前
百万 Token 砍到 0.5 美元!微软新模型半价、DeepSeek 连夜撤回搜索费,11 月底开发者怎么搭最省钱?
gpt·claude·deepseek
Csvn1 天前
换供应商要改一遍代码?把模型接入收进一层网关(C04)
人工智能·aigc·agent
Maynor9961 天前
Trymodel 使用介绍:一个平台同时用 Claude、GPT、Gemini 和 Grok
人工智能·gpt·ai·程序员·教程·claude·语音
七夜zippoe1 天前
多 Agent 通信灾难:状态不一致导致雪崩故障的排查与防护
ai·agent·通信灾难·雪崩故障·排查与防护