Claude Agent SDK 完整实战指南用可编程 Agent 让 Claude 自主完成代码任务【免费下载链接】easy-vibe vibe coding 101The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe导读本指南围绕 easy-vibe 课程stage-3/core-skills中的 Claude Agent SDK 完整指南 展开系统讲解如何把 Claude Code 的读文件、改代码、跑命令、查代码、浏览网页等能力封装进 Python/TypeScript 库让模型不再是一问一答而是接单干活、自己迭代直到完成。读完本文你将掌握query()与ClaudeSDKClient两种编程模式、内置工具矩阵、Hooks 钩子、子代理与 MCP 集成并能照搬一套可直接嵌入 CI/CD 的代码评审→安全扫描→自动修复→测试验证→报告生成企业级质量流水线。一、为什么需要 Agent SDK从你会说到你会做你可能已经用过 Claude 的基础 API发一条消息收一个回复就像聊天。但如果你希望 Claude 自己去读文件、执行命令、搜索代码、修复 bug、验证结果并持续迭代这种自主工作恰恰是基础 API 做不到的。Claude Agent SDK 正是为此而生它把 Claude Code 的全部能力——读写文件、执行命令、搜索代码、编辑文件、浏览网页——打包成一个可编程的库。你不再需要自己写工具调用循环tool-calling loopClaude 可以自主调用工具、自主迭代直到任务真正完成。一句话总结基础 SDK 是你问它答Agent SDK 是你派活它干活。从仓库的课程编排看这一能力位于 stage-3 进阶开发 的核心技能板块与 Claude Code 快速入门、MCP 完整指南、Agent Teams 团队协作 共同构成从会用 CLI到会编程化驱动 Agent的完整进阶路径。1.1 与基础 SDK 的本质差异先看代码差异一目了然。基础 anthropic SDK 需要你手写整个工具调用循环# 基础 anthropic SDK你必须自己写循环来处理工具调用 import anthropic client anthropic.Anthropic() response client.messages.create( modelclaude-sonnet-4-6, max_tokens1024, messages[{role: user, content: Fix the bug in auth.py}], tools[...] # 你必须自己定义工具 ) # Claude 请求调用某些工具 while response.stop_reason tool_use: result your_tool_executor(response.tool_use) # 你必须自己执行 response client.messages.create(tool_resultresult, **params) # 你必须自己回喂结果而 Agent SDK 一段代码搞定Claude 自己读文件、定位问题、编辑代码# Agent SDK一段代码完事Claude 自己读文件、找 bug、改代码 from claude_agent_sdk import query, ClaudeAgentOptions async for message in query( promptFix the bug in auth.py, optionsClaudeAgentOptions(allowed_tools[Read, Edit, Bash]), ): print(message) # Claude 自己读文件、定位问题、编辑代码对比项基础 anthropic SDKClaude Agent SDK工具执行你自己实现Claude 全权负责工具循环你自己实现内置 Agent 循环内置工具无全部自研读写文件、Bash、搜索等开箱即用上下文管理你自己维护自动压缩、自动管理最适用场景对话、生成、简单工具调用自主完成复杂任务1.2 与其他 Agent 框架的定位差异市面上的 Agent 框架很多——LangChain、LlamaIndex、CrewAI、AutoGPT 等。Claude Agent SDK 与它们的区别在于专精它不追求通用编排而是专注让 Claude 自主完成编程、文件操作与命令执行这类开发任务。仓库的 AI Agent 原理与工具调用附录 详细讲解了工具调用Tool Calling、规划与记忆等底层机制可作为理解本文概念的底层知识铺垫。框架最适用场景Claude Agent SDK让 Claude 自主完成编码、文件操作、命令执行LangChain构建流程高度可定制化的复杂通用 AI 应用CrewAI模拟多角色协作场景虚拟团队、角色扮演LlamaIndex构建连接企业数据与大模型的知识库问答系统二、安装与配置2.1 环境要求与安装Python需要 3.10通过 pip 安装pip install claude-agent-sdkTypeScript需要 Node.js 18通过 npm 安装npm install anthropic-ai/claude-agent-sdk2.2 认证方式最简单的方式是设置环境变量export ANTHROPIC_API_KEYyour-api-key同时支持云平台认证云平台启用方式AWS Bedrock设置CLAUDE_CODE_USE_BEDROCK1 AWS 凭据Google Vertex AI设置CLAUDE_CODE_USE_VERTEX1 GCP 凭据Microsoft Azure设置CLAUDE_CODE_USE_FOUNDRY1 Azure 凭据2.3 自定义 API 端点代理/网关/自托管如果你使用代理、网关或自托管 API 端点可以通过env参数覆盖默认 API 地址from claude_agent_sdk import query, ClaudeAgentOptions async for message in query( promptHello, optionsClaudeAgentOptions( env{ ANTHROPIC_BASE_URL: https://your-proxy.example.com, ANTHROPIC_API_KEY: your-api-key, } ), ): print(message)ClaudeAgentOptions没有直接的base_url参数但env字段可以把任意环境变量透传给底层的 Claude Code CLI。常用环境变量环境变量用途ANTHROPIC_BASE_URL自定义 API 端点代理、网关ANTHROPIC_API_KEYAPI 密钥ANTHROPIC_AUTH_TOKEN备选认证令牌ANTHROPIC_CUSTOM_HEADERS自定义请求头三、核心运行原理与两种编程模式Agent SDK 的运行原理可以浓缩为一句话收集上下文 → 执行动作 → 验证结果 → 迭代。这正是人类开发者的工作方式先读代码再改代码然后跑测试验证如果出错继续迭代。Agent SDK 把这个循环自动化了。3.1 模式一query()—— 无状态适合一次性任务import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): async for message in query( prompt这个目录下有哪些文件, optionsClaudeAgentOptions(allowed_tools[Bash, Glob]), ): if hasattr(message, result): print(message.result) asyncio.run(main())每次调用query()都是一个全新会话互不共享上下文适合单发任务。3.2 模式二ClaudeSDKClient/ 会话恢复 —— 有状态适合多轮对话当你需要跨多轮保持上下文时比如先让 Claude 读某个模块再让它找到所有调用该模块的地方——第二轮它仍记得第一轮读到的内容。通过resume恢复会话import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): session_id None # 第 1 轮读取认证模块代码 async for message in query( promptRead the authentication module code, optionsClaudeAgentOptions(allowed_tools[Read, Glob]), ): if hasattr(message, subtype) and message.subtype init: session_id message.session_id # 第 2 轮基于之前上下文继续 async for message in query( promptFind all places that call it, optionsClaudeAgentOptions(resumesession_id), ): if hasattr(message, result): print(message.result) asyncio.run(main())关键点从subtype init的初始化消息中捕获session_id后续用resumesession_id续接。四、内置工具矩阵开箱即用这是 Agent SDK 最出色的部分之一——你无需实现任何工具Claude 可直接使用工具能力典型用途Read读取文件查看代码、读取配置Write创建文件生成新文件Edit精确编辑文件修 bug、重构Bash执行终端命令跑测试、装依赖、git 操作Glob按模式查找文件**/*.py、src/**/*.tsGrep正则搜索内容找函数定义、TODOWebSearch网页搜索查文档、找解决方案WebFetch抓取网页内容阅读在线文档Task启动子代理并行处理子任务用allowed_tools控制 Agent 可用工具集实现最小权限# 只读 Agent能勘察不能修改 options ClaudeAgentOptions( allowed_tools[Read, Glob, Grep], permission_modebypassPermissions ) # 全功能 Agent可读、可写、可执行命令 options ClaudeAgentOptions( allowed_tools[Read, Write, Edit, Bash, Glob, Grep] )permission_mode在此起到权限模式开关的作用bypassPermissions代表跳过权限确认配合只读工具集等于只看不改后续流水线还会用到acceptEdits允许自动接受文件编辑但保留对命令的确认。五、进阶特性5.1 Hooks 钩子在关键节点注入你的逻辑Hooks 允许你在 Agent 执行的关键时刻注入自定义代码——例如日志记录、拦截危险操作、审计文件变更。支持的钩子类型包括PreToolUse工具执行前、PostToolUse工具执行后、StopAgent 停止时、SessionStart、SessionEnd等。from datetime import datetime from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher # 每次文件被修改时记录审计日志 async def log_file_change(input_data, tool_use_id, context): file_path input_data.get(tool_input, {}).get(file_path, unknown) with open(./audit.log, a) as f: f.write(f{datetime.now()}: modified {file_path}\n) return {} async def main(): async for message in query( promptRefactor utils.py for better readability, optionsClaudeAgentOptions( permission_modeacceptEdits, hooks{ PostToolUse: [ HookMatcher(matcherEdit|Write, hooks[log_file_change]) ] }, ), ): if hasattr(message, result): print(message.result)注意HookMatcher的两个字段matcher是匹配工具名的正则表达式这里匹配Edit|Writehooks是命中的回调函数列表。实际用途审计日志记录 Agent 执行的每一个操作安全拦截阻止对关键文件的修改即时通知Agent 任务完成时发消息成本监控统计工具调用次数与 token 用量5.2 子代理Subagents用专家拆解大任务当任务足够复杂你可以定义多个专业化子代理让主代理把子任务委派给它们。每个子代理拥有独立的系统提示词与工具权限相互隔离。from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition async for message in query( promptUse the code-reviewer agent to review this projects code quality, optionsClaudeAgentOptions( allowed_tools[Read, Glob, Grep, Task], agents{ code-reviewer: AgentDefinition( description资深代码评审员负责质量与安全评审, promptAnalyze code quality, identify potential issues, and provide improvement suggestions., tools[Read, Glob, Grep], ), test-writer: AgentDefinition( description测试专家负责编写单元测试, promptWrite unit tests for functions that are missing tests., tools[Read, Write, Bash], ), }, ), ): if hasattr(message, result): print(message.result)子代理的消息带有parent_tool_use_id字段方便追踪每条消息来自哪个子代理。关于单主代理多个子代理与多 Agent 平级协作团队两种拓扑的区别可进一步参考仓库中的 Agent Teams 完整指南。5.3 MCP 集成连接外部世界通过 Model Context ProtocolMCP你的 Agent 可以连接数据库、浏览器、外部 API 等系统。社区已有大量现成 MCP 服务器可直接使用仓库中的 MCP 完整指南 详细讲解了 STDIO、HTTP、SSE 三种传输模式与项目级/用户级配置方法。# 接入 Playwright让 Agent 能操作浏览器 async for message in query( promptOpen example.com and describe what you see, optionsClaudeAgentOptions( mcp_servers{ playwright: { command: npx, args: [playwright/mcplatest] } } ), ): if hasattr(message, result): print(message.result)常见 MCP 集成场景Playwright浏览器自动化、页面抓取、表单填写PostgreSQL/MySQL直接查询与操作数据库Slack/Email发送通知与消息GitHub管理 PR、Issue、仓库六、能做什么五个实战场景场景 1自动修 bug 代理给它一个 bug 描述它能定位代码、分析问题、修复并跑测试验证async for message in query( promptUsers report occasional HTTP 500 errors during login. Investigate and fix code under src/auth/, optionsClaudeAgentOptions( allowed_tools[Read, Edit, Bash, Glob, Grep], permission_modeacceptEdits, ), ): print(message)Claude 会 grep 搜索日志、阅读相关代码、定位错误、修改代码并运行测试确认修复生效。场景 2代码评审代理构建只读的代码评审代理不产生任何修改async for message in query( promptReview code under src/ with focus on security vulnerabilities, performance issues, and coding conventions, optionsClaudeAgentOptions( allowed_tools[Read, Glob, Grep], permission_modebypassPermissions, ), ): if hasattr(message, result): print(message.result)场景 3CI/CD 集成在 CI 流水线中让 Agent 分析失败测试并尝试自动修复async for message in query( promptRun npm test, analyze failing test cases, and fix the code so all tests pass, optionsClaudeAgentOptions( allowed_tools[Read, Edit, Bash, Glob], max_turns20, ), ): print(message)这是 Agent SDK 相比 CLI 的一大优势——CLI 适合人坐在终端前而 SDK 天然适合嵌入自动化工作流。max_turns20限制了 Agent 最多迭代 20 轮防止失控。场景 4调研代理让 Agent 上网搜索、阅读文档、汇总信息并产出报告async for message in query( promptResearch mainstream Python Web frameworks in 2026. Compare FastAPI, Django, and Litestar, then write a technical selection report to report.md, optionsClaudeAgentOptions( allowed_tools[WebSearch, WebFetch, Write], ), ): print(message)场景 5带浏览器能力的全栈开发代理通过 MCP 接入 PlaywrightAgent 不仅能写代码还能打开浏览器验证结果async for message in query( promptFix the homepage style issue, then open a browser and take screenshots to verify the result, optionsClaudeAgentOptions( allowed_tools[Read, Edit, Bash], mcp_servers{ playwright: { command: npx, args: [playwright/mcplatest] } }, ), ): print(message)场景速查表场景核心工具难度自动修 bugRead, Edit, Bash, Grep入门代码评审Read, Glob, Grep入门CI/CD 自动修复Read, Edit, Bash进阶技术调研报告WebSearch, WebFetch, Write入门浏览器自动化MCP (Playwright)进阶多代理协作Task AgentDefinition高级数据库操作MCP (PostgreSQL/MySQL)进阶邮件/通知助手MCP (Slack/Email)进阶七、什么时候该用 Agent SDK并非所有场景都需要 Agent SDK选对工具很重要你想做的事推荐工具简单对话、文本生成、翻译基础anthropicSDK一次性工具调用查天气、算数基础anthropicSDK自主完成多步骤开发任务Agent SDK嵌入 CI/CD 流水线Agent SDK构建操作文件系统的应用Agent SDK日常交互式开发Claude Code CLI一次性快速任务Claude Code CLI总结如果你的任务需要 Claude亲手干活读文件、改代码、跑命令用 Agent SDK如果只是问答需求基础 SDK 就够了。八、企业级实战构建代码质量防护流水线前面的场景都是单 Agent 单任务。真实企业环境需要的是完整流水线——多个 Agent 串联每阶段有清晰的输入/输出契约外加审计、回滚与通知。下面构建一个真实场景每次提交 PR 后自动执行代码评审 → 安全扫描 → 自动修复 → 测试验证 → 报告生成的完整流水线。8.1 架构设计PR 提交 │ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Code Review │───▶│ Security Scan│───▶│ Auto Fix │ │ Agent │ │ Agent │ │ Agent │ │ 只读 │ │ 只读 │ │ 可写 │ └─────────────┘ └─────────────┘ └─────────────┘ │ ▼ ┌─────────────┐ ┌─────────────┐ │ Test Verify │───▶│ Report Build │ │ Agent │ │ Agent │ │ (Bash) │ │ (Write) │ └─────────────┘ └─────────────┘ │ ▼ Slack 通知核心理念每个 Agent 只做一件事权限最小化结果按顺序传递。8.2 步骤 1定义流水线骨架与公共审计钩子import asyncio import json from datetime import datetime from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher # 审计日志记录每个 Agent 的每个操作 audit_log [] async def audit_hook(input_data, tool_use_id, context): audit_log.append({ time: datetime.now().isoformat(), tool: input_data.get(tool_name), input: input_data.get(tool_input, {}), }) return {} # 公共钩子配置所有 Agent 共享审计能力 audit_hooks { PostToolUse: [HookMatcher(matcher.*, hooks[audit_hook])] }8.3 步骤 2代码评审 Agent只读async def run_code_review(pr_diff: str) - str: 只读 Agent评审代码质量并输出结构化报告 result_text async for message in query( promptfReview the following PR diff from these dimensions: 1. Code conventions: naming, formatting, comments 2. Logic issues: edge cases, null pointer risks, race conditions 3. Performance risks: N1 queries, memory leaks, unnecessary loops 4. Maintainability: oversized functions, unclear responsibilities, magic numbers PR Diff: {pr_diff} Output JSON format: {{issues: [{{severity: high/medium/low, file: ..., line: ..., description: ...}}], summary: ...}}, optionsClaudeAgentOptions( allowed_tools[Read, Glob, Grep], permission_modebypassPermissions, hooksaudit_hooks, max_turns10, ), ): if hasattr(message, result): result_text message.result return result_text8.4 步骤 3安全扫描 Agent只读async def run_security_scan() - str: 只读 Agent专注漏洞扫描 result_text async for message in query( promptScan the project code for security vulnerabilities: 1. SQL injection, XSS, CSRF 2. Hardcoded keys or credentials 3. Insecure dependency versions 4. Missing permission checks Output JSON: {{vulnerabilities: [{{severity: critical/high/medium, type: ..., file: ..., description: ..., fix_suggestion: ...}}]}}, optionsClaudeAgentOptions( allowed_tools[Read, Glob, Grep, Bash], permission_modebypassPermissions, hooksaudit_hooks, max_turns15, ), ): if hasattr(message, result): result_text message.result return result_text8.5 步骤 4自动修复 Agent可写async def run_auto_fix(review_result: str, security_result: str) - str: 可写 Agent根据评审与扫描结果自动修复代码 result_text async for message in query( promptfFix code according to the following review results: Code review report: {review_result} Security scan report: {security_result} Fix rules: 1. Only fix issues with severity high or critical 2. Run related tests after each change to ensure no existing functionality is broken 3. Do not refactor unrelated code, apply minimal fixes only 4. Output the list of modified files after completion, optionsClaudeAgentOptions( allowed_tools[Read, Edit, Bash, Glob, Grep], permission_modeacceptEdits, hooksaudit_hooks, max_turns30, ), ): if hasattr(message, result): result_text message.result return result_text注意这里的关键约束只修 high/critical 级别问题、每次改动后跑相关测试、不做无关重构——通过提示词把修复边界显式写死。8.6 步骤 5测试验证 报告生成async def run_test_and_report(fix_result: str) - str: 运行测试并生成最终报告 result_text async for message in query( promptfExecute these actions: 1. Run the full test suite (npm test or pytest) 2. Compute test pass rate 3. Generate a Markdown quality report into pr-report.md, including: - Count of issues found in code review and severity distribution - Number of security vulnerabilities - Auto-fix changes: {fix_result} - Test pass rate - Final conclusion: whether merge is recommended, optionsClaudeAgentOptions( allowed_tools[Read, Bash, Write, Glob], hooksaudit_hooks, max_turns15, ), ): if hasattr(message, result): result_text message.result return result_text8.7 步骤 6串联完整流水线import subprocess async def run_pipeline(): 完整 PR 质量防护流水线 print( 阶段 1/4代码评审...) pr_diff subprocess.run( [git, diff, main...HEAD], capture_outputTrue, textTrue ).stdout review_result await run_code_review(pr_diff) print(️ 阶段 2/4安全扫描...) security_result await run_security_scan() print( 阶段 3/4自动修复...) fix_result await run_auto_fix(review_result, security_result) print(✅ 阶段 4/4测试验证 报告生成...) report await run_test_and_report(fix_result) # 保存审计日志 with open(audit-log.json, w) as f: json.dump(audit_log, f, indent2, ensure_asciiFalse) print(f流水线结束审计日志已保存{len(audit_log)} 条操作记录) return report asyncio.run(run_pipeline())8.8 企业设计原则复盘这条流水线体现了几个关键的企业级设计原则最小权限代码评审与安全扫描 Agent 是只读的绝无可能误改代码只有自动修复 Agent 拥有写权限且被acceptEdits约束。可审计性每个 Agent 的每一步操作都通过 Hooks 记录。一旦出问题你能追踪到是哪个 Agent 在什么时间做了什么。结果串联每个 Agent 的输出成为下一个 Agent 的输入。评审结果喂给自动修复修复结果喂给测试验证。每阶段都有清晰的输入/输出契约。成本控制每个 Agent 都设置max_turns上限防止失控循环。生产环境中还可以增加max_budget_usd做预算控制。可扩展性想加一个阶段比如文档检查 Agent或性能测试 Agent新增一个函数插进流水线即可。这个模型可直接嵌入 GitHub Actions 或 GitLab CI每次 PR 自动触发真正实现AI 加持的代码质量防线。九、错误处理Agent SDK 提供了明确的异常类型便于在生产环境构建健壮的容错逻辑from claude_agent_sdk import query, CLINotFoundError, ProcessError try: async for msg in query(promptAnalyze code): print(msg) except CLINotFoundError: print(Claude Code CLI 未安装请先安装。) except ProcessError as e: print(f进程异常退出退出码{e.exit_code})CLINotFoundError底层 Claude Code CLI 未安装时抛出ProcessError底层进程异常退出时抛出可通过e.exit_code读取退出码十、总结Claude Agent SDK 的核心价值在于把模型推理升级为受控执行。它不只是生成文本而是在一套可审计、可约束的工具系统内真正完成任务。好的 Agent 应用 清晰的工具设计 明确的任务边界 适当的人类监督。工具给 Agent 能力边界给 Agent 约束监督给你信心三者缺一不可。本课程的相关章节可继续深入想掌握 MCP 协议细节与服务器配置阅读 MCP 完整指南想了解多 Agent 平级协作的团队模式阅读 Agent Teams 完整指南想从原理层面理解工具调用、规划与记忆机制阅读 AI Agent 原理与工具调用附录。【免费下载链接】easy-vibe vibe coding 101The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考