在 AI Agent 开发领域，Anthropic Agent SDK 提供了一套强大的工具链，让 Claude 能够直接操作文件、执行命令并自主完成任务。
本文将带你通过一个实战案例——构建一个自动发现并修复 Python 代码 Bug 的 Agent，深入理解该 SDK 的核心用法。
🛠️ 准备工作 (Prerequisites)
在开始之前，请确保你满足以下条件：
- Python 环境：Python 3.10 或更高版本。
- API Key：拥有一个 Anthropic Console 账号并创建了 API Key。
📦 安装 SDK (Installation)
首先，我们需要安装 Python 版本的 Agent SDK。打开终端执行以下命令：
Bash
pip install claude-agent-sdk
接着，设置你的 API Key 环境变量（或者将其写入 .env 文件）：
Bash
export ANTHROPIC_API_KEY="your-api-key-here"
📝 实战：构建自动修复 Agent
我们将创建一个包含故意错误的代码文件，然后编写一个 Agent 来自动读取、分析并修复它。
第一步：创建“有 Bug”的文件
在你的项目目录下创建一个名为 utils.py 的文件，填入以下包含潜在 Bug 的代码：
Python
# utils.py
def calculate_average(numbers):
total = 0
for num in numbers:
total += num
# Bug 1: 如果 numbers 为空列表，这里会抛出 ZeroDivisionError
return total / len(numbers)
def get_user_name(user):
# Bug 2: 如果 user 为 None，这里会抛出 TypeError
return user["name"].upper()
第二步：编写 Agent 代码
创建一个名为 agent.py 的文件。我们将使用 SDK 的 query 函数来启动一个 Agent 循环。
注意代码中的 ClaudeAgentOptions 配置，我们赋予了 Agent 读取 (Read) 、编辑 (Edit) 和 列出文件 (Glob) 的权限，并设置 permission_mode="acceptEdits" 以允许自动应用修改。
Python
# agent.py
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
async def main():
print("🤖 Agent 正在启动，开始分析 utils.py ...")
# 配置 Agent 的能力和权限
options = ClaudeAgentOptions(
# 授予 Agent 读取、编辑文件和文件搜索的工具权限
allowed_tools=["Read", "Edit", "Glob"],
# ⚠️ acceptEdits 模式会自动批准 Agent 的文件修改请求，适合无人值守运行
permission_mode="acceptEdits",
)
# 启动 Agent 循环
# query() 函数返回一个异步迭代器，随着 Claude 的思考和操作实时生成消息
async for message in query(
prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options=options
):
# 处理并打印 Agent 的实时反馈
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
# 打印 Claude 的思考过程
print(f"💡 思考: {block.text}")
elif hasattr(block, "name"):
# 打印 Agent 正在调用的工具（如 Read, Edit）
print(f"🔧 调用工具: {block.name}")
# 打印最终结果
elif isinstance(message, ResultMessage):
print(f"✅ 完成: {message.subtype}")
if __name__ == "__main__":
asyncio.run(main())
第三步：运行 Agent
在终端运行 agent.py：
Bash
python agent.py
🎉 运行结果
你会看到终端中打印出 Agent 的思考过程。它通常会执行以下步骤：
- Read: 读取
utils.py的内容。 - Analysis: 分析代码，发现空列表除零错误和 NoneType 访问错误。
- Edit: 调用编辑工具，自动重写
utils.py增加防御性代码。
运行结束后，再次查看 utils.py，你会发现代码已经被自动修复了（类似于以下内容）：
Python
def calculate_average(numbers):
if not numbers:
return 0
total = 0
for num in numbers:
total += num
return total / len(numbers)
def get_user_name(user):
if user is None:
return ""
return user.get("name", "").upper()
🔍 核心代码解析
1. query() 函数
这是 SDK 的核心入口。它建立了一个与 Claude 的会话循环。
- 流式响应：通过
async for我们可以实时获取 Agent 的每一步操作（思考、调用工具、工具返回结果），而不是傻等任务全部结束。 - 自动编排：SDK 自动处理了“模型思考 -> 调用工具 -> 获取工具结果 -> 再次思考”的复杂循环。
2. ClaudeAgentOptions
这是控制 Agent 行为的关键配置对象。
-
allowed_tools: 决定了 Agent 的能力边界。Read,Glob,Grep: 只读权限，适合代码审查。Edit: 允许修改文件，适合自动重构或修复。Bash: 允许执行 Shell 命令（慎用！适合自动化运维）。
-
permission_mode:acceptEdits: 自动批准文件修改，实现全自动化。default: 在执行敏感操作（如写文件）前会暂停并等待人工确认（通过回调函数）。
🚀 进阶：自定义 Agent 能力
你可以通过修改 options 轻松扩展 Agent 的能力。
场景：给 Agent 增加“上网”和“执行命令”的能力
Python
options = ClaudeAgentOptions(
# 增加 WebSearch 和 Bash 工具
allowed_tools=["Read", "Edit", "Glob", "WebSearch", "Bash"],
permission_mode="acceptEdits"
)
# 此时你可以尝试这样的 Prompt：
# "搜索最新的 Python 3.12 特性，并写一个 demo.py 演示其中三个特性，然后运行它。"
⚠️ 注意事项
- 安全权限：在使用
Bash工具或acceptEdits模式时请务必小心，确保 Agent 运行在受控环境（如 Docker 容器）中，防止误删文件。 - 成本控制：Agent 循环可能会消耗较多 Token，建议在开发测试阶段关注 API 使用量。
通过这篇指南，你已经掌握了使用 Python 版本的 Anthropic Agent SDK 构建自修复代码助手的基础。现在的 AI 不仅仅是对话机器人，更是能实实在在帮你干活的“数字员工”。快去尝试构建你自己的 Agent 吧！
