logo

做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 爆炸
编排 控制循环、重试、终止 没有最大轮次,死循环烧钱

一个最小可用的工具调用循环长这样:

  1. def run_agent(query, tools, model, max_steps=8):
  2. messages = [
  3. {"role": "system", "content": SYSTEM_PROMPT},
  4. {"role": "user", "content": query},
  5. ]
  6. for step in range(max_steps):
  7. resp = model.chat(messages, tools=tools)
  8. messages.append(resp.message)
  9. if not resp.tool_calls: # 模型给出最终答案
  10. return resp.content
  11. for call in resp.tool_calls: # 执行工具,回填结果
  12. result = tools[call.name]( **call.arguments)
  13. messages.append({
  14. "role": "tool",
  15. "tool_call_id": call.id,
  16. "content": str(result),
  17. })
  18. 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 的工程重点不在向量库,而在 检索质量 :

  1. 切分:按语义结构切,别按固定字数硬切,表格和代码块要特殊处理。
  2. 混合检索:向量召回 + 关键词召回(BM25)融合,专有名词和编号靠关键词更准。
  3. 重排:召回 20 条,用 Reranker 精排取前 5 条,这一步对准确率提升最明显。
  4. 引用溯源:答案必须带出处,否则无法排查幻觉。

五、工具设计是最容易被忽视的工程活

模型不会用工具,八成是工具设计有问题。我的 checklist:

  • 粒度 :一个工具做一件事。把”查询订单并退款”拆成两个工具。
  • 描述 :工具描述和参数说明要写给”一个聪明但不懂你业务的新人”看,写清单位、枚举值、异常返回。
  • 错误返回 :把错误信息作为工具结果返回给模型,让它有机会自我修正,而不是直接抛异常中断。
  • 幂等与权限 :写操作必须幂等,高危操作加二次确认。
  • 协议标准化 :工具多了以后,用 MCP 这类协议统一接入,避免每个模型各写一套适配。

六、Prompt 分层,别写成一锅粥

我习惯把 Prompt 拆成四层,各自独立迭代:

  1. 角色与目标 (system):你是谁、要达成什么、绝对不能做什么。
  2. 流程约束 :可用工具、调用顺序、何时停止。
  3. 输出格式 :JSON Schema 或明确模板,越具体越好。
  4. 少样本示例 :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 工程的本质是 用不确定的模型构建确定的系统,所有的模式、约束、评测,都是在给不确定性加护栏。

发表评论

活动