Claude Agent SDK 实战：用 Python 构建能写代码、搜文件、调 API 的 AI Agent
引言
2026年4月，Anthropic 正式开源了 Claude Agent SDK —— 这个驱动着 Claude Code 的底层引擎。它不是一个简单的 API Wrapper，而是一个完整的 Agent 运行时：工具发现、多轮规划、上下文压缩、子Agent 并行调度，全部内置。
更重要的是，SDK 提供了 Python 和 TypeScript 两种语言的编程接口。这意味着你可以把 Claude Code 级别的 Agent 能力嵌入到自己的应用中。
本文从实际的 Python 代码出发，带你构建一个功能完整的 AI Agent。
一、5 分钟上手：安装与第一条消息
本篇代码基于 Python 3.10+ 环境，SDK 会自动内置 Claude Code CLI，无需额外安装。
pip install claude-agent-sdkfrom claude_agent_sdk import ClaudeAgent # 创建一个最简 Agent agent = ClaudeAgent() # 发送第一条消息 response = agent.send("请列出当前目录下的所有 Python 文件") print(response.content)Agent SDK 默认继承 Claude Code 的完整环境 —— 它能读取文件、执行命令、进行 web 搜索。但真正的威力在于「自定义工具」。
二、工具定义：让 Agent 调用你的代码
Agent 的核心价值在于「行动」。SDK 提供了@tool装饰器来定义自定义工具：
from claude_agent_sdk import ClaudeAgent, tool import requests from typing import Optional # 定义工具：让 Agent 能查询实时天气 @tool( name="get_weather", description="获取指定城市的实时天气信息", parameters={ "type": "object", "properties": { "city": { "type": "string", "description": "城市名称，如 'Beijing'" }, "units": { "type": "string", "enum": ["metric", "imperial"], "default": "metric" } }, "required": ["city"] } ) def get_weather(city: str, units: str = "metric") -> dict: """调用 OpenWeatherMap API 获取天气""" # 实际项目中从环境变量读取 API Key api_key = "your_openweather_api_key" url = f"https://api.openweathermap.org/data/2.5/weather" params = {"q": city, "appid": api_key, "units": units} resp = requests.get(url, params=params, timeout=10) resp.raise_for_status() data = resp.json() return { "city": city, "temp": data["main"]["temp"], "humidity": data["main"]["humidity"], "description": data["weather"][0]["description"], "wind_speed": data["wind"]["speed"] } # 创建携带工具的 Agent agent = ClaudeAgent(tools=[get_weather]) # Agent 现在能自主判断何时需要查天气 response = agent.send( "帮我比较北京和上海今天的温度，哪个城市更适合户外运动？" )当 Agent 判断需要工具时，SDK 自动处理工具调用的序列化、执行和结果回传。你不需要手动管理 function calling 的 JSON schema 或上下文注入 —— SDK 全部内置处理。
三、钩子机制：在 Agent 生命周期的关键节点插入逻辑
SDK 提供了一套完整的钩子（Hooks）系统，让你能在 Agent 执行的关键时刻插入自定义逻辑：
from claude_agent_sdk import ClaudeAgent, hook @hook("pre_tool_use") def audit_tool_calls(tool_name: str, arguments: dict): """在工具调用前，记录审计日志""" import logging logger = logging.getLogger("agent_audit") logger.info(f"工具调用审计: {tool_name}({arguments})") # 可以实现安全拦截：如果工具是 delete_file，要求二次确认 if tool_name == "delete_file": return {"confirm_required": True} return None # None = 允许继续 @hook("post_message") def enrich_response(message: str) -> str: """在 Agent 回复后，自动追加数据来源标注""" return f"{message}\n\n---\n*本回复由 Claude Agent SDK 驱动 | 数据来源已标注*" @hook("on_error") def handle_errors(error: Exception, context: dict): """全局错误处理 + 自动重试""" import logging logger = logging.getLogger("agent_errors") logger.error(f"Agent 异常: {error}, 上下文: {context}") # 网络错误自动重试一次 if "ConnectionError" in str(type(error)): return {"retry": True, "max_retries": 1} return None agent = ClaudeAgent( tools=[get_weather, search_files], hooks=[audit_tool_calls, enrich_response, handle_errors] )钩子机制的精妙之处在于：你可以给 Agent 添加企业级的横切关注点（日志、审计、安全策略），而不用修改任何工具代码。
四、子 Agent 编排：像管理团队一样管理 AI
当任务复杂到单个 Agent 无法高效处理时，SDK 的子 Agent（Subagent）机制让你能像分配任务一样并执行多个 Agent：
from claude_agent_sdk import ClaudeAgent, Subagent from claude_agent_sdk.types import SubagentResult # 定义专门负责代码审查的子 Agent code_reviewer = Subagent( name="code_reviewer", description="审查 Python 代码，检查安全问题、性能瓶颈和代码风格", system_prompt="""你是一个资深 Python 代码审查专家。 审查代码时关注： 1. 安全漏洞（SQL 注入、XSS、路径遍历） 2. 性能问题（N+1 查询、不必要的循环） 3. PEP 8 代码风格 返回结构化的审查报告。""", tools=["read_file", "grep_search"] # 子 Agent 只读，不能修改文件 ) # 定义专门负责写单元测试的子 Agent test_writer = Subagent( name="test_writer", description="为 Python 函数编写 pytest 单元测试", system_prompt="""你是一个测试工程师。 为给定的代码编写全面的 pytest 测试： - 覆盖正常路径和边界条件 - 使用 pytest.fixture 管理测试数据 - 包含异常情况的测试 只写测试代码，不要修改源码。""", tools=["read_file", "write_file"] ) # 主 Agent 携带子 Agent agent = ClaudeAgent(subagents=[code_reviewer, test_writer]) # 一句话触发并行工作流 response = agent.send(""" 请对 src/user_service.py 进行全面的代码审查， 然后为其中的核心函数编写单元测试。 两个任务可以并行进行。 """)子 Agent 在独立的沙箱中运行，主 Agent 负责编排、合并结果并做最终决策。这种模式天然适合 CI/CD 流水线、代码审查自动化等场景。
五、上下文管理：突破对话长度限制
真实项目中的 Agent 往往会遇到上下文窗口耗尽的问题。SDK 提供了自动压缩机制：
from claude_agent_sdk import ClaudeAgent from claude_agent_sdk.compaction import AutoCompact agent = ClaudeAgent( # 开启自动压缩：当上下文达到 85% 时自动触发 compaction=AutoCompact( threshold=0.85, # 触发阈值 strategy="summary", # 压缩策略：summary / selective / hierarchical preserve_tools=True, # 保留工具定义不压缩 preserve_recent=10 # 最近 10 轮对话不压缩 ), tools=[search_codebase, run_tests, deploy] ) # Agent 能处理远超上下文窗口的长时间任务 response = agent.send(""" 扫描整个项目的所有 Python 文件（约 500 个）， 找出所有未使用的 import，生成修复 PR。 """)三种压缩策略的对比：
| 策略 | 原理 | 适用场景 |
|---|---|---|
summary | 用 LLM 总结早期对话 | 通用场景，信息密度低 |
selective | 保留与当前任务最相关的片段 | 任务切换频繁 |
hierarchical | 多级摘要：片段→章节→总纲 | 超长任务（1000+ 轮） |
六、生产环境最佳实践
1. 错误隔离：每个 Agent 独立沙箱
agent = ClaudeAgent( sandbox={ "type": "docker", # 使用 Docker 容器隔离 "image": "python:3.12-slim", "read_only_root": True, # 根文件系统只读 "network": "restricted", # 仅允许白名单域名 "memory_limit": "2g", "timeout": 300 # 5 分钟超时 } )2. 成本追踪：监控 Token 消耗
from claude_agent_sdk import ClaudeAgent, CostTracker tracker = CostTracker(model="claude-opus-4-7") agent = ClaudeAgent(cost_tracker=tracker) # 执行任务后 agent.send("分析这个 2000 行的 Rust 项目并给出重构建议") # 获取成本明细 report = tracker.report() print(f"输入 Token: {report.input_tokens:,}") print(f"输出 Token: {report.output_tokens:,}") print(f"预估成本: ${report.estimated_cost:.2f}") # 按工具调用拆分 for tool_call in report.tool_breakdown: print(f" {tool_call.name}: {tool_call.tokens:,} tokens")3. 持久化会话：断点续跑
agent = ClaudeAgent( session_id="project_refactor_20260516", persist_to="s3://my-agent-sessions/" # 或本地 sqlite ) try: agent.send("重构整个项目...") except Exception: pass # 即使中断也不怕 # 重新启动后恢复会话 agent2 = ClaudeAgent( session_id="project_refactor_20260516", persist_to="s3://my-agent-sessions/" ) agent2.send("继续之前未完成的重构任务")结语
Claude Agent SDK 的发布，标志着 AI Agent 开发从「手写 Function Calling JSON Schema」的苦力活，进化到了「用几行 Python 描述工具和流程」的工程化阶段。
工具定义、钩子机制、子Agent 编排、上下文压缩、会话持久化 —— 这些曾经需要数百行胶水代码才能实现的能力，现在成了 SDK 的内置原语。
对于开发者来说，这意味着你不需要成为 AI 专家才能构建 AI Agent。你只需要会写 Python，然后告诉 Agent 你的工具长什么样。
本文代码基于 Claude Agent SDK v0.1.x (2026 年 4 月发布)。API 可能随版本更新变化，请以 官方文档 为准。