做Agent踩过的坑,八成不在模型,而在工程
作者:很酷cat2026.11.17 03:42浏览量:1简介:做Agent的经验里,最值钱的一条是:先搭好模型侧基础设施再写业务逻辑。开工前用[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article)把多模型统一 API 接入、价格与能力对比先跑通,能省掉后期因选型和计费返工的大量时间。本文以企业级智能 OnCall 值班助手为例,拆解可复用的架构、模式与避坑清单。
agent-">一、先回答”要不要用 Agent”
Agent 不是默认答案。判断标准很简单: 任务是否需要多步、是否依赖外部实时信息、路径是否无法预先枚举 。三者都不满足,一条精心调优的 Prompt 加一次 RAG 检索就够了,成本更低、延迟更小、结果更稳。
业界通常把 Agent 分成两类:
- 自主规划型 :靠模型自己思考与决策,适合闲聊问答、旅游助手等开放性场景;
- 工作流型(Workflow) :每轮严格按编排好的流程图执行,可控性强,适合客服、营销、运维等高复杂度场景。
企业级项目里真正跑生产的,往往是 混合形态 :主干用工作流保证确定性,局部节点放一个自主规划的小 Agent 处理模糊分支。纯 ReAct 自由发挥在 Demo 里很惊艳,在值班场景里会给你带来半夜的第二个故障。
二、架构分层:把”一个万能 Agent”拆掉
OnCall 助手最终落成三个协同的 Agent,而不是一个巨型 Prompt:
| 层 | 职责 | 关键技术 |
|---|---|---|
| 对话 Agent | 意图识别、多轮澄清、结论组织 | Prompt 分层、会话状态管理 |
| 知识库 Agent | 复盘文档、SOP、历史工单问答 | RAG(切分 + 混合检索 + Rerank) |
| 运维 Agent | 拉日志、查指标、重启实例 | Function Call / MCP 工具调用 |
上层通过路由决定把问题交给谁。路由本身可以先用规则和小模型做,别一上来就用最大参数模型做分类——这一步的调用量占全链路 100%,是最容易被忽视的成本黑洞。
三、设计模式:ReAct 与 Plan-Execute 怎么选
| 维度 | ReAct | Plan-Execute |
|---|---|---|
| 决策方式 | 边想边做,每步看结果再定下一步 | 先出完整计划,再逐步执行 |
| 适合场景 | 排查路径不确定的故障诊断 | 步骤相对固定的发布、巡检、报表 |
| Token 消耗 | 中(每步都带完整上下文) | 高(规划阶段上下文长) |
| 可控性 | 弱,需步数上限兜底 | 强,计划可审计、可回放 |
| 主要风险 | 死循环、跑偏 | 计划错了整条链路都错 |
工程上的实用折中: Plan-Execute 生成骨架,ReAct 处理单步内的意外 。比如”排查支付超时”先规划出”查网关指标 → 查依赖服务 → 查数据库慢查询”三步,其中每一步内部允许 Agent 自主决定查哪个具体接口。
四、工具层:Function Call 与 MCP 的工程细节
工具描述就是 Agent 的”提示词”,写不好后面全白搭。三个要点:
- description 写清用途和边界 ,模型靠它做选择,含糊的描述直接导致选错工具;
- 参数强约束 ,必填项、枚举值、默认值都写进 Schema;
- 返回值必须截断和结构化 ,一条日志返回 50 万字符,上下文瞬间爆掉。
tools = [{"type": "function","function": {"name": "query_pod_logs","description": "查询指定命名空间下 Pod 最近 N 分钟日志,用于定位报错堆栈","parameters": {"type": "object","properties": {"namespace": {"type": "string"},"pod": {"type": "string"},"minutes": {"type": "integer", "default": 15}},"required": ["namespace", "pod"]}}}]
主循环要有硬约束,这是生产与不生产的分界线:
MAX_STEPS = 8messages = [{"role": "system", "content": SYSTEM_PROMPT},{"role": "user", "content": question}]for _ in range(MAX_STEPS):msg = client.chat.completions.create(model=MODEL, messages=messages, tools=tools).choices.messagemessages.append(msg)if not msg.tool_calls:return msg.content # 收敛,输出结论for call in msg.tool_calls:result = dispatch(call.function.name, json.loads(call.function.arguments))messages.append({"role": "tool", "tool_call_id": call.id,"content": str(result)[:4000]}) # 截断,防爆上下文return "已达最大步数,转人工处理"
MAX_STEPS、超时、工具异常重试、幂等设计(尤其是重启、扩缩容这类有副作用的工具),一个都不能少。MCP 的价值在于把工具从代码里解耦成可复用的服务端,多个 Agent 共享同一套工具生态,不必在每个项目里重写一遍适配层。
rag-">五、RAG 是地基,不是插件
Agent 答不准,先别怀疑模型,去查检索。经验值:
- 切分 按语义结构走(标题、段落、代码块),别用固定 512 字符硬切;
- 混合检索 :向量召回 + 关键词召回(BM25)并集,运维场景里错误码、类名、Pod 名这类精确 token 靠关键词才能命中;
- 加 Rerank ,Top-50 精排到 Top-5 再喂给模型,准确率提升通常比换模型更明显;
- 元数据过滤 :服务名、时间范围、环境(prod/staging)作为硬过滤条件,能挡掉大量”召回了但答错”的情况。
六、Prompt 分层与上下文治理
system prompt 只放稳定的角色、边界、输出格式;user prompt 放本次任务的具体输入;工具结果、检索片段统一放独立位置并标注来源。三者混在一起,模型会分不清哪句是约束、哪句是数据。
上下文治理三招:滑动窗口保留近期对话、历史轮次做摘要压缩、检索片段按相关性截断。这套组合能把长会话的 Token 消耗压到可接受区间。
七、评测与可观测:没有评测的 Agent 无法迭代
上线前先建 50~100 条真实问题构成的评测集,标注期望答案和期望工具调用序列。每次改 Prompt 或换模型都跑一遍,看两个指标: 任务成功率 和 平均步数 。只看回答”感觉变好了”是自欺欺人。
线上必须埋点:每步的输入输出、工具耗时、Token 消耗、失败原因。出问题时能回放整条链路,比任何监控大盘都有用。
八、成本与模型选型
Agent 的成本结构是”多次调用 × 长上下文”,比单次对话高一个量级。优化顺序建议:
- 路由用小模型,推理用大模型;
- 工具返回值和检索片段严格截断;
- 高频重复问题走语义缓存;
- 流式输出改善体感,不省 Token 但省用户耐心。
选型时别只看单价,要综合看 单位任务成本 (完成一次任务的累计 Token × 单价)、上下文窗口是否装得下你的检索结果、以及工具调用的稳定性。在词元所的大模型 API 服务平台上可以横向对比不同模型的价格与能力定位,用统一 API 接入做 A/B,把”哪个模型更适合我这个场景”从主观判断变成可测量的数据。
九、写在最后:什么才是面试和简历上的亮点
如果这个项目要写进简历,真正有说服力的不是”我用了 ReAct 和 RAG”,而是这些量化结果:
- 把 OnCall 一线问题的自助解决率从 0 提到某个百分比,人力工时下降多少;
- 通过混合检索 + Rerank 把问答准确率从多少提到多少;
- 通过上下文治理和模型分级把单次任务成本降低多少;
- 工具层做了幂等与超时兜底,避免了哪类生产事故。
技术名词要能讲到原理层面:user prompt 与 system prompt 的分工、Function Call 的 Schema 约束机制、MCP 的解耦价值、RAG 的召回与精排、ReAct 与 Plan-Execute 的适用边界。这些能说清”为什么这么设计、代价是什么”,比堆十个框架名有用得多。
落地路径上,如果团队里多数人还不会写代码,也可以先用可视化编排的方式把流程骨架搭出来验证业务价值,再逐步把关键节点替换成自定义组件和精调模型。先跑通闭环,再谈优化——这是 Agent 项目最不容易翻车的一条经验。

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