📖 前言
你是否想过，如果能将 Claude Code 那种强大的"阅读代码、执行命令、修复 Bug"的能力集成到自己的 Python 或 TypeScript 脚本中，会是怎样的体验？
Claude Agent SDK 正是为此而来。它不仅仅是一个 API 包装器，更是一个完整的代理运行时（Agent Runtime）。它赋予了开发者以编程方式调用 Claude 的能力，让你可以构建能够自主操作文件系统、运行终端命令、甚至自我修正代码的智能体。
本文将带你深入了解 Claude Agent SDK 的核心概念，并通过实战代码带你从零构建一个自动化代理。
🛠️ 环境准备与安装
在开始之前，请确保你已拥有 Anthropic API Key。
1. 前置要求
- Python: >= 3.10
- API Key : 设置环境变量
ANTHROPIC_API_KEY
2. 安装 SDK
Python
Bash
pip install claude-agent-sdk💻 快速上手：你的第一个 Agent
Claude Agent SDK 的核心入口是 query 函数。它是一个异步生成器，会流式返回 Agent 的思考过程、工具调用和最终回复。
Python 版本
创建一个名为 hello_agent.py 的文件：
Python
python
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
# 定义 Agent 的配置
options = ClaudeAgentOptions(
# 允许 Agent 使用的工具集
allowed_tools=["Bash", "Read", "Edit", "Glob"],
# 开启详细日志（可选）
verbose=True
)
print("🤖 Agent 正在启动...")
# query 函数返回一个异步迭代器
async for message in query(
prompt="请检查当前目录下有哪些 Python 文件，并创建一个名为 'summary.txt' 的文件，里面写上 'Checked by Claude Agent'",
options=options
):
# 实时打印 Agent 的输出（包括思考过程和工具调用结果）
if hasattr(message, "content"):
# 注意：实际结构可能根据 SDK 版本略有不同，这里打印完整消息以便调试
print(message)
elif hasattr(message, "message"):
print(f"Agent 说: {message.message['content']}")
if __name__ == "__main__":
asyncio.run(main())运行结果预期
当你运行此脚本时，Agent 会：
- 思考 ：决定使用
Bash工具运行ls *.py。 - 执行：列出文件。
- 思考 ：决定使用
Edit(或Write) 工具创建summary.txt。 - 执行：写入文件内容。
- 完成：向你汇报任务已完成。
🧩 核心概念详解
1. The Query Loop (查询循环)
与普通的 Chat API 不同，Agent SDK 的 query 是一个代理循环。
- 它不仅发送 Prompt，还会自动处理模型 -> 工具调用 -> 工具执行 -> 模型再思考的完整闭环。
- 你不需要手动编写代码来解析工具调用结果并回传给模型，SDK 内部的运行时（Runtime）会自动处理这一切。
2. Tools (内置工具)
Claude Agent SDK 的强大之处在于其预置的生产级工具：
- Bash: 允许 Agent 在沙箱环境中执行 Shell 命令。
- Read: 读取文件内容。
- Edit: 修改文件（支持智能差异替换，非全量覆盖）。
- Glob: 文件模式匹配搜索。
- LSP (Language Server Protocol) : (高级功能) 让 Agent 拥有类似 IDE 的代码补全和跳转能力。
3. ClaudeAgentOptions (配置选项)
通过 ClaudeAgentOptions，你可以精细控制 Agent 的行为：
Python
ini
options = ClaudeAgentOptions(
allowed_tools=["Read", "Bash"], # 限制权限，例如禁止 Edit 防止误删文件
system_prompt="你是一个资深的 Python 架构师，只关注代码结构优化。", # 设定角色
cwd="/path/to/project", # 指定工作目录
model="claude-3-7-sonnet-20250219" # 指定具体模型版本
)🏗️ 实战案例：自动化代码审查 Agent
让我们构建一个更实用的例子：一个能自动扫描当前项目代码、提取 TODO 注释并生成报告的 Agent。
Python
python
import asyncio
import os
from claude_agent_sdk import query, ClaudeAgentOptions
# 模拟一个带有 TODO 的项目文件
def setup_demo_files():
with open("app.py", "w") as f:
f.write("# TODO: Refactor this function later\ndef add(a, b): return a + b\n")
with open("utils.py", "w") as f:
f.write("def helper():\n # TODO: Add error handling here\n pass\n")
async def run_audit_agent():
# 1. 准备环境
setup_demo_files()
# 2. 定义 Prompt
audit_task = """
请扫描当前目录下的所有 Python 文件。
1. 找出所有包含 'TODO' 的注释。
2. 创建一个 Markdown 表格报告文件 'todo_report.md'。
3. 报告应包含文件名、行号（如果能获取）和 TODO 的内容。
"""
# 3. 配置 Agent
# 注意：我们赋予了 Read 和 Glob 权限用于读取，Edit 权限用于写报告
options = ClaudeAgentOptions(
allowed_tools=["Glob", "Read", "Edit", "Bash"],
verbose=True
)
print(f"🚀 开始执行代码审计任务...\n{'-'*30}")
async for message in query(prompt=audit_task, options=options):
# 简单过滤，只显示最终的文本回复，忽略中间的工具调用细节
# 在实际开发中，你可能需要记录完整的日志
pass
print(f"{'-'*30}\n✅ 任务完成。请检查 todo_report.md 文件。")
# 验证结果
if os.path.exists("todo_report.md"):
print("\n[todo_report.md 内容预览]:")
with open("todo_report.md", "r") as f:
print(f.read())
if __name__ == "__main__":
asyncio.run(run_audit_agent())代码解析
- 自主规划 : Agent 不会像普通 LLM 那样只给你一段 Python 代码让你去跑。它会自己运行
grep或find命令（通过 Bash 工具）来查找文件，或者使用 Python 脚本读取文件内容。 - 工具组合 : 它会先用
Glob找到*.py，然后用Read读取内容，最后用Edit生成 Markdown 文件。整个过程是自动推理完成的。
⚠️ 最佳实践与注意事项
-
权限控制 (Permissions) :
在生产环境中，务必谨慎开启
Bash和Edit权限。建议在 Docker 容器或受限的沙箱环境中运行 Agent，以防它执行rm -rf /等危险命令。 -
System Prompt:
利用
system_prompt参数明确 Agent 的边界。例如："你只能读取文件，严禁修改任何代码逻辑，除非用户明确要求。" -
Token 消耗:
Agent SDK 的工作模式是多轮对话（Loop）。复杂的任务可能会产生大量的 API 调用和 Token 消耗。建议设置
max_turns（如果 SDK 支持）或在 Prompt 中限制步骤数量。 -
错误处理:
query循环可能会抛出异常（如网络中断、API 错误）。在生产代码中，务必使用try...except包裹迭代器。
📝 总结
Claude Agent SDK 填补了"聊天机器人"与"自主智能体"之间的鸿沟。通过本文的 query 循环和工具配置，你已经掌握了构建自动化工作流的基石。无论是自动化测试、代码重构，还是文档生成，Claude Agent SDK 都能成为你强大的编程助手。
现在，去构建你自己的 AI 员工吧！