09-Agent-SDK完整指南

09 Agent SDK完整指南 09 Agent SDK完整指南 Modified May 9 4. 使用更小的模型：简单任务用Haiku Code block Python Copy options = ClaudeAgentOptions( model='claude haiku 4 5 20251001', 便宜模型 max turns=5, 限制轮数 system prompt="简洁回复。" 简短提示 ) Q4: 子代理和主代理怎么通信？ 答：通过 Agent 工具调用与最终结果回传： 1. 主 Agent 通过 Agent 工具创建/调用子代理，指定任务 2. 子代理执行任务并返回结果 3. 主 Agent 收到子代理最终消息，作为后续汇总或下一步决策的输入 子代理运行在独立上下文里，父级不会自动继承它读过的所有文件和中间工具结果；需要保留的信息应让子代理在最终回复里明确写出来。 Q5: 可以同时运行多少个子代理？ 答：最多10个并行。如果需要处理更多任务，会自动排队。 Q6: 如何在生产环境使用？ 答：几个建议： 1. 使用权限控制：设置allowed tools白名单 2. 启用沙箱：防止危险命令 3. 添加Hooks：记录日志、过滤危险操作 4. 设置超时：防止任务卡住 5. 监控Token消耗：控制成本 Code block Python Copy 生产环境配置示例 production options = ClaudeAgentOptions( model='claude sonnet 4 6', 推荐模型 allowed tools=['Read', 'Glob', 'Grep'], 最小权限 permission mode='default', 需要确认 max turns=10, sandbox={"enabled": True}, hooks={ "PreToolUse": [safety hooks], "PostToolUse": [logging hooks] } ) Q7: SDK支持流式输出吗？ 答：是的！query函数返回的是AsyncIterator，天然支持流式： Code block Python Copy async for message in query(prompt="...", options=options): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(block.text, end='', flush=True) 流式打印 Q8: 如何处理长时间运行的任务？ 答： 1. 使用后台运行的子代理：在 AgentDefinition 中设置 background=True 2. 设置合理的超时 3. 使用异步并行 Code block Python Copy prompt = """请使用子代理并行处理： 子代理1：分析src目录 子代理2：分析tests目录 如果这些子代理被配置为 background=True，请持续跟踪它们的最终结果后再汇总。""" Q9: 自定义工具可以访问外部API吗？ 答：可以！自定义工具就是普通的Python/TypeScript函数： Code block Python Copy import httpx @tool("weather", "获取天气信息", {"city": str}) async def get weather(args): city = args.get('city') async with httpx.AsyncClient() as client: response = await client.get(f"https://api.weather.com/{city}") data = response.json() return {"content": [{"type": "text", "text": f"{city}天气：{data}"}]} Q10: 如何调试Agent的决策过程？ 答：打印所有消息类型： Code block Python Copy async for message in query(prompt="...", options=options): print(f"[{type(message). name }] ", end='') if isinstance(message, AssistantMessage): print("AI思考中...") for block in message.content: if isinstance(block, TextBlock): print(f" 文本: {block.text[:100]}...") elif isinstance(block, ToolUseBlock): print(f" 调用工具: {block.name}({block.input})") elif isinstance(message, ToolResultBlock): print(f"工具结果: {str(message.content)[:100]}...") Q11: SDK会自动重试失败的请求吗？ 答：SDK有基本的重试机制，但你可以自己加强： Code block Python Copy import asyncio from tenacity import retry, stop after attempt, wait exponential @retry(stop=stop after attempt(3), wait=wait exponential(min=1, max=10)) async def query with retry(prompt, options): results = [] async for message in query(prompt=prompt, options=options): results.append(message) return results Q12: 如何在Jupyter Notebook中使用？ 答：需要处理事件循环： Code block Python Copy import nest asyncio nest asyncio.apply() 然后正常使用 import asyncio from claude agent sdk import query, ClaudeAgentOptions async def run(): async for message in query(prompt="Hello", options=ClaudeAgentOptions()): print(message) asyncio.run(run()) Q13: 可以保存和恢复会话吗？ 答：SDK本身不提供会话持久化，但你可以自己实现： Code block Python Copy import json 保存对话历史 conversation history = [] async for message in query(prompt="...", options=options): conversation history.append({ "type": type(message). name , "content": str(message) }) 保存到文件 with open("session.json", "w") as f: json.dump(conversation history, f) Q14: TypeScript和Python SDK功能一样吗？ 答：是的，功能完全相同。选择你熟悉的语言即可。 Q15: 如何处理大文件？ 答：Agent会自动分块处理。如果文件太大，考虑： 1. 只读取需要的部分 2. 使用Grep搜索而不是Read全文 3. 拆分任务给多个子代理 Q16: SDK支持哪些AI模型？ 答：支持Claude系列模型： • claude opus 4 6（最强） • claude sonnet 4 6（推荐） • claude haiku 4 5 20251001（最快最便宜） 通过model参数指定： Code block Python Copy options = ClaudeAgentOptions(model='claude sonnet 4 6') Q17: 如何测试自定义工具？ 答：单独测试工具函数： Code block Python Copy 直接调用测试 result = await calculate({"expression": "2+2"}) print(result) 应该输出 {"content": [{"type": "text", "text": "2+2 = 4"}]} 然后在Agent中测试 async for message in query( prompt="请计算 2+2", options=ClaudeAgentOptions( mcp servers={"tools": my tools}, allowed tools=["mcp tools calculate"] ) ): print(message) 4. 使用更小的模型：简单任务用Haiku Q4: 子代理和主代理怎么通信？ 答：通过 Agent 工具调用与最终结果回传： 1. 主 Agent 通过 Agent 工具创建/调用子代理，指定任务 2. 子代理执行任务并返回结果 3. 主 Agent 收到子代理最终消息，作为后续汇总或下一步决策的输入 子代理运行在独立上下文里，父级不会自动继承它读过的所有文件和中间工具结果；需要保留的信息应让子代理在最终回复里明确写出来。 Q5: 可以同时运行多少个子代理？ 答：最多10个并行。如果需要处理更多任务，会自动排队。 Q6: 如何在生产环境使用？ 答：几个建议： 1. 使用权限控制：设置allowed tools白名单 2. 启用沙箱：防止危险命令 3. 添加Hooks：记录日志、过滤危险操作 4. 设置超时：防止任务卡住 5. 监控Token消耗：控制成本 Q7: SDK支持流式输出吗？ 答：是的！query函数返回的是AsyncIterator，天然支持流式： Q8: 如何处理长时间运行的任务？ 答： 1. 使用后台运行的子代理：在 AgentDefinition 中设置 background=True 2. 设置合理的超时 3. 使用异步并行 Q9: 自定义工具可以访问外部API吗？ 答：可以！自定义工具就是普通的Python/TypeScript函数： Q10: 如何调试Agent的决策过程？ 答：打印所有消息类型： Q11: SDK会自动重试失败的请求吗？ 答：SDK有基本的重试机制，但你可以自己加强： Q12: 如何在Jupyter Notebook中使用？ 答：需要处理事件循环： Q13: 可以保存和恢复会话吗？ 答：SDK本身不提供会话持久化，但你可以自己实现： Q14: TypeScript和Python SDK功能一样吗？ 答：是的，功能完全相同。选择你熟悉的语言即可。 Q15: 如何处理大文件？ 答：Agent会自动分块处理。如果文件太大，考虑： 1. 只读取需要的部分 2. 使用Grep搜索而不是Read全文 3. 拆分任务给多个子代理 Q16: SDK支持哪些AI模型？ 答：支持Claude系列模型： • claude opus 4 6（最强） • claude sonnet 4 6（推荐） • claude haiku 4 5 20251001（最快最便宜） 通过model参数指定： Q17: 如何测试自定义工具？ 答：单独测试工具函数： Q18: 如何处理API速率限制？ 答： 1. 添加请求间隔 2. 使用指数退避重试 3. 监控速率限制错误 Q19: 安全最佳实践有哪些？ 答： 1. 最小权限原则：只给需要的工具权限 2. 输入验证：自定义工具要验证输入 3. 不信任用户输入：Agent的prompt可能被注入 4. 启用沙箱：Bash命令在沙箱中执行 5. 使用Hooks过滤：阻止危险操作 6. 监控日志：记录所有工具调用 Q20: 有官方示例代码吗？ 答：有！ • Python示例：https://github.com/anthropics/claude agent sdk python/tree/main/examples • TypeScript示例：https://github.com/anthropics/claude agent sdk typescript/tree/main/examples 推荐从quick start.py或quick start.ts开始。 本课总结 核心知识点回顾 1. Agent SDK定位：把Claude Code的能力封装为可编程接口 2. query函数：核心API，返回流式消息 3. Agent Loop：接收→思考→使用工具→检查→继续/结束 4. Tools：Agent的能力来源，可以自定义扩展 5. Subagents：并行处理复杂任务 6. Hooks：在关键时刻自动执行自定义逻辑 最佳实践总结 场景 建议 模型选择 日常用Sonnet，复杂推理用Opus，简单任务用Haiku 权限控制 生产环境用最小权限，开发可以放宽 子代理 大任务拆分并行，注意最多10个同时运行 自定义工具 优先用SDK内置MCP服务器，简单高效 错误处理 使用try/catch，添加重试机制 场景 场景 建议 建议 模型选择 模型选择 日常用Sonnet，复杂推理用Opus，简单任务用Haiku 日常用Sonnet，复杂推理用Opus，简单任务用Haiku 权限控制 权限控制 生产环境用最小权限，开发可以放宽 生产环境用最小权限，开发可以放宽 子代理 子代理 大任务拆分并行，注意最多10个同时运行 大任务拆分并行，注意最多10个同时运行 自定义工具 自定义工具 优先用SDK内置MCP服务器，简单高效 优先用SDK内置MCP服务器，简单高效 错误处理 错误处理 使用try/catch，添加重试机制 使用try/catch，添加重试机制 下一步学习 完成本课后，建议继续学习： 1. MCP开发：深入学习MCP协议，创建更复杂的工具 2. Hooks高级应用：实现自动测试、自动格式化等工作流 3. 企业集成：将Agent SDK集成到CI/CD流程 课程版本：V1.2最后更新：2026年4月5日作者：老金 版本历史 版本 日期 修改内容 V1.2 2026 02 26 更新所有模型引用至最新4.6版本：Sonnet 4.6（claude sonnet 4 6）、Opus 4.6（claude opus 4 6）、Haiku 4.5（claude haiku 4 5 20251001） V1.1 2025 12 24 修正所有模型名称为最新4.5版本（claude sonnet 4 5 20250929、claude opus 4 5 20251101、claude 3 5 haiku 20241022） V1.0 2025 12 19 初版发布 版本 版本 日期 日期 修改内容 修改内容 V1.2 V1.2 2026 02 26 2026 02 26 更新所有模型引用至最新4.6版本：Sonnet 4.6（claude sonnet 4 6）、Opus 4.6（claude opus 4 6）、Haiku 4.5（claude haiku 4 5 20251001） 更新所有模型引用至最新4.6版本：Sonnet 4.6（claude sonnet 4 6）、Opus 4.6（claude opus 4 6）、Haiku 4.5（claude haiku 4 5 20251001） V1.1 V1.1 2025 12 24 2025 12 24 修正所有模型名称为最新4.5版本（claude sonnet 4 5 20250929、claude opus 4 5 20251101、claude 3 5 haiku 20241022） 修正所有模型名称为最新4.5版本（claude sonnet 4 5 20250929、claude opus 4 5 20251101、claude 3 5 haiku 20241022） V1.0 V1.0 2025 12 19 2025 12 19 初版发布 初版发布 参考资料： • 官方Agent SDK总览 官方Agent SDK总览 • 官方Agent SDK Skills文档 官方Agent SDK Skills文档 • GitHub Python SDK GitHub Python SDK • GitHub TypeScript SDK GitHub TypeScript SDK • DataCamp教程 DataCamp教程 • KDnuggets入门指南 KDnuggets入门指南 Claude Agent SDK 完整指南：把AI编程能力装进你的程序里 课程信息 • 作者：老金 • GitHub：https://github.com/KimYx0207 • 公众号：老金带你玩AI • X（Twitter）：老金带你玩AI • 个人博客：https://aiking.dev • 预计学时：6 8小时 • 难度等级：⭐⭐⭐ 中级进阶 • 更新日期：2026年4月 • 适用版本：Claude Code v2.1.133（验证于 2026 05 08） • 信息来源：官方概览、GitHub Python SDK、GitHub TypeScript SDK 版本说明：Claude Agent SDK（原名Claude Code SDK）是2025年Anthropic官方发布的开发工具包。本教程基于最新官方文档编写，如有更新请以官方为准。 https://aiking.dev 官方概览 GitHub Python SDK GitHub TypeScript SDK 课程信息 • 作者：老金 • GitHub：https://github.com/KimYx0207 • 公众号：老金带你玩AI • X（Twitter）：老金带你玩AI • 个人博客：https://aiking.dev https://aiking.dev • 预计学时：6 8小时 • 难度等级：⭐⭐⭐ 中级进阶 • 更新日期：2026年4月 • 适用版本：Claude Code v2.1.133（验证于 2026 05 08） • 信息来源：官方概览、GitHub Python SDK、GitHub TypeScript SDK 官方概览 GitHub Python SDK GitHub TypeScript SDK 版本说明：Claude Agent SDK（原名Claude Code SDK）是2025年Anthropic官方发布的开发工具包。本教程基于最新官方文档编写，如有更新请以官方为准。 2026 04 差量更新（先读） 这章主体内容已经切到了 Agent SDK，但还有两个容易混淆的点： • 官方文档主入口已经转到 platform.claude.com/docs/.../agent sdk/...，不要再把旧的 Claude Code SDK 文档路径当主入口。 platform.claude.com/docs/.../agent sdk/... • 当前包名与品牌都应统一写作 Claude Agent SDK；“Claude Code SDK”只适合作为迁移说明里的旧称呼。 v2.1.132+ / v2.1.133 SDK 相关变更 v2.1.132： • CLAUDE CODE SESSION ID：Bash 工具的子进程环境中现在自动注入此环境变量。如果你的 Agent 通过 Claude Code 的 Bash 工具执行脚本，脚本可以通过 $CLAUDE CODE SESSION ID 获取当前会话 ID，用于日志关联和状态追踪。 • CLAUDE CODE FORK SUBAGENT：当 Skill 以 context: fork 模式运行时，子进程会自动设置此变量为 1。用于区分主会话和 fork 子代理。 v2.1.133： • localSettings suggestion：SDK 的 Message 类型中新增 localSettings 字段，用于向 Claude Code 建议本地设置项。具体 schema 以官方 SDK 类型定义为准。 • mcp authenticate redirectUri：MCP OAuth 认证流程中的 mcp authenticate 工具新增 redirectUri 参数，支持更灵活的 OAuth 回调配置。 本课学习目标 完成本课学习后，你将能够： 1. 理解SDK的核心价值：掌握Agent SDK与Claude Code CLI的关系和定位 2. 5分钟快速上手：完成Hello World Agent的创建和运行 3. 掌握核心概念：深入理解Tools、Agent Loop、Context Management 4. 独立完成3个实战项目：从one shot到multi tool再到streaming模式 5. 自定义工具开发：创建SDK内置MCP服务器，扩展Agent能力 6. 故障排查技能：独立解决90%的常见问题 学习路径导航（先看这里！） 这是一篇长教程，不用全看！根据你的目标选择路径。 路径A：快速体验（60分钟） 适合人群：急着体验Agent SDK，想快速跑个Demo 只看这些章节： 60分钟后你能达到：成功运行第一个Agent，理解基本工作流程 路径B：系统学习（6 8小时） 适合人群：想深入掌握Agent SDK，准备在项目中使用 学习顺序：从头到尾所有章节 建议分段学习： • 第1天（2小时）：第一 三部分（概念+安装+核心原理） • 第2天（2小时）：第四部分（3个实战项目） • 第3天（2小时）：第五 六部分（高级功能+故障排查） • 第4天（1小时）：第七部分FAQ + 总复习 路径C：问题速查（5分钟） 适合人群：使用中遇到问题，需要快速解决 直接跳到： 路径D：专项学习（30 60分钟/主题） 适合人群：已经会基础，想深入某个功能 想学什么 看哪几节 预计时间 自定义工具 第三部分3.3节 + 第四部分项目3 60分钟 Hooks钩子 第五部分5.2节 45分钟 子代理并行 第三部分3.4节 + 第四部分项目3 60分钟 MCP集成 第五部分5.1节 45分钟 想学什么 想学什么 看哪几节 看哪几节 预计时间 预计时间 自定义工具 自定义工具 第三部分3.3节 + 第四部分项目3 第三部分3.3节 + 第四部分项目3 60分钟 60分钟 Hooks钩子 Hooks钩子 第五部分5.2节 第五部分5.2节 45分钟 45分钟 子代理并行 子代理并行 第三部分3.4节 + 第四部分项目3 第三部分3.4节 + 第四部分项目3 60分钟 60分钟 MCP集成 MCP集成 第五部分5.1节 第五部分5.1节 45分钟 45分钟 术语表（小白必读） 在开始之前，先了解这些关键术语。不理解术语会影响后续学习！ 术语 英文全称 通俗解释 SDK Software Development Kit 软件开发工具包，就像一个"工具箱"，里面有各种你需要的零件和工具，让你能更方便地造东西 Agent • 智能代理/自动机器人，能够自主完成任务的AI程序。就像一个会思考的机器人助手，你给它任务，它自己想办法完成 Agent Loop • 代理循环，Agent工作的核心流程：接收任务→思考→使用工具→检查结果→继续或结束。就像一个"工作循环" Tool • 工具，Agent可以调用的能力，比如读文件、写文件、执行命令等。就像机器人的"手"和"眼睛" Hook • 钩子，在特定时机自动触发的回调函数。就像设置的"自动报警器"，特定事件发生时自动执行 MCP Model Context Protocol 模型上下文协议，让Agent连接外部工具的标准协议。就像USB接口标准，让各种设备能统一接入 Stream/Streaming • 流式传输，数据像流水一样一点点传过来，而不是等全部完成才一次性传输。就像看视频边加载边播放 Async/Await • 异步编程语法，让程序不用傻等，可以同时处理多件事。就像你等外卖时还能看手机，不用傻站着 Iterator • 迭代器，一种可以逐个获取数据的对象。就像自动发牌机，每次给你一张牌 Context • 上下文，AI理解对话的背景信息。就像聊天记录，AI通过它知道你之前说了什么 Token • 计费单位，AI处理文字的最小单元。约等于0.75个英文单词或1 2个汉字 Subagent • 子代理，由主Agent创建的子任务执行者。就像主管派出去干活的员工 术语 术语 英文全称 英文全称 通俗解释 通俗解释 SDK SDK Software Development Kit Software Development Kit 软件开发工具包，就像一个"工具箱"，里面有各种你需要的零件和工具，让你能更方便地造东西 软件开发工具包，就像一个"工具箱"，里面有各种你需要的零件和工具，让你能更方便地造东西 Agent Agent • • 智能代理/自动机器人，能够自主完成任务的AI程序。就像一个会思考的机器人助手，你给它任务，它自己想办法完成 智能代理/自动机器人，能够自主完成任务的AI程序。就像一个会思考的机器人助手，你给它任务，它自己想办法完成 Agent Loop Agent Loop • • 代理循环，Agent工作的核心流程：接收任务→思考→使用工具→检查结果→继续或结束。就像一个"工作循环" 代理循环，Agent工作的核心流程：接收任务→思考→使用工具→检查结果→继续或结束。就像一个"工作循环" Tool Tool • • 工具，Agent可以调用的能力，比如读文件、写文件、执行命令等。就像机器人的"手"和"眼睛" 工具，Agent可以调用的能力，比如读文件、写文件、执行命令等。就像机器人的"手"和"眼睛" Hook Hook • • 钩子，在特定时机自动触发的回调函数。就像设置的"自动报警器"，特定事件发生时自动执行 钩子，在特定时机自动触发的回调函数。就像设置的"自动报警器"，特定事件发生时自动执行 MCP MCP Model Context Protocol Model Context Protocol 模型上下文协议，让Agent连接外部工具的标准协议。就像USB接口标准，让各种设备能统一接入 模型上下文协议，让Agent连接外部工具的标准协议。就像USB接口标准，让各种设备能统一接入 Stream/Streaming Stream/Streaming • • 流式传输，数据像流水一样一点点传过来，而不是等全部完成才一次性传输。就像看视频边加载边播放 流式传输，数据像流水一样一点点传过来，而不是等全部完成才一次性传输。就像看视频边加载边播放 Async/Await Async/Await • • 异步编程语法，让程序不用傻等，可以同时处理多件事。就像你等外卖时还能看手机，不用傻站着 异步编程语法，让程序不用傻等，可以同时处理多件事。就像你等外卖时还能看手机，不用傻站着 Iterator Iterator • • 迭代器，一种可以逐个获取数据的对象。就像自动发牌机，每次给你一张牌 迭代器，一种可以逐个获取数据的对象。就像自动发牌机，每次给你一张牌 Context Context • • 上下文，AI理解对话的背景信息。就像聊天记录，AI通过它知道你之前说了什么 上下文，AI理解对话的背景信息。就像聊天记录，AI通过它知道你之前说了什么 Token Token • • 计费单位，AI处理文字的最小单元。约等于0.75个英文单词或1 2个汉字 计费单位，AI处理文字的最小单元。约等于0.75个英文单词或1 2个汉字 Subagent Subagent • • 子代理，由主Agent创建的子任务执行者。就像主管派出去干活的员工 子代理，由主Agent创建的子任务执行者。就像主管派出去干活的员工 第一部分：Claude Agent SDK 简介 1.1 什么是 Claude Agent SDK 用一句话说：Claude Agent SDK是Anthropic官方提供的开发工具包，让你能够在自己的Python或TypeScript程序中使用Claude Code的全部能力。 生活类比： 想象Claude Code是一辆装配完整的汽车，你可以开着它到处跑。而Agent SDK就是这辆车的发动机、变速箱和底盘的组合包，让你能够打造属于自己的定制车型。 1.2 SDK vs CLI：什么时候用哪个？ Claude Code有两种使用方式，选择取决于你的场景： 对比表： 特性 Claude Code CLI Claude Agent SDK 使用方式 在终端里输入命令 在代码里调用函数 适合场景 日常开发、快速任务 自动化、批处理、集成到系统 交互方式 人工对话 程序控制 并发能力 单会话 多代理并行 定制程度 配置文件 完全可编程 学习曲线 低（会打字就行） 中（需要编程基础） 特性 特性 Claude Code CLI Claude Code CLI Claude Agent SDK Claude Agent SDK 使用方式 使用方式 在终端里输入命令 在终端里输入命令 在代码里调用函数 在代码里调用函数 适合场景 适合场景 日常开发、快速任务 日常开发、快速任务 自动化、批处理、集成到系统 自动化、批处理、集成到系统 交互方式 交互方式 人工对话 人工对话 程序控制 程序控制 并发能力 并发能力 单会话 单会话 多代理并行 多代理并行 定制程度 定制程度 配置文件 配置文件 完全可编程 完全可编程 学习曲线 学习曲线 低（会打字就行） 低（会打字就行） 中（需要编程基础） 中（需要编程基础） 什么时候用SDK？ 1. 自动化脚本：每天自动审查代码、生成报告 2. 批量处理：一次处理100个文件的重构 3. 系统集成：把Claude嵌入你的CI/CD流程 4. 多Agent协作：让多个Agent并行工作 5. 定制化工具：构建特定领域的AI助手 什么时候用CLI？ 1. 日常开发：写代码、改bug、问问题 2. 快速任务：临时需要AI帮忙的小事 3. 学习探索：熟悉Claude的能力 4. 不想写代码：就想简单聊聊 1.3 支持的编程语言 Agent SDK目前官方支持两种语言，选择你熟悉的即可： Python SDK TypeScript/JavaScript SDK 老金建议：两种SDK功能完全相同，选你最熟悉的语言就好。本教程会同时展示两种语言的代码示例。 1.4 版本演进说明 Claude Agent SDK经历了从"Claude Code SDK"到"Agent SDK"的品牌升级： 版本阶段 包名 状态 早期 @anthropic ai/claude code / claude code sdk 已弃用 当前 @anthropic ai/claude agent sdk / claude agent sdk 推荐使用 版本阶段 版本阶段 包名 包名 状态 状态 早期 早期 @anthropic ai/claude code / claude code sdk @anthropic ai/claude code / claude code sdk 已弃用 已弃用 当前 当前 @anthropic ai/claude agent sdk / claude agent sdk @anthropic ai/claude agent sdk / claude agent sdk 推荐使用 推荐使用 如果你之前用旧版SDK，需要更新导入语句： 第二部分：5分钟快速开始 2.1 环境准备 系统要求： 要求项 最低版本 推荐版本 Node.js（TypeScript用） 18.0.0 20.x LTS Python（Python用） 3.10 3.11+ 操作系统 Windows 10/macOS 12/Ubuntu 20.04 最新稳定版 要求项 要求项 最低版本 最低版本 推荐版本 推荐版本 Node.js（TypeScript用） Node.js（TypeScript用） 18.0.0 18.0.0 20.x LTS 20.x LTS Python（Python用） Python（Python用） 3.10 3.10 3.11+ 3.11+ 操作系统 操作系统 Windows 10/macOS 12/Ubuntu 20.04 Windows 10/macOS 12/Ubuntu 20.04 最新稳定版 最新稳定版 快速检查命令： 2.2 安装SDK Python安装（推荐方式）： 重要提示：Python SDK会自动捆绑Claude Code CLI，无需单独安装！ TypeScript安装： 2.3 配置API密钥 Agent SDK需要Anthropic API密钥才能运行。 方式一：环境变量（推荐） 方式二：.env文件 创建.env文件： 在代码中加载： 2.4 Hello World Agent 现在让我们创建第一个Agent！ Python版本 创建hello agent.py： 运行： 预期输出： TypeScript版本 创建src/hello agent.ts： 运行： 2.5 验证安装成功 如果你看到了Agent的回复，恭喜！安装成功！ 常见问题快速排查： 错误信息 原因 解决方案 ModuleNotFoundError: No module named 'claude agent sdk' SDK没装好 重新运行 pip install claude agent sdk Cannot find module '@anthropic ai/claude agent sdk' npm包没装好 重新运行 npm install Authentication failed API Key没配置 检查环境变量是否设置正确 错误信息 错误信息 原因 原因 解决方案 解决方案 ModuleNotFoundError: No module named 'claude agent sdk' ModuleNotFoundError: No module named 'claude agent sdk' SDK没装好 SDK没装好 重新运行 pip install claude agent sdk 重新运行 pip install claude agent sdk Cannot find module '@anthropic ai/claude agent sdk' Cannot find module '@anthropic ai/claude agent sdk' npm包没装好 npm包没装好 重新运行 npm install 重新运行 npm install Authentication failed Authentication failed API Key没配置 API Key没配置 检查环境变量是否设置正确 检查环境变量是否设置正确 Connection timeout 网络问题 检查网络连接，国内可能需要代理 第三部分：核心概念深度解析 3.1