Claude Agent SDK 实战：从零构建带日志调试的 AI Agent

Claude Code 的 Agent SDK（原 Claude Code SDK）正在成为开发者构建 AI Agent 的重要工具。B站 UP 主 Andrew 的这期实操教程，完整演示了从环境搭建到工具调用、停止原因观察，再到日志库封装的开发闭环。与其说这是一篇教程复述，不如说它揭示了一个真实问题：当 AI 生成代码偏离预期时，开发者如何通过配置与日志把 Agent 拉回正轨。

环境准备：Claude Code 与 Agent SDK 的安装要点

Andrew 在 WSL2 环境下演示了整个流程。安装 Claude Code 时，他明确推荐使用原生安装方式（native install），而非 Homebrew 或 Winget。原因很实际：原生安装直接编译自源码，版本最新；而发布版渠道的包往往滞后，容易引发奇怪的 API 兼容问题。

安装完成后，通过 claude --version 确认版本（演示时为 2.1），再执行 claude auth status 检查登录状态。认证环节通过订阅授权完成，这也是目前学习成本最低的接入方式。

Agent SDK 的安装命令为 pip install claude-agent-sdk。这里有个容易被忽视的细节：SDK 已经从 Claude Code SDK 重命名为 Claude Agent SDK，旧文档中的包名和引用方式可能造成混淆，开发时务必以官方最新文档为准。

第一个 Agent：工具调用与停止原因观察

教程的目标很聚焦：用一个天气查询工具调用，展示 Agent SDK 中**停止原因（stop reason）**的运作机制——包括工具调用的停止原因、最终结果的停止原因，以及结果如何链式拼接。

初始版本的 AI 生成代码暴露了几个典型问题：

• 使用了固定的模拟天气数据，而不是真实 API 端点
• 把工具塞进了一个 MCP 服务器，增加了不必要的复杂度
• 程序试图“解释”自己的工作原理，而不是输出可供观察的关键内容

Andrew 的反馈方式值得学习：他没有直接手写代码，而是明确指出问题并让 Claude 修改——要求使用真实 API 端点、去掉多余的 MCP 封装、只输出关键日志。这其实是一种提示工程实践：把模糊需求转化为具体约束。

调试过程中还遇到一个 Python 特有的坑：代码包含 async 内容，必须在异步环境中运行，普通的同步脚本执行会失败。这提醒开发者，Agent SDK 的调用模型天然是异步的。

停止原因（stop reason） 是 LLM Agent 循环中的核心控制信号，它告诉调用方本次模型响应为何结束，常见取值包括 end_turn（模型自然结束）、tool_use（模型请求调用工具）、max_tokens（达到输出长度上限）等。在 Agent SDK 中，一次完整的天气查询往往经历多轮循环：模型先返回 tool_use 停止原因，SDK 执行工具并把结果回传给模型，模型再返回 end_turn 与最终答案。理解停止原因的意义在于，开发者可以据此判断 Agent 是正常完成、需要继续执行工具，还是因长度或异常而中断，从而在日志中准确定位问题环节。

MCP（Model Context Protocol） 是 Anthropic 提出的开放协议，用于让模型以标准化方式连接外部工具与数据源。MCP 服务器适合在多个 Agent 或客户端之间复用同一套工具能力，但它引入了额外的进程启动、传输层配置和生命周期管理成本。对于教程中“调用一个天气 API”这样单一、内聚的需求，直接用 SDK 提供的工具定义（如函数装饰器）注册即可，无需启动独立 MCP 服务器。Andrew 要求去掉 MCP 封装，正是基于“最小化复杂度”的工程判断：工具数量少、复用范围窄时，MCP 带来的抽象收益不足以抵消其调试负担。

从混乱到可用：封装日志解析库

原始输出是一堆难以阅读的 Python 对象字符串。Andrew 的做法是让 Claude 在项目顶层创建一个 lib 目录，封装一个 SDK 解析器（formatter），把原始输出格式化为人类可读的消息，并附上 README 说明如何在不同项目中导入使用。

这一步的价值不止于美化输出。结构化的日志是后续调试 Agent 行为的基础。他进一步要求解析器支持将日志导出到项目相对路径下的 log 目录，每次运行生成带 ISO8601 时间戳的新日志文件。

Agent SDK 的原始输出通常是嵌套的 Python 对象（消息、内容块、工具调用记录等），直接打印会得到难以阅读的字符串表示。SDK 解析器（formatter） 的作用是按消息类型分派格式化逻辑：把助手文本、工具调用参数、工具返回结果分别抽取为结构化字段，再序列化为 JSON 或可读文本。这样做的好处是日志具备稳定的 schema，既方便人工阅读，也便于后续用脚本过滤、统计或把日志片段直接回灌给模型分析。封装成项目内可导入的 lib 模块，则让同一套解析逻辑在多个 Agent 项目间复用，避免每次重写。

用日志反向调试 Agent 行为

教程最有说服力的部分是一个真实的调试场景：Agent 声称修改了目标文件，但终端里看不到任何变化。Andrew 把日志喂回给 Claude，让它基于日志分析问题。

日志显示编辑实际已成功，文件也确实包含修改内容——问题很可能只是 VS Code 的缓存显示延迟。但这个过程本身确立了工作流：Agent 行为异常时，日志是第一手证据，把它反馈给模型往往比人工猜测更高效。

ISO8601 时间戳（如 2025-01-15T10:30:00Z）是国际标准的日期时间表示法，包含日期、时间与时区信息，可按字典序直接排序。日志文件名带上 ISO8601 时间戳，能保证多次运行产生的日志按时间自然排序、互不覆盖，也便于跨机器比对。相比本地化的时间格式，ISO8601 避免了时区歧义和格式解析问题，是 Agent 调试日志命名与内容标注的推荐做法。

实践建议与局限

几个可直接复用的经验：

1. 保持信息最新：Anthropic 频繁调整 SDK 命名与接口，遇到疑惑先查官方 API 参考和开发者指南，别完全信任模型生成的包名。
2. 最小化复杂度：展示工具调用不需要 MCP 服务器，一个简单的函数装饰器加真实 API 就够了。
3. 规划先行：在写代码前让 Claude 生成计划（Plan），审查计划比审查代码成本更低。
4. 日志即调试接口：为 Agent 输出设计时间戳和结构化日志，是长期维护的关键投入。

需要说明的是，本教程聚焦入门级实现，未涉及生产环境的密钥管理、错误重试、并发控制等话题。订阅方式能否用于生产环境，教程中也仅做了初步验证而未给出定论。对于希望深入 Agent 工程化的开发者，这些空白需要额外补充。