90秒上手Claude Agent SDK：从Hello World到自动修复Bug

想要构建一个能够自主读取代码、发现问题并修复的AI Agent，到底需要多少步骤？答案可能比你想象的简单。借助Anthropic推出的Claude Agent SDK，整个流程精简到了几行代码的程度。本文基于一则YouTube教程，拆解从环境安装到让Agent自动修复代码缺陷的完整路径。

两步完成环境搭建

整个起步过程几乎没有门槛。第一步是安装依赖包，只需在终端执行 pip install claude-agent-sdk。第二步是把你的 Anthropic API Key 配置为环境变量——到这里，所有的准备工作就全部结束了。

没有复杂的框架初始化，没有繁琐的配置文件。这种极简的设计理念，正是当前Agent开发工具链追求的方向：把开发者的注意力从样板代码中解放出来，聚焦到真正重要的业务逻辑上。

Hello World：第一次运行Agent

官方示例给出的入门代码非常直观。从SDK中导入 query 方法，向模型抛出一个最简单的问题——「2加2等于几」，然后遍历流式返回的消息，打印出Claude的文本输出。

Import query, ask it, what is 2 plus 2.

由于这个任务没有调用任何工具（tools），整个消息循环只需要一个回合（turn）就能完成。Claude返回「4」，你的第一个Agent就跑起来了。这个例子虽然简单，但它清晰地展示了Agent运行的核心机制：发起查询、接收流式消息、处理输出。

让Agent真正干活：自动排查并修复Bug

真正体现Agent价值的，是第二个案例。官方快速入门提供了一个名为 utils.py 的小文件，里面埋了两个隐藏的Bug：

calculate_average 在传入空列表时会因为除以零而崩溃；
get_username 在用户为 None 时会抛出异常。

The official quickstart gives you a little file called utils.py, with two hidden bugs.

这次的Agent同样是一次 query 调用，但提示词（prompt）变成了：「审查 utils.py 中可能导致崩溃的Bug，并修复你发现的所有问题」。

The prompt says, review utility.

关键在于两个配置选项。第一个是 allowed_tools，这里授权了 read、edit 和 glob 三种工具，让Agent具备读取文件、编辑文件和查找文件的能力。第二个是 permission_mode 设置为 acceptEdits，意味着Agent可以直接修改文件，而不必每一步都停下来征求许可。

allowed_tools 中授权的三种工具各有分工：read 允许Agent读取文件内容，edit 允许对文件进行修改，glob 则允许通过通配符模式（如 *.py）在目录中批量匹配和查找文件。这种基于白名单的工具授权机制是Agent安全设计的基础思路——默认不赋予任何能力，开发者按需显式开启，从而将Agent的"行动半径"限定在可控范围内。permission_mode 的 acceptEdits 模式则是在此基础上进一步提升自动化程度：Agent无需在每次文件写入前弹出确认提示，适合已信任Agent判断力的场景；相对地，开发阶段通常会使用更保守的模式，让开发者逐步审查每一次变更。

从「执行指令」到「自主推理」

点击运行后，整个过程颇具观赏性。Agent先读取文件内容，接着推理哪些输入会触发崩溃，然后动手编辑代码——为空列表加上防护判断，再为缺失用户的情况补上校验逻辑。任务完成。

Hit run, and watch.

最值得玩味的一点是：你从头到尾都没有告诉它该改哪几行代码。你只给出了一个高层次的目标，是Agent自己定位到了问题所在。这正是Agent与传统脚本的本质区别——传统程序执行你写死的指令，而Agent根据目标自主规划并采取行动。

Agent能够"自主定位问题"，依赖的是大语言模型在推理过程中的工具调用循环（Tool Use Loop）：模型读取文件内容后，在上下文中构建代码的心智模型，推断哪些执行路径会引发异常，再决定调用 edit 工具并生成具体的补丁内容。这个过程在底层是多轮消息的来回——每次工具调用的结果会作为新的上下文输入反馈给模型，驱动下一步决策。Claude Agent SDK将这套循环封装在单次 query 调用背后，让开发者无需手动管理轮次，但理解其背后的"感知—推理—行动"循环有助于在更复杂的场景中调试Agent行为。

这意味着什么

这个90秒的演示，背后折射出AI编程工具正在发生的范式转变。开发者的角色逐渐从「编写每一行实现」向「定义目标与边界」迁移。通过 allowed_tools 和 permission_mode 这样的参数，开发者既赋予了Agent行动能力，又保留了对权限范围的控制。

对于想要尝试Agent开发的工程师来说，Claude Agent SDK提供了一条低摩擦的入门路径。它把复杂的工具调用、权限管理和流式交互封装得足够简洁，让人可以在极短时间内从概念走向可运行的产品原型。当然，演示中的案例相对简单，真实生产环境中的Agent还需要考虑错误处理、安全边界和结果验证等更多因素，但作为入门的第一课，它已经把核心思想讲得足够透彻。