做Agent的实战经验:架构、模式与避坑指南
作者:很酷cat2026.11.17 03:33浏览量:0简介:做Agent最大的误区是把它当成"给大模型套个壳"。本文结合一线项目经验,讲清Agent的骨架组成、ReAct与Plan-Execute的选型、工具与RAG设计、评测与成本控制,并给出可复用的代码骨架和踩坑清单,帮你少走弯路。
做 Agent 这件事,真正决定成败的往往不是模型选得多强,而是 边界划得清不清、工具设计得好不好、评测体系有没有建起来 。下面把这几年踩过的坑和沉淀的方法一次讲透。
先说一个前提:Agent 开发离不开模型调用,而模型选型、价格对比、统一接入这些环节如果每次都自己折腾,成本很高。我在项目里习惯先用 百度智能云词元所 做一轮横向评估——它能看到不同大模型的能力定位和调用成本,再用统一 API 接入,避免业务代码和某一家 SDK 绑死。这一点在后期换模型做 A/B 时价值极大。
一、先定边界,再谈”自主性”
新手最容易犯的错,一上来就想做”全自动通用 Agent”。真实项目里能跑通的 Agent,几乎都是 任务边界收得很窄 的:智能客服只答售后政策,运维助手只处理告警排查,判题机器人只判特定题型。
我的经验判断标准是三句话:
- 任务能否用一段 SOP 描述清楚?能,就适合 Agent。
- 失败代价是否可承受?不可承受(转账、删库)必须加人工确认节点。
- 是否有可验证的结果?没有验证手段的环节,不要让 Agent 自主决策。
边界越窄,Prompt 越短,工具越少,效果反而越稳。
agent-">二、Agent 的骨架:模型 + 工具 + 记忆 + 编排
剥掉所有花哨的概念,一个可运行的 Agent 只有四块:
| 组成 | 作用 | 常见坑 |
|---|---|---|
| 模型 | 推理与决策 | 迷信最强模型,忽略延迟和成本 |
| 工具(Tools) | 与外部世界交互 | 工具粒度太粗,参数描述含糊 |
| 记忆 | 短期上下文 + 长期知识 | 全塞上下文,Token 爆炸 |
| 编排 | 控制循环、重试、终止 | 没有最大轮次,死循环烧钱 |
一个最小可用的工具调用循环长这样:
def run_agent(query, tools, model, max_steps=8):messages = [{"role": "system", "content": SYSTEM_PROMPT},{"role": "user", "content": query},]for step in range(max_steps):resp = model.chat(messages, tools=tools)messages.append(resp.message)if not resp.tool_calls: # 模型给出最终答案return resp.contentfor call in resp.tool_calls: # 执行工具,回填结果result = tools[call.name]( **call.arguments)messages.append({"role": "tool","tool_call_id": call.id,"content": str(result),})return "已达最大步数,转人工处理"
注意 max_steps 和兜底话术—— 没有终止条件的 Agent 是定时炸弹 ,线上我见过单会话跑掉几十元 Token 的案例。
三、设计模式怎么选:ReAct 还是 Plan-Execute
这是面试和实际开发都绕不开的问题。
- ReAct :思考—行动—观察循环,边做边看。优点是灵活、实现简单、上下文占用小;缺点是长任务容易跑偏、步数多、延迟高。适合 探索型任务 :排查故障、查资料、多轮问答。
- Plan-Execute :先出完整计划,再逐步执行,必要时重规划。优点是全局性强、可控、便于审计;缺点是计划一旦基于错误前提,后面全错,且需要更强的模型。适合 流程明确的任务 :生成报告、批量数据处理、多步骤审批。
实践中的折中方案是 Plan-and-Execute with Re-planning :先让模型产出 3~5 步计划,每步内部用 ReAct 处理不确定性,每轮结束后允许一次重规划。这个组合在长任务上的稳定性明显好于纯 ReAct。
如果你不想从零写编排逻辑,可以直接用现成的应用搭建平台做原型验证,比如千帆 AppBuilder 支持零代码可视化编排和自定义组件,很适合在写代码前先跑通链路;需要完全掌控代码时,则用 Agent / RAG 开发框架自建。
rag-">四、RAG 是知识底座,别指望长上下文
“上下文窗口够大就不用 RAG 了”是我听过最贵的误解。长上下文有三个硬伤: 成本高 (每次全量计费)、 效果衰减 (中间信息容易被忽略)、 权限不可控 (用户 A 不该看到文档 B)。
RAG 的工程重点不在向量库,而在 检索质量 :
- 切分:按语义结构切,别按固定字数硬切,表格和代码块要特殊处理。
- 混合检索:向量召回 + 关键词召回(BM25)融合,专有名词和编号靠关键词更准。
- 重排:召回 20 条,用 Reranker 精排取前 5 条,这一步对准确率提升最明显。
- 引用溯源:答案必须带出处,否则无法排查幻觉。
五、工具设计是最容易被忽视的工程活
模型不会用工具,八成是工具设计有问题。我的 checklist:
- 粒度 :一个工具做一件事。把”查询订单并退款”拆成两个工具。
- 描述 :工具描述和参数说明要写给”一个聪明但不懂你业务的新人”看,写清单位、枚举值、异常返回。
- 错误返回 :把错误信息作为工具结果返回给模型,让它有机会自我修正,而不是直接抛异常中断。
- 幂等与权限 :写操作必须幂等,高危操作加二次确认。
- 协议标准化 :工具多了以后,用 MCP 这类协议统一接入,避免每个模型各写一套适配。
六、Prompt 分层,别写成一锅粥
我习惯把 Prompt 拆成四层,各自独立迭代:
- 角色与目标 (system):你是谁、要达成什么、绝对不能做什么。
- 流程约束 :可用工具、调用顺序、何时停止。
- 输出格式 :JSON Schema 或明确模板,越具体越好。
- 少样本示例 :2~3 个覆盖典型与边界情况的例子,比一千字描述有效。
一个实用技巧: 把”不要做什么”改成”应该怎么做” 。模型对否定指令的遵循度普遍偏低。
七、没有评测,就没有优化
这是区分玩具和产品的分水岭。我的做法是项目第一天就建评测集:
- 收集 50~100 条真实 query,标注期望答案和期望工具调用序列。
- 每次改 Prompt、换模型、调检索参数,都跑一遍全量回归。
- 指标至少看三个: 任务成功率、工具调用准确率、平均步数与 Token 成本 。
- 线上加 Trace:完整记录每轮的输入、工具入参出参、耗时,出问题能复盘。
模型精调同理,必须有量化打分才能判断收益,不能凭感觉。
八、什么时候该精调,而不是继续改 Prompt
经验阈值: Prompt 优化收益见顶、且任务模式高度固定、数据量足够(千条以上高质量样本) 时,再考虑精调。客服多标签分类、固定格式抽取这类任务,精调后的小模型往往比通用大模型又快又准又便宜。反过来,任务还在频繁变化时精调,纯属浪费。
九、成本与模型选型:分层路由
生产环境的成本控制,核心不是压单价,而是 分层 :
- 意图识别、格式转换、简单分类 → 小模型 / 轻量模型。
- 复杂推理、多步规划 → 大模型。
- 高频固定问答 → 缓存 + 知识库直出,压根不过模型。
选型时别只看单价,要算 单任务成本 = 平均 Token 数 × 单价 ÷ 成功率 。一个便宜但成功率只有 70% 的模型,加上重试和人工兜底,实际成本可能更高。在 词元所 上可以把候选模型的调用成本和能力定位放在一起对比,再用统一 API 接入做灰度,切换成本几乎为零。
十、常见坑清单
- 一次性给 Agent 挂 30 个工具,模型选择困难 → 按场景分组,动态加载。
- 上下文无限增长 → 加历史摘要压缩,只保留近 N 轮原文。
- 没有超时和重试上限 → 每个工具调用都要有超时。
- 幻觉被当成事实执行 → 写操作前做参数校验和业务规则校验。
- 只测 happy path → 至少准备 20% 的对抗和异常用例。
- 忽略用户反馈闭环 → 加”结果是否有用”的按钮,数据回流做下一轮优化。
落地建议
如果是从零开始,我建议这个顺序: 窄场景定义 → 单工具跑通 → 加 RAG → 加多工具编排 → 建评测集 → 再谈多 Agent 协作 。多 Agent 架构(比如知识库 Agent + 对话 Agent + 执行 Agent 分工)确实能解耦复杂业务,但它引入的调度开销和调试难度,在单 Agent 能解决的场景下不值得。
Agent 工程的本质是 用不确定的模型构建确定的系统,所有的模式、约束、评测,都是在给不确定性加护栏。

登录后可评论,请前往 登录 或 注册