5分钟搭建第一个AI Agent：Claude Agent SDK实战指南

最近在折腾 Claude Agent SDK,忍不住想分享一下。

这东西真的太爽了。

一. 我为什么要折腾这个

说实话,我之前一直在用 Claude Code CLI,在终端里跟 AI 对话,让它帮我写代码、改 bug。

挺好用的,但有个问题。

每次都得手动打开终端,输入命令,等它跑完。我就想,能不能把这个能力嵌入到我自己的项目里?

比如做一个自动化运维工具,让 AI 自己去检查服务器状态、修复问题。

或者做一个代码审查机器人,每次提交代码自动帮我 review。

后来发现 Anthropic 出了个 Claude Agent SDK,就是把 Claude Code 的核心能力打包成了 Python 和 TypeScript 的库。

你可以用几行代码,就让 AI 帮你干活。

太符合我的需求了。

二. 第一次尝试,10 分钟翻车

我一开始以为很简单。

看了官方文档,写了几行代码:

import asynciofrom claude_agent_sdk import query, ClaudeAgentOptionsasync def main(): async for message in query( prompt="帮我找找项目里的 TODO 注释", options=ClaudeAgentOptions(allowed_tools=["Glob", "Grep"]) ): print(message)asyncio.run(main()) 

然后运行。

报错了:ModuleNotFoundError: No module named 'claude_agent_sdk'

我一拍脑袋,忘了装 SDK。

pip install claude-agent-sdk 

装完再跑,又报错:Not logged in · Please run /login

我去,还得配置 API key。

翻了半天文档才知道,需要设置环境变量:

export ANTHROPIC_API_KEY=sk-ant-your-key-here 

这次终于跑起来了。

但我发现一个问题,它输出的内容太多了,全是各种工具调用的日志,我只想看最终结果。

后来我改了一下代码:

async def main(): async for message in query( prompt="帮我找找项目里的 TODO 注释", options=ClaudeAgentOptions(allowed_tools=["Glob", "Grep"]) ): # 只打印最终结果 if hasattr(message, "result"): print(message.result) 

这次终于看到想要的输出了。

整个过程大概花了 10 分钟,主要是踩坑。

三. 真正的第一个 Agent:自动修 Bug

搞定基础配置后,我想做点实际的东西。

就做一个自动修 bug 的 Agent 吧。

我写了个有 bug 的文件 utils.py:

def calculate_average(numbers): if not numbers: return 0 total = 0 for num in numbers: total += num return total / len(numbers)def get_user_name(user): if user is None: return "" name = user.get("name") if name is None: return "" return str(name).upper() 

这代码看起来没问题,但其实有个隐藏的坑:calculate_average 函数如果传入空列表会返回 0,但这不符合数学定义(应该返回 None 或抛异常)。

然后我让 Agent 去找 bug:

import asynciofrom claude_agent_sdk import query, ClaudeAgentOptionsasync def main(): async for message in query( prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.", options=ClaudeAgentOptions( allowed_tools=["Read", "Edit", "Glob"], permission_mode="acceptEdits" # 自动批准文件编辑 ) ): if isinstance(message, AssistantMessage): for block in message.content: if hasattr(block, "text"): print(block.text) elif isinstance(message, ResultMessage): print(f"Done: {message.subtype}")asyncio.run(main()) 

跑起来后,我看到 Agent 的工作流程:

1. 先用 Read 工具读取 utils.py
2. 分析代码,发现了几个潜在问题
3. 用 Edit 工具修改文件
4. 输出最终结果

整个过程完全自动化,我只需要等结果。

最神奇的是,它不仅修复了我预期的 bug,还发现了几个我没注意到的边界情况。

比如 get_user_name 函数如果 user 不是字典类型会报错,它帮我加了类型检查。

这感觉真的像有个人在帮你写代码。

四. 踩过的几个坑

坑 1:API Key 配置

如果你用的是第三方 API 服务(比如 Cubence 这种代理服务),除了 ANTHROPIC_API_KEY,还得配置 ANTHROPIC_BASE_URL:

export ANTHROPIC_API_KEY=sk-your-keyexport ANTHROPIC_BASE_URL=https://api.cubence.com 

我一开始只设置了 key,结果一直连不上。

坑 2:权限模式

permission_mode 有几个选项:

• "acceptEdits":自动批准文件编辑
• "bypassPermissions":跳过所有权限检查
• 默认值:每次操作都会询问你

如果你要做自动化工具,一定要设置成 acceptEdits,不然每次都得手动确认,太麻烦。

坑 3:工具选择

allowed_tools 这个参数很重要。

如果你只是想让 Agent 读文件、搜索代码,就只给 ["Read", "Glob", "Grep"]。

千万别一股脑给所有工具,特别是 Bash。

我之前试过给它 Bash 权限,结果它为了"优化性能",自己跑去装了一堆依赖包。

虽然是好心,但我并不想让它乱动我的环境。

坑 4:异步编程

SDK 用的是异步 IO,所以必须用 async/await。

如果你对 Python 的异步编程不熟悉,可能会觉得有点绕。

我的建议是,照着官方示例写,别自己瞎改。

五. 实际能用来做什么

折腾了几天后,我总结了几个实际的应用场景:

1. 自动化代码审查

每次 PR 提交后,让 Agent 自动检查代码质量、安全漏洞、性能问题。

2. 运维助手

让 Agent 定期检查服务器状态、日志异常,发现问题自动修复或告警。

3. 文档生成

让 Agent 读代码,自动生成 API 文档、使用说明。

4. 数据分析

给 Agent 一个 CSV 文件,让它自动做数据清洗、统计分析、生成可视化图表。

说实话,这些场景以前也能做,但要写一堆代码。

现在用 Agent SDK,10 行代码搞定。

六. 和其他工具的对比

可能有人会问,这跟直接用 Claude API 有什么区别?

最大的区别是:Agent SDK 帮你处理了工具循环。

如果用普通的 Claude API,你得自己写代码:

1. 发送提示词
2. Claude 返回"我要调用某个工具"
3. 你执行工具,拿到结果
4. 把结果发回给 Claude
5. 重复步骤 2-4,直到完成

这个循环你得自己写,很麻烦。

Agent SDK 把这些全封装好了,你只需要告诉它"干什么",它自己搞定。

还有人问,跟 Claude Code CLI 有啥区别?

CLI 是交互式的,你在终端里跟 AI 对话。

SDK 是编程式的,你把它嵌入到自己的项目里。

我的用法是:日常开发用 CLI,生产环境用 SDK。

七. 快速开始指南

如果你也想试试,这是最快的上手方式:

1. 安装 SDK

pip install claude-agent-sdk 

2. 配置 API Key

export ANTHROPIC_API_KEY=your-api-key-here 

从这里获取 API key:https://platform.claude.com/

3. 写一个最简单的 Agent

新建 agent.py:

import asynciofrom claude_agent_sdk import query, ClaudeAgentOptionsasync def main(): async for message in query( prompt="列出当前目录的所有 Python 文件", options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]) ): if hasattr(message, "result"): print(message.result)asyncio.run(main()) 

4. 运行

python agent.py 

就这么简单。

八. 一些建议

1. 从小项目开始

别一上来就想做个复杂的系统。

先做一个只有单一功能的 Agent,比如"自动格式化代码"、“检查拼写错误”。

跑通了再慢慢加功能。

2. 控制好权限

生产环境一定要限制 Agent 的权限。

能用 Read 就别用 Edit,能用 Glob 就别用 Bash。

AI 再聪明,也可能犯错。

3. 记录日志

把 Agent 的所有操作都记录下来。

出问题的时候方便排查。

4. 设置超时

长时间运行的任务,记得设置超时。

别让 Agent 一直跑,浪费 token。

九. 写在最后

Claude Agent SDK 出来才几个月,已经挺成熟了。

我觉得这个方向很有前景。

以后每个开发者可能都会有几个自己的 Agent,帮你干各种重复性工作。

你只需要专注于创造性的部分。

如果你对 AI 编程感兴趣,强烈建议试试这个 SDK。

真的不难,折腾半天就能上手。

官方文档写得很详细:https://platform.claude.com/docs/zh-CN/agent-sdk/overview

GitHub 上也有很多示例项目:https://github.com/anthropics/claude-agent-sdk-demos

以上,既然看到这里了,如果觉得不错,随手点个赞、在看、转发三连吧～

想入门 AI 大模型却找不到清晰方向？备考大厂 AI 岗还在四处搜集零散资料？别再浪费时间啦！2026 年 AI 大模型全套学习资料已整理完毕，从学习路线到面试真题，从工具教程到行业报告，一站式覆盖你的所有需求，现在全部免费分享！

👇👇扫码免费领取全部内容👇👇

​

一、学习必备：100+本大模型电子书+26 份行业报告 + 600+ 套技术PPT，帮你看透 AI 趋势

想了解大模型的行业动态、商业落地案例？大模型电子书？这份资料帮你站在 “行业高度” 学 AI：

1. 100+本大模型方向电子书

2. 26 份行业研究报告：覆盖多领域实践与趋势

报告包含阿里、DeepSeek 等权威机构发布的核心内容，涵盖：

• 职业趋势：《AI + 职业趋势报告》《中国 AI 人才粮仓模型解析》；
• 商业落地：《生成式 AI 商业落地白皮书》《AI Agent 应用落地技术白皮书》；
• 领域细分：《AGI 在金融领域的应用报告》《AI GC 实践案例集》；
• 行业监测：《2024 年中国大模型季度监测报告》《2025 年中国技术市场发展趋势》。

3. 600+套技术大会 PPT：听行业大咖讲实战

PPT 整理自 2024-2025 年热门技术大会，包含百度、腾讯、字节等企业的一线实践：

• 安全方向：《端侧大模型的安全建设》《大模型驱动安全升级（腾讯代码安全实践）》；
• 产品与创新：《大模型产品如何创新与创收》《AI 时代的新范式：构建 AI 产品》；
• 多模态与 Agent：《Step-Video 开源模型（视频生成进展）》《Agentic RAG 的现在与未来》；
• 工程落地：《从原型到生产：AgentOps 加速字节 AI 应用落地》《智能代码助手 CodeFuse 的架构设计》。

二、求职必看：大厂 AI 岗面试 “弹药库”，300 + 真题 + 107 道面经直接抱走

想冲字节、腾讯、阿里、蔚来等大厂 AI 岗？这份面试资料帮你提前 “押题”，拒绝临场慌！

1. 107 道大厂面经：覆盖 Prompt、RAG、大模型应用工程师等热门岗位

面经整理自 2021-2025 年真实面试场景，包含 TPlink、字节、腾讯、蔚来、虾皮、中兴、科大讯飞、京东等企业的高频考题，每道题都附带思路解析：

2. 102 道 AI 大模型真题：直击大模型核心考点

针对大模型专属考题，从概念到实践全面覆盖，帮你理清底层逻辑：

3. 97 道 LLMs 真题：聚焦大型语言模型高频问题

专门拆解 LLMs 的核心痛点与解决方案，比如让很多人头疼的 “复读机问题”：

三、路线必明： AI 大模型学习路线图，1 张图理清核心内容

刚接触 AI 大模型，不知道该从哪学起？这份「AI大模型 学习路线图」直接帮你划重点，不用再盲目摸索！

路线图涵盖 5 大核心板块，从基础到进阶层层递进：一步步带你从入门到进阶，从理论到实战。

L1阶段:启航篇丨极速破界AI新时代

L1阶段：了解大模型的基础知识，以及大模型在各个行业的应用和分析，学习理解大模型的核心原理、关键技术以及大模型应用场景。

L2阶段：攻坚篇丨RAG开发实战工坊

L2阶段：AI大模型RAG应用开发工程，主要学习RAG检索增强生成：包括Naive RAG、Advanced-RAG以及RAG性能评估，还有GraphRAG在内的多个RAG热门项目的分析。

L3阶段：跃迁篇丨Agent智能体架构设计

L3阶段：大模型Agent应用架构进阶实现，主要学习LangChain、 LIamaIndex框架，也会学习到AutoGPT、 MetaGPT等多Agent系统，打造Agent智能体。

L4阶段：精进篇丨模型微调与私有化部署

L4阶段：大模型的微调和私有化部署，更加深入的探讨Transformer架构，学习大模型的微调技术，利用DeepSpeed、Lamam Factory等工具快速进行模型微调，并通过Ollama、vLLM等推理部署框架，实现模型的快速部署。

L5阶段：专题集丨特训篇 【录播课】

四、资料领取：全套内容免费抱走，学 AI 不用再找第二份

不管你是 0 基础想入门 AI 大模型，还是有基础想冲刺大厂、了解行业趋势，这份资料都能满足你！
现在只需按照提示操作，就能免费领取：

👇👇扫码免费领取全部内容👇👇

​

2026 年想抓住 AI 大模型的风口？别犹豫，这份免费资料就是你的 “起跑线”！