引言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( nameget_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 fhttps://api.openweathermap.org/data/2.5/weather params {q: city, appid: api_key, units: units} resp requests.get(url, paramsparams, timeout10) 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(fAgent 异常: {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 的子 AgentSubagent机制让你能像分配任务一样并执行多个 Agentfrom claude_agent_sdk import ClaudeAgent, Subagent from claude_agent_sdk.types import SubagentResult # 定义专门负责代码审查的子 Agent code_reviewer Subagent( namecode_reviewer, description审查 Python 代码检查安全问题、性能瓶颈和代码风格, system_prompt你是一个资深 Python 代码审查专家。 审查代码时关注 1. 安全漏洞SQL 注入、XSS、路径遍历 2. 性能问题N1 查询、不必要的循环 3. PEP 8 代码风格 返回结构化的审查报告。, tools[read_file, grep_search] # 子 Agent 只读不能修改文件 ) # 定义专门负责写单元测试的子 Agent test_writer Subagent( nametest_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% 时自动触发 compactionAutoCompact( threshold0.85, # 触发阈值 strategysummary, # 压缩策略summary / selective / hierarchical preserve_toolsTrue, # 保留工具定义不压缩 preserve_recent10 # 最近 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(modelclaude-opus-4-7) agent ClaudeAgent(cost_trackertracker) # 执行任务后 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_idproject_refactor_20260516, persist_tos3://my-agent-sessions/ # 或本地 sqlite ) try: agent.send(重构整个项目...) except Exception: pass # 即使中断也不怕 # 重新启动后恢复会话 agent2 ClaudeAgent( session_idproject_refactor_20260516, persist_tos3://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 可能随版本更新变化请以 官方文档 为准。
