AI Agent 搭建指南：从零开始 vibecoding 你的第一个Agent（附完整代码）

市面上的 Agent 教程要么太浅、要么太碎。真正能让你从我想做一个Agent到我做出了一个能用的 Agent的完整路径几乎找不到。干脆自己动手了vibecoding一个出来。把 Anthropic、OpenAI 还有各路高手的零散资料全部揉碎和我的搭档 Claude 一起硬是肝出了一套面向普通人的完整课程。目标就一个学完就能动手今天就做出你的第一个 Agent。1. Agent 是怎么工作的先搞清楚底层逻辑不然你根本不知道为什么要用 Agent以及什么时候该用 Agent。所有 Agent 的核心循环都是一样的用户输入 → LLM 思考 → LLM 决定回复还是调用工具→ 如果调用工具执行把结果传回 → 重复LLM 是大脑负责推理。工具是手负责执行具体动作计算器、网页搜索、文件读写。记忆是笔记本记录已经发生的事情。不管你用 LangGraph、CrewAI、Anthropic 的 SDK 还是 OpenAI 的 Agents SDK框架只是在这个循环上包了一层抽象本质没变。增强版 LLM普通 LLM 输入文本、输出文本。增强版 LLM 加了三个能力**工具Tools**模型可以调用的函数计算器、数据库、API、文件操作等。Anthropic 通过 input_schema 暴露工具OpenAI 用 function 对象包装参数。**检索Retrieval**从外部来源拉取相关信息搜索引擎、文档、向量数据库。**记忆Memory**通过消息历史或持久化存储在多次交互中保留信息。工作流 vs. 真正的 Agent选型的时候搞清楚这个区别很重要。工作流是确定性的你的代码控制执行流程同样的输入永远走同一条路适合步骤固定、定义明确的任务成本也低。Agent 是动态的LLM 自己决定下一步可以反复调用工具适合开放式任务但成本更高。正确的做法是先用简单的工作流试试看能不能满足需求再考虑升级成完全自主的 Agent。2. 五种工作流模式大部分问题其实根本不需要 Agent 就能解决。这五个模式是 Anthropic 文档记录、被业界广泛采用的常见方案每个都依赖增强版 LLM。模式一Prompt Chaining链式提示把任务拆成顺序执行的步骤每个 LLM 调用处理前一个的输出。在步骤之间加程序化的门卫来验证质量。适用场景任务能干净地分解成固定子任务。用速度换精度让每个 LLM 调用更简单。例子生成营销文案再翻译。写大纲、验证覆盖了关键主题、再写完整文档。模式二Routing路由对输入进行分类然后分发给专门的处理器。每个处理器有自己的优化 prompt。适用场景不同类别的输入需要完全不同的处理方式。客服工单分类是经典例子。模式三Parallelisation并行化同时跑多个 LLM 调用。Sectioning 把任务拆成独立的子任务并行处理Voting 跑同一个任务多次聚合结果获得更高置信度。适用场景子任务相互独立sectioning或者需要对关键决策达成共识voting。模式四Orchestrator-Workers编排器-工作者一个中心 LLM编排器动态拆分任务分发给 worker LLM。和并行化不同子任务不是预定义的编排器在运行时决定。适用场景复杂任务无法提前预知结构。跨多文件生成代码、研究任务、写报告。模式五Evaluator-Optimiser评估器-优化器一个 LLM 生成输出另一个评估并给出反馈。如果评估不通过反馈循环回去。反复直到满足质量标准。适用场景有明确评估标准迭代优化能带来可衡量价值的场景。翻译、代码生成、写作任务。3. 构建你的第一个 Agent这部分是文章的核心——怎么把我想要一个 Agent 帮我做 XYZ变成真实可用的东西。最简单的心法就五步把工作写下来决定它需要什么工具告诉模型怎么表现用 5 个真实例子测试只有失败了才加复杂度你不需要同时掌握五个框架才能搭 Agent。对普通人来说最好的起点就两个**Anthropic**如果你想要一个能操作文件、跑 shell 命令、做网页搜索、coding 能力强的能干的操作员**OpenAI**如果你想要一个开发体验干净、有托管工具、handoffs、guardrails、能快速上生产的 SDK这份指南主要讲这两个。最简心智模型构建 Agent 之前先回答这四个问题1. 要达成什么结果Agent 实际要产出什么例子“研究一个主题并写摘要”“读我的笔记并转成卡片”“看支持工单并正确路由”“对比产品并给我最佳选项”“审核内容并用自己的风格重写”2. 它需要什么信息需要网页搜索、文件、数据库、表格、CRM还是只要用户的消息3. 它可以执行什么操作只能回答只能搜索可以改文件可以发邮件可以写代码可以调用你自己的函数4. 它必须遵守什么规则语气、格式、约束、安全规则、遇到不确定怎么办、好的标准是什么。能清楚回答这四个问题通常一天内就能搭出第一版 Agent。用 AI 帮你设计 Agent正式动手之前先用 Claude 或 ChatGPT 帮你定义清晰。粘贴类似这样的内容I want to build an AI agent.My goal:[描述你想要它做什么]The user will ask things like:[加5个真实例子]The agent should have access to:[网页搜索 / 文件 / 计算器 / 自定义 API / 其他]It must always:[列出不可妥协的规则]It must never:[列出边界]Please turn this into:1. A clear agent spec2. A system prompt3. A tool list4. A first version roadmap5. 10 test cases这一个 prompt 就能把新手的模糊想法变成可执行的计划。Agent 设计公式每次设计都用这个结构Agent 角色 目标 工具 规则 输出格式例子**角色**加密项目研究助手**目标**查找准确信息并清晰总结**工具**网页搜索、文件搜索、计算器**规则**引用来源、不猜测、标注不确定性**输出格式**总结、风险、机会、最终判断这就是大多数有用 Agent 的基础。五种入门 Agent 类型新手别一上来就搞多 Agent 集群。先从这五个里挑一个1. 研究 Agent适用场景想让 Agent 收集信息并总结。例子“研究脚踝扭伤最好的康复训练”“找某个加密协议的最新动态”“对比三款笔记本电脑”需要的工具网页搜索、如果用自己的文档还要文件搜索、清晰的输出格式。2. 内容 Agent适用场景想让 Agent 写、改写、总结或转换内容。例子“把我的笔记转成通讯”“用我的品牌语气重写”“总结这个会议记录”需要的工具通常只要一个强的 system prompt可选加文件访问、加你的风格示例。3. 工作流 Agent适用场景想让 Agent 执行可重复的业务流程。例子“分类支持工单”“把线索路由到正确分类”“检查表单提交并生成回复草稿”需要的工具清晰的分类规则、有些场景还要自定义工具或 API 调用。4. 个人知识 Agent适用场景想让 Agent 用你自己的文档回答问题。例子“只用我的 PDF 回答”“搜我的笔记并解释这个主题”“找出所有提到这个客户的 reference”需要的工具文件搜索或 RAG、清晰的指令让 Agent 严格基于提供的材料。5. 操作 Agent适用场景想让 Agent 在某个环境中执行操作。例子“读这些文件并编辑”“搜网页、收集发现、保存报告”“跑 shell 命令并帮我 debug”需要的工具工具、权限、强的安全边界。Anthropic构建第一个 Agent 的最简路径Anthropic 的 Agent 工具链在你需要模型使用工具、在某个环境中操作时特别顺手。Claude Code 2025 年 2 月上线后来改名叫 Claude Agent SDK2026 年 3 月 GitHub 最新 release 是 v0.1.50。选 Anthropic 的场景优先选它如果你的 Agent 需要读、写、编辑文件用 shell 命令搜索网页用 MCP 工具做 coding 和技术活像个能干的助手一样一步步操作用 Anthropic 真正在做的事入门级来说你就做了三件事给 Claude 一个任务给 Claude 工具让 Claude 循环执行直到完成没了。入门例子研究总结 Agent假设你想要“一个能研究主题并给我写出干净报告的 Agent”设计计划**角色**高级研究助手**目标**查找准确信息并清晰总结**工具**网页搜索可选加文件访问**规则**引用来源说不确定的地方保持简洁**输出**要点总结 关键发现 风险或不确定性 最终结论这就是你的 system promptSYSTEM_PROMPT You are a careful research assistant.Your job is to help the user research topics accurately.Use tools when needed.Do not guess.If information is uncertain or incomplete, say so clearly.Always produce:1. Summary2. Key findings3. Risks or uncertainty4. Final conclusion然后用户可以问“研究最新的 AI Agent SDK”“对比 Anthropic 和 OpenAI 哪个适合新手搭 Agent”“找三个强来源并总结”这已经是一个可用的 Agent 了。OpenAI构建第一个 Agent 的最简路径OpenAI 2025 年 3 月 11 日发布了 Agents SDK配合 Responses API内置了网页搜索、文件搜索、电脑操作等工具。Python 包 openai-agents 2026 年 3 月版本是 0.13.1。选 OpenAI 的场景优先选它如果你的需求是一个非常干净的 Agent API简单的自定义函数工具内置托管工具specialist Agent 之间的 handoffsguardrails 和 tracing从原型到生产的平滑路径用 OpenAI 真正在做的事入门级来说你就做了四件事创建一个 Agent给他指令需要的话加工具用真实用户请求跑起来没了。入门例子支持分类 Agent假设你的目标是“读收到的支持请求判断是billing、technical还是sales”设计**角色**支持分类助手**目标**正确分类请求**工具**不用后续可能加 CRM 工具**规则**只选一个分类简短解释原因**输出**分类 原因代码from agents import Agent, Runneragent Agent( nameSupport Triage Agent, instructionsYou classify customer requests.Choose exactly one category:- billing- technical- salesReply with:1. Category2. One sentence explaining why,)result Runner.run_sync(agent, I was charged twice for my subscription this month.)print(result.final_output)这已经是一个有用的 Agent 了。入门例子加一个自定义工具假设你想要“在需要的时候帮用户计算值”from agents import Agent, Runner, function_toolfunction_tooldef calculate(expression: str) - str: import math allowed {k: v for k, v in math.__dict__.items() if not k.startswith(__)} return str(eval(expression, {__builtins__: {}}, allowed))agent Agent( nameMath Helper, instructionsHelp the user solve maths problems. Use the calculator tool when needed., tools[calculate],)result Runner.run_sync(agent, What is compound growth on 10000 at 5 percent for 8 years?)print(result.final_output)现在这个 Agent 不只是在聊天了它在通过工具执行动作。入门例子用托管工具OpenAI Agents SDK 也支持托管工具网页搜索、文件搜索、代码解释器新手可以理解成 SDK 文档里的预建能力直接 attach 到 Agent 上不用从头写。这意味着你可以搭这样的 Agent“搜这个主题的网页并总结”“搜我的文件并从中回答”“跑代码分析这个数据”定制 Agent 的检查清单新手常犯的错误是搭了个通用助手而不是具体的Agent。1. 把工作做窄❌ 不好“帮我处理业务的事”✅ 好“把销售通话总结成行动要点”“把线索分成热、温、冷”“研究加密项目并输出风险、催化剂、最终判断”2. 定义输出格式❌ 不好“给我一个答案”✅ 好“返回总结、证据、风险、下一步”“返回 JSONcategory、confidence、explanation”“返回 bullet list五个标题以下”3. 给例子想要特定语气、结构、分类质量的话例子很有用。告诉模型“这是三个好输出的例子”“这是五个请求分类的例子”“用这个精确的风格写”4.只在需要的时候加工具任务只是改写笔记就别加网页搜索。答案应该只来自 prompt 就别加文件访问。每个额外工具都会增加复杂度。5. 用真实 prompt 测试不要用理想的测试用真实用户会输入的那种混乱 prompt 测试。不要只测试“请分类这个技术问题”也要测试“my account is broken and i keep getting charged what do i do”这才是你真正能看到 Agent 实际表现的地方。你的构建路径**Step 1**写一句话描述 Agent 例子“我想要一个 Agent把我的粗糙笔记整理成干净的周报。”**Step 2**问 Claude 或 ChatGPT 帮你转成Agent specSystem promptTool list10 个测试 prompt**Step 3**搭最小可运行版本 不要多 Agent。不要复杂记忆。除非必要不要上 RAG。**Step 4**用 10 个真实例子测试**Step 5**一次改进一件事prompt输出结构例子工具记忆检索这个顺序很重要别搞混。不要犯这个错最大的错误是试图搭一个万能超级 Agent。不要一上来就网页搜索文件搜索数据库访问记忆多 Agent handoffs复杂 guardrails自定义 dashboard20 个工具从这些开始一个任务一个 Agent一个清晰的 prompt最多一两个工具五到十个真实测试用例不把自己搞复杂这才是正确的路。4. 怎么用好工具大多数人都把这件事搞复杂了。你只需要理解一件事工具就等于“AI 自己做不到的事”例子算数字搜网页读文件发邮件查数据库Step 1先问自己这需要工具吗加任何东西之前先问模型能单靠推理回答这个问题吗还是需要现实世界的数据或动作不需要工具的例子“改写这封邮件”“总结这段文字”“解释这个概念”需要工具的例子“现在天气怎么样”“搜最新新闻”“算复利”“从我的表格拉数据”规则需要外部数据或动作 → 用工具不需要 → 别加Step 2用 AI 帮你设计工具I am building an AI agent.My goal:[描述目标]Here is what I think the agent needs to do:[列出动作]Which of these require tools?What tools should I create?Keep them simple and minimal.Return:1. Tool list2. Tool descriptions3. Inputs required for each tool这能帮你省很多时间。Step 3保持简单 stupid❌ 差的工具manage_files(action, file, destination, overwrite, format, permissions)✅ 好的工具read_file(path)write_file(path, content)delete_file(path)规则一个工具 一个明确的任务Step 4告诉 Agent 什么时候用工具这是大多数人失败的地方。❌ 不好“计算器工具”✅ 好“当需要数学的时候用这个工具。不允许猜测计算结果。”Step 5让 Agent 失败然后修用真实测试跑“2^16 是多少”“算一下 10 年 7% 增长”如果不使用工具 → 修描述用得不对 → 修输入产生幻觉 → 规则定严格点5. 给 Agent 加记忆这件事也被严重过度复杂化了。你只需要理解两件事记忆就两种1. 短时记忆对话就是“到目前为止说了什么”你用默认配置就已经有了。2. 长时记忆外部知识就是“Agent 以后可以查的东西”例子你的笔记PDF文档数据库什么时候真正需要记忆问自己Agent 需要跨消息记住事情吗→ 是 → 短时记忆需要用外部文档吗 → 是 → 长时记忆否则 → 大概率不需要Step 1用 AI 帮你决定要不要加记忆I am building an AI agent.My goal:[目标]Does this agent need:1. Conversation memory?2. External knowledge (RAG)?If yes, explain why.If no, explain why not.Keep it simple.Step 2你有三个选项选项 A不用记忆先从这里开始大多数入门者的最佳选择70% 的场景够用选项 B对话记忆大多数 SDK 已经处理好了只要别 reset 消息就行选项 C基于文件的记忆简单 RAG上传文档用文件搜索工具Step 3不要用力过猛大错上向量数据库上 embeddings上复杂 pipeline在甚至不知道是否需要之前就上这些。规则如果 Agent 不用记忆就能工作 → 别加6. 让 Agent 跑起来这是 Agent 做得好不好、能不能用的关键。很多 Agent 做得很烂就是因为prompt 写得差不测试期望不现实Step 1用 AI 生成测试用例I built an AI agent with this goal:[目标]Create 15 realistic user inputs:- messy- vague- real-world styleAlso include:- edge cases- confusing inputs- bad inputsStep 2像真实用户那样测试不要测“请分类这个billing请求”要测“why tf did i get charged again”Step 3一次只修一件事失败的时候问prompt 不清楚输出格式模糊缺工具缺规则Step 4用 AI debug 你的 AgentHere is my agent:Here is what I asked:[input]Here is the output:[output]What went wrong?How do I fix it?Be specific.Step 5不要过早搞复杂在以下条件满足之前不要加多个 Agent复杂工作流自动化 pipeline直到你的简单版本能稳定工作7. 多 Agent 协作这件事很容易让你彻底跑偏。有人觉得“多 Agent 更强”错。永远从一个 Agent 开始。只有在以下情况才加更多任务明显可拆分一个 Agent 扛不住角色差异很大需要多 Agent 的三种情况1. 不同技能例子研究 Agent写作 Agent2. 清晰 pipeline例子输入 → 分析 → 写作 → 输出3. 不同权限例子一个 Agent 可以读数据一个 Agent 可以执行动作用 AI 帮你决定要不要多 AgentI built an AI agent.Here is its job:[描述]Should this be:1. A single agent2. Multiple agentsIf multiple:- what roles?- why?Keep it simple.最安全的模式Supervisor 模式用户 → 主 Agent →需要时调用其他 Agent不要一上来就用swarm完全自主的多 Agent 系统这些很容易坏。角色保持简单 stupid❌ 不好“AI 战略 Agent带动态认知分层”✅ 好“研究 Agent”“写作 Agent”慢速加 Agent从1 个 Agent然后最多 2 个 Agent只有看到真实好处才扩展。8. 收尾这篇文章最重要的结论是Agent 概念上简单落地起来却要求很高。Agent LoopLLM 思考、调用工具、重复50 行 Python 代码就能跑完。真正费功夫的是工具设计、错误处理、评估以及知道什么时候该用更简单的模式Prompt Chaining、Routing而不是完全自主的 Agent。三个可操作的结论1. 先搭一个从零开始的 Agent搞懂底层循环之后每个框架对你来说都是透明的而不是玄学。debug 问题的速度快得多选工具也更明智。2. 用能工作的最简单模式开始Prompt Chain 能处理大多数多步任务。Routing 能处理大多数分类后执行的工作流。只有当你需要 LLM 动态决定执行路径的时候才升级到自主 Agent。3. 及早投资工具设计和评估好工具的特征名字清晰、描述精准、错误消息结构化。这三样东西对 Agent 性能的提升比换模型或换框架有效得多。20 个好的测试用例比大量人工测试能抓到更多 bug。这个领域变化很快。MCP 不到一年就成了通用标准两个大厂都出了 Agent SDK新框架每月都在冒出来。但这份指南里的基础是稳定的Agent Loop、五种工作流模式、好工具的设计原则以及从简单开始的纪律。掌握这些你就能适应接下来出现的一切。你现在可以搭一个 Agent 了。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】