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

优质文章学习记录

— 13 min read

最近在折腾 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 大核心板块，从基础到进阶层层递进：一步步带你从入门到进阶，从理论到实战。
img
L1阶段:启航篇丨极速破界AI新时代
L1阶段：了解大模型的基础知识，以及大模型在各个行业的应用和分析，学习理解大模型的核心原理、关键技术以及大模型应用场景。
img
L2阶段：攻坚篇丨RAG开发实战工坊
L2阶段：AI大模型RAG应用开发工程，主要学习RAG检索增强生成：包括Naive RAG、Advanced-RAG以及RAG性能评估，还有GraphRAG在内的多个RAG热门项目的分析。
img
L3阶段：跃迁篇丨Agent智能体架构设计
L3阶段：大模型Agent应用架构进阶实现，主要学习LangChain、 LIamaIndex框架，也会学习到AutoGPT、 MetaGPT等多Agent系统，打造Agent智能体。
img
L4阶段：精进篇丨模型微调与私有化部署
L4阶段：大模型的微调和私有化部署，更加深入的探讨Transformer架构，学习大模型的微调技术，利用DeepSpeed、Lamam Factory等工具快速进行模型微调，并通过Ollama、vLLM等推理部署框架，实现模型的快速部署。
img
L5阶段：专题集丨特训篇 【录播课】
img


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

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

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

​

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

Read more

从低代码到 AI 智能体：VTJ.PRO 2.0 深度解析

技术白皮书 版本 1.0 | 2026年3月 摘要 随着企业数字化转型进入深水区，软件开发效率与质量的双重压力推动着开发工具的持续演进。VTJ.PRO 作为一款 AI 驱动的 Vue3 低代码开发平台，在 2026 年初发布的 2.0 版本中实现了从“低代码工具”到“AI 原生应用开发平台”的质变跃迁。本白皮书将深入解析 VTJ.PRO 2.0 的核心架构、技术创新及其实践价值，揭示其如何通过“AI 智能体+前后端一体+企业级工程化”的三位一体架构，重新定义现代应用开发范式。 第一章：背景与愿景 1.1 低代码开发的演进困局 传统低代码平台在过去十年中虽然显著提升了开发效率，但也面临三大核心挑战： 平台锁定风险：多数平台生成代码依赖私有运行时，一旦采用便难以脱离，

国产FPGA厂家安路开发工具TD使用手册详细版

FPGA系统学习详细版资料包，整理超多资料，整理不易，链接随时有可能失效，先下载再学习 网盘链接：https://pan.baidu.com/s/1rDsLAXGj8WbX82teSkhuIw?pwd=1234 提取码: 123 国产FPGA安路TD（TangDynasty）工具使用方法全流程详解 TD（TangDynasty）是安路科技自研的FPGA/FPSoC集成开发环境，覆盖RTL输入→综合→布局布线→时序分析→比特流生成→下载调试全流程，支持Windows/Linux系统，适配EG、ELF、SF1、DR1等安路全系列芯片。以下从环境搭建、工程创建、设计输入、综合、约束、布局布线、仿真、下载调试、高级功能、常见问题等维度，提供最详细的操作方法。 一、TD工具安装与环境准备 1.1

【论文笔记】Scalable Defense against In-the-wild Jailbreaking Attacks with Safety Context Retrieval

论文信息 论文标题： Scalable Defense against In-the-wild Jailbreaking Attacks with Safety Context Retrieval - ICML 2025 论文作者： Taiye Chen , Zeming Wei , Ang Li , Yisen Wang - PKU 论文链接：http://arxiv.org/abs/2505.15753 关键词： LLM Safety, Jailbreaking, RAG 研究背景 尽管大语言模型（LLMs）经过了人类反馈强化学习（RLHF）等安全对齐技术处理，但仍易受到“越狱攻击”（Jailbreaking Attacks）的威胁，即通过精心设计的提示词诱导模型产生有害输出。

AI绘画报错

提示输出验证失败：CheckpointLoaderSimple: - 值不在列表中：ckpt_name: 'v1-5-pruned-emaonly-fp16.safetensors' 不在 ['anything-v5-PrtRE.safetensors'] 中 模型文件夹里面没模型 这是官方链接：v1-5-pruned-emaonly.safetensors https://huggingface.co/runwayml/stable-diffusion-v1-5/tree/main 点击同一行的小下载箭头。然后把文件放在：models/checkpoints文件夹里 你还需要标准的VAE文件，也就是：vae-ft-mse-840000-ema-pruned.safetensors https://huggingface.co/stabilityai/sd-vae-ft-mse-original/tree/main 这个文件放在：models/vae文件夹里 现在你已经拥有运行所需的一切了。慢慢来。你最初生成的图片会很糟糕。但是继续尝试，很快你就能得到很棒的结果。