几何隧道
83.13M · 2026-02-19
你是否想过，如果能将 Claude Code 那种强大的“阅读代码、执行命令、修复 Bug”的能力集成到自己的 Python 或 TypeScript 脚本中，会是怎样的体验？
Claude Agent SDK 正是为此而来。它不仅仅是一个 API 包装器，更是一个完整的代理运行时（Agent Runtime）。它赋予了开发者以编程方式调用 Claude 的能力，让你可以构建能够自主操作文件系统、运行终端命令、甚至自我修正代码的智能体。
本文将带你深入了解 Claude Agent SDK 的核心概念，并通过实战代码带你从零构建一个自动化代理。
在开始之前，请确保你已拥有 Anthropic API Key。
ANTHROPIC_API_KEYBash
pip install claude-agent-sdk
Claude Agent SDK 的核心入口是 query 函数。它是一个异步生成器，会流式返回 Agent 的思考过程、工具调用和最终回复。
创建一个名为 hello_agent.py 的文件：
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。与普通的 Chat API 不同，Agent SDK 的 query 是一个代理循环。
Claude Agent SDK 的强大之处在于其预置的生产级工具：
通过 ClaudeAgentOptions，你可以精细控制 Agent 的行为：
Python
options = ClaudeAgentOptions(
allowed_tools=["Read", "Bash"], # 限制权限，例如禁止 Edit 防止误删文件
system_prompt="你是一个资深的 Python 架构师，只关注代码结构优化。", # 设定角色
cwd="/path/to/project", # 指定工作目录
model="claude-3-7-sonnet-20250219" # 指定具体模型版本
)
让我们构建一个更实用的例子：一个能自动扫描当前项目代码、提取 TODO 注释并生成报告的 Agent。
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 laterndef add(a, b): return a + bn")
with open("utils.py", "w") as f:
f.write("def helper():n # TODO: Add error handling heren passn")
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())
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 员工吧！
