ai agent开发学习路线

很多人卡在同一个地方：模型能问答，但一让它自己调工具、多轮跑任务，就乱、就贵、就查不出错在哪。这篇不堆概念，只给一条按周推进的学习顺序——每一步该练什么、练到什么程度算过关、什么情况下该回头补基础。适合有基本编程能力、想从调用 API 走到能交付 Agent 的开发者。

很多人卡在同一个地方：模型能问答，但一让它自己调工具、多轮跑任务，就乱、就贵、就查不出错在哪。你会写提示词，也能把 API 调通，可一旦任务需要模型自己决定下一步做什么，整套东西就开始失控。这篇不堆概念，只给一条按周推进的学习顺序：每一步该练什么、练到什么程度算过关、什么情况下该回头补基础。

适合对象：有基本编程能力、能看懂接口文档、想从「调用 API」走到「能交付 Agent」的开发者。不适合完全不写代码的人，也不适合只想接个现成机器人用的人。整条路线大概分四段，每段都有明确的验收标准，练到了就走下一步，没到就停在那一段，别急着上框架。

先分清：Agent 开发和调 API 差在哪

单次调用是「输入→输出」，你关心的是提示词写得准不准。Agent 多了循环、状态和工具选择这三样东西，难点就从写提示词转移到了控制流程：什么时候该再调一次模型、上一轮的结果要不要留、工具选错了谁来兜。这个转变不完成，后面学什么框架都是在沙子上盖楼。

循环

模型给出动作、你执行、把结果送回模型，直到它认为任务结束，这个圈要转几圈由你的控制逻辑决定。

状态

任务跑到现在，目标是什么、做完哪几步、还剩哪几步、有哪些硬约束，这些要显式维护，不能靠对话历史兜着。

工具选择

多个工具摆在面前时，由模型判断该用哪个、参数怎么填，你的活儿是把工具描述写清楚并把执行结果稳定回灌。

判断自己该不该学：如果你手头的任务一次模型调用就能答完，那不需要 Agent，硬上只会更贵更慢还更难查错。真正值得上 Agent 的，是那种需要多步、每步结果会影响下一步、且中间要碰外部系统的任务。想先把概念对齐，可以对照站内「什么是 AI Agent」相关词条看一遍，再决定往哪个方向投入。

第一段：把工具调用跑通，不求聪明只求闭环

这一段的目标不是让模型变聪明，而是让闭环跑起来。选两个最简单的工具：一个固定参数的查询类（比如按城市名查天气那种结构），一个纯计算类（比如做个加减乘除）。只验证一件事——模型能不能给出格式正确的参数，你能不能把执行结果回灌回去，然后模型能不能基于结果继续往下答。

1. 写死工具描述把每个工具的名字、用途、参数类型写成模型能读懂的一段说明，别偷懒省略。参数尽量少，能用一个字符串解决的就别拆成五个字段。
2. 跑同一问题多遍同一个问题连跑几次，看参数格式是否每次都稳定。格式在多数时候对、偶尔崩，说明你的描述里有歧义，回去改描述而不是换模型。
3. 记录原始交互把每次请求和响应原样落盘或打日志，尤其是模型返回的工具调用片段。这是你后面所有排查的底稿。
4. 故意造一次错手动改一个不存在的城市名，看链路怎么反应。如果你自己都得翻半天日志才看出是哪一步崩的，说明可观测性不够，先补上再往下走。

验收标准就两条：同一个问题连跑几次参数都对；错的时候你能从日志里立刻分清是模型给错参数，还是你解析错了结构。这个阶段不要接向量库、不要上多智能体，加了只会把问题藏进更深的层里，到时候你连错在哪一层都说不清。

第二段：上下文和状态，Agent 真正翻车的地方

多轮任务里最先出问题的是「聊到一半忘了前面做过什么」。人的直觉是把历史对话全量塞回去，但这样上下文会越来越长，既贵又容易把关键信息淹掉。要练的是另一种做法：把历史压缩成「任务状态 + 最近几步」。状态是结构化的，最近几步是原始的，两者分开对待。

具体做法是列一张自己的状态表，每次调模型只喂这张表和最近一轮的工具结果。表里固定放四样东西，不增不减，多了就说明你在往里塞不该塞的东西。

什么情况下不适用：任务步数很少（两三步以内）且上下文不长的场景，做这套治理是过度设计，直接把原话带过去就行。判断依据是「如果全量塞回去，长度会不会撑到影响回答质量」，不会就别折腾。上下文为什么会丢、还有哪些替代做法，站内有专门篇章，这里只给实操顺序。

第三段：报错、超时和成本，会被拖垮的三件事

Agent 跑起来的头号杀手不是模型不行，是循环退不出去。模型觉得上一步没做好，就再调一次工具，再失败，再调，一晚上额度就这么烧完了。第二号杀手是工具返回太长，把上下文撑爆，后面模型开始胡说。第三号才是模型本身的能力问题。所以排查要按顺序来，别一上来就换模型。

• 错误先分类：限流类、网络类可以退避重试，参数错、鉴权错、工具不存在这类重试一万次也没用，直接终止并报出来。
• 每一步都设超时和最大循环次数，两个上限都要有，超了就退出并记录原因，别让它自己决定什么时候停。
• 成本在开发期就量：按「平均步数 × 每步 token」估算，而不是看单次调用的标价，多步任务的真实开销全在步数上。
• 排查顺序固定：先看循环有没有退出，再看工具返回是不是太长，再看状态表有没有带错，最后才怀疑模型能力。

估算方法和现成的计算工具在站内成本计算页，数字这类东西别凭记忆，去那边核对当时的口径。要注意的是，不同任务的平均步数差得很远，拿别人的数字套自己的场景基本没意义，得拿你自己那几轮真实日志去算。

第四段：能交付才算学会，练一个完整小项目

前三段都是零件，这一段是把零件装成能交出去的东西。选题原则很简单：你自己每天会用、失败了也不心疼的小场景。比如把一份固定格式的资料整理成表格并落地存档，或者把一批条目按规则分类打标。别一上来就做通用助手，那个做不完也验不出对错。

项目必须有的三样东西，缺一样都还停留在 demo 阶段：可观测日志，每一步的输入输出都能翻出来；失败可重放，拿同一份输入能复跑一遍定位问题；人工兜底，关键步骤可以暂停等确认，而不是闷头跑到底。

验收标准：换一个人按你的说明能跑起来，跑挂了他能看懂日志知道卡在哪。做不到这条，说明还停在 demo 阶段。不适用提醒：纯粹内部试验用的小工具，可以砍掉重放和兜底，但你要清楚这是欠债不是设计，别把简化版当成标准做法向外推广。

框架什么时候学：别一上来就啃编排

顺序建议很明确：先用原生调用手写一遍循环，知道每一步发生什么，再去用框架省事。反过来做，你会变成只会配参数、出了问题完全不知道从哪查的人。手写那一遍不用多完美，能跑通两工具闭环就够，重点是建立对每一步的直觉。

• 工具超过五六个、手写分发开始吃力时，可以考虑上框架。
• 需要多分支流程或人工介入节点时，框架的图结构确实省事。
• 团队里不止你一个人维护时，统一编排方式比个人手写更稳。
• 选型看四点：中间步骤能不能看见、出错信息可读不可读、模型和工具能不能替换、退出成本高不高。

这四点里最容易忽略的是退出成本。用了某套编排之后，想把逻辑搬走要重写多少，提前问自己一句。把框架和 SDK 的区别先弄清再选，站内有篇章专门讲这个，别把「框架」当成必选项，它只是省事的手段之一。

常见走弯路信号，出现就该回头

学习过程中有几个信号很典型，出现任何一个，都说明你在往错的方向使劲，先停下来回头补，比继续往前堆功能划算。

• 提示词越写越长还是不稳定——说明你缺的是流程控制，不是措辞技巧，回去补状态管理那一段。
• 几乎所有问题都靠换模型解决——说明你没定位到根因，是参数、上下文还是工具定义的问题，先分清再动手。
• 本地能跑、换个环境就挂——说明依赖了临时状态或本地文件，该补配置与状态管理。
• 说不清每步花了多少钱——该停下加用量统计，而不是继续往上加功能。

这些信号有个共同点：它们都在提示你「问题在结构不在细节」。判断类的东西都有边界，如果你的任务本身就是单次问答性质，上面第一条不适用，那时候提示词长一点确实能解决问题，不用硬套这条。

一张自检清单：确认自己走到哪一步了

下面五项，缺哪项就回对应那段补，别跳着学。这五项是按顺序递进的，后一项默认前一项已经过了。

• 能独立跑通两工具闭环，且参数错误可定位到具体哪一层。
• 能说清当前任务的步数上限和退出条件，不是靠模型自己决定停。
• 错误会分类处理，有重试上限和超时设置。
• 能量出平均步数与每步开销，且知道钱主要花在哪一段。
• 能交出带日志和人工兜底的可运行小项目，别人接手能跑。

五项目测下来都过了，说明你已经从「会调 API」走到了「能交付 Agent」。接下来才是挑框架、做多智能体、接更复杂的工具链这些事。反过来，如果第五项过不了，前面四项再熟也只是零件堆得好看。想横向看看别人怎么做的、哪些中转和工具适合拿来练手，可以去站内相关目录核对当时的清单。