搜「ai agent从零构建大模型智能体教程」的人,八成已经看过几篇讲 ReAct 和 Function Calling 的文章,动手时却卡在很具体的地方:工具描述写在哪个字段、循环什么时候停、跑出来的结果怎么判断是不是真成了。这篇不铺概念,按一条能跑通的线往下走,每一步告诉你验收标准是什么,跑到哪一步该考虑收手。
搜「ai agent从零构建大模型智能体教程」的人,八成已经翻过几篇讲 ReAct 和 Function Calling 的文章。概念看着都懂,一动手还是卡在很具体的地方:工具描述写在哪个字段、循环跑到第几轮该喊停、跑出来的东西怎么判断是真成了还是看着像成了。这篇不铺概念,按一条能跑通的线往下走,每一步告诉你验收标准,也告诉你跑到哪一步该考虑收手。
先说个常见画面。有人周末兴致上来,装依赖、配密钥、挂上五六个工具,跑第一遍就报错,改完报错发现工具压根没被调用,调用上了结果又不对。折腾两天,热情没了。问题不在模型,在于一上来就想把整套东西装齐。下面这条路,每一步只加一样东西,跑通了再往下。
先别写代码,先定这个智能体不干什么
动手前拿张纸,把任务拆成三档:一定能自动完成的、需要人确认的、明确不做的。第三档最难写,也最值钱。没写第三档的智能体,跑着跑着就会去调它不该调的工具,比如查个天气顺手把文件删了。这不是模型调皮,是你没告诉它边界在哪。
判断能不能做,有个土办法:这个任务你自己手动做三遍,三遍步骤基本一样,才适合做成智能体。每遍流程都变的,先做提示词模板更划算,几分钟就能用。一次性任务、结果没法自动校验的任务,做了也是给自己找麻烦。
- 能自动做:输入格式稳定、结果能对照检查的,比如按关键词整理一份清单
- 要人确认:涉及对外发送、改数据、花钱的动作,一律卡在这里
- 明确不做:超出任务范围的工具,从一开始就不挂载,别指望提示词拦住
- 边界写不清就先别写代码,写清了再动手,返工能少一大半
一次完整循环长什么样,先跑通再加料
最小骨架只有四段:读输入、让模型决定下一步、执行工具、把结果塞回上下文。这四段不跑通,挂再多工具都是空转。很多人卡壳不是因为循环写错,是因为一上来就挂了返回一大坨文本的工具,上下文瞬间被撑满,模型后面就开始胡说。
建议先只挂一个工具,挑返回结果短的那个,比如查天气或者算个数。跑通之后再加第二个。验收标准很具体:同一句话连问三次,模型稳定选中同一个工具。选不稳,先别怀疑模型,回头看看工具描述是不是写得含糊。
- 跑通单工具输入一句明确需要该工具的话,确认工具被调用、参数填对、结果回填进上下文,然后再输出答案
- 加第二个工具选一个和第一个功能不重叠的,观察模型会不会选错;选错说明两个工具的适用场景描述有交叉
- 做稳定性测试同一句话重复三次,三次都走同一条路径才算过;一次对一次错,说明描述还得改
工具描述比提示词更值得花时间
新手的时间大多花在调提示词上,其实工具描述更值得改。每个工具写清三件事:什么时候该用、参数各填什么、什么情况下不该用。最后一句最能减少误调用,偏偏大多数人省了。参数名别用缩写,模型看不懂 ctx、q 这种,写成 city、query,调错率会明显下降。
有个常见误判:觉得是模型笨,其实是工具返回值里塞了一堆调试信息,模型被噪声带跑偏。返回结果只留模型决策需要的字段,多余的日志一律不往上下文里放。
| 工具描述要素 | 写清楚什么 | 不写会怎样 |
|---|---|---|
| 使用时机 | 什么输入下该调这个工具 | 模型该调不调,或者对着闲聊也调 |
| 参数说明 | 每个参数填什么、什么格式 | 字段填错,或者干脆漏填 |
| 不该用的场景 | 哪类输入不该走这个工具 | 工具之间互相抢活,选错率高 |
| 返回内容 | 只保留决策需要的字段 | 上下文被噪声占满,后面越跑越偏 |
循环怎么停,这里最容易出事故
至少设三道闸:最大轮次、单次运行时长、累计调用次数。只设一道的,早晚遇到跑到额度见底还没停的情况。别问我怎么知道的,一个忘了设轮次上限的循环,半夜把测试额度跑光,第二天账单看着都心慌。
模型说「完成了」不等于真完成。加一步结果校验更稳:要求的字段是不是都填了、返回是不是空、格式对不对。校验不过就让它重试一次,再不过直接抛错给人看,别让它自己编一个看着像样的答案。
- 最大轮次按任务复杂度定,宁可少也别多,跑不完就报错,人再看
- 单次运行时长兜住死循环,超时直接中断
- 累计调用次数防突发,尤其是带外部接口的工具
- 结果校验单独成一步,别混在主循环里,排查时更清楚
上下文和记忆:什么时候该省,什么时候别省
短任务不要上向量库。把历史对话直接拼进上下文更准,检索一层反而丢细节。判断标准也简单:如果任务需要精确引用前文某句话,用长上下文;如果只需要模糊回忆,才考虑检索。分不清就先用长上下文,贵一点但省心。
需要跨会话记住用户偏好的,先做最简单的键值存储,键用用户 ID,值存几条结论,别一上来就搭全套 RAG。我见过有人第一个版本就上向量库、切分、重排序一套配齐,结果连「记住用户是中文」这种小事都没搞定,调了半天索引,其实两个字段的字典就够了。
跑通了不算完,先量一遍再谈上线
准备十到二十条真实输入,人工标一遍期望结果。每次改完提示词或工具描述都重跑一遍。没这个集合,改一次心里没底一次,改十次也不知道是变好还是变坏。数量不用多,能覆盖主要场景就行。
看两个数:一次成功的比例,和平均跑了几轮才成功。轮次比成功率更能反映成本,一个成功率还行但每次都要跑七八轮的系统,用起来很贵。同一批输入换个模型跑一遍,差别大说明你的任务对模型能力还很敏感,这时候急着上线容易翻车。
| 观察项 | 说明什么 | 怎么处理 |
|---|---|---|
| 一次成功率 | 任务本身稳不稳 | 低于预期先改工具描述,别急着换模型 |
| 平均轮次 | 成本高低 | 轮次偏高查是不是工具返回太啰嗦 |
| 换模型差异 | 对模型能力的敏感度 | 差异大就保守选型,差异小可以挑便宜的 |
| 失败样本类型 | 问题集中在哪 | 按类型归类,比看总数有用 |
什么情况下这事不值得做
任务步骤固定、输入格式固定的,写脚本或做个表单比智能体稳得多,也便宜。结果错了代价很高的场景,比如对外发通知、动账,智能体只适合做草稿,最后一步必须有人点确认。这不是保守,是划得来。
还有一条容易忽略:团队里没人能持续维护提示词和工具描述的,先别上。这类系统不上心调就会慢慢变差,工具接口一改、模型一换,之前调好的东西就可能失灵。要上的话,先想清楚谁来管这件事。
选模型前先看资料库不同模型在工具调用上的表现差别不小,到站内模型资料库对照当时的价格和参数再决定。→常见问题
不用框架,纯手写能做出智能体吗?
能,而且建议第一版就这么做。核心就是一个循环加几个函数调用,代码量不大。框架帮你省的是拼装时间,但调试时多一层抽象就多一层看不懂的地方。等循环跑顺、知道哪里最常出错了,再换框架也不迟。
智能体老是调错工具怎么办?
先看工具描述,九成问题出在这。检查三处:用途那句话是不是写了具体场景、参数说明有没有举一个填好的例子、有没有写「什么情况下别用这个工具」。这三处补齐还错,就把工具数量减到两个,看是不是选择太多导致的。
需要多智能体吗?
大多数从零开始的场景不需要。一个智能体加几个工具就能覆盖。多智能体的好处是职责隔离,代价是通信成本和调试难度都上去。判断标准:如果你的任务里有两块需要完全不同的工具集和不同的判断标准,才考虑拆;否则先在一个里面加分支。
跑起来很慢,是模型的问题吗?
先看轮次。轮次多比单次慢更常见。把每轮的工具返回打印出来,看是不是有工具返回了大量无关内容,模型每轮都在重新读。再看是不是串行调了本来能并行的工具。这两处改完通常能快不少,换模型是最后一步。
做完怎么判断该继续投入还是收手?
看两件事:一是人工兜底的比例,如果一半以上的运行结果都要人来改,说明任务边界没定好;二是节省的时间,把搭建和维护的时间算进去,跟手动做对比。两条都不划算就停,把已经跑通的那部分退化成提示词模板,也能用。