AI Agent开发实战经验：从OnCall智能助手说起

一、从真实痛点出发：先定义问题，再谈技术

很多团队做Agent的第一步是“先选框架、先堆功能”，这往往是本末倒置。一个值得投入的Agent项目，首先要回答三个问题：谁在用？痛点是什么？成功标准如何衡量？

以企业级智能OnCall Agent为例，它解决的是传统值班模式中的典型低效问题：人工值守成本高、重复性咨询占比大、故障排查严重依赖个人经验、夜间响应慢。对应的目标可以概括为两件事：一是把“人找信息”变成“信息找人”，让常见问题自动应答；二是把专家的排查思路沉淀为可复用的自动化排查链路，缩短故障定位时间。

这里的第一条经验是：收敛边界，先跑通最小闭环。不要一开始就追求“万能助手”，把场景限定在“知识问答+故障排查”两类高频需求上，先做到单Agent、少量工具、一个知识库的端到端可用，再逐步扩展。问题定义得越清晰，后续的技术选型就越不容易跑偏。

agent-agent">二、架构设计：多Agent协作优于单一大Agent

新手常见的做法是用一个巨大的System Prompt加一大堆工具堆出一个“全能Agent”。实践证明，当工具数量增多、职责混杂时，模型的任务理解和工具选择准确率都会明显下降。更合理的做法是按职责拆分：

• 知识库Agent：负责基于文档知识的问答，核心是RAG链路；
• 对话Agent：负责多轮交互、意图澄清与会话状态维护，是用户的统一入口；
• 运维Agent：负责执行实际操作，如查询监控指标、拉取日志、调用诊断脚本。

由一个编排层负责路由与结果聚合。这样拆分的收益很明确：

1. 上下文隔离：每个子Agent的System Prompt更聚焦，减少无关指令的干扰；
2. 工具集收敛：每个Agent只挂载与自身职责相关的少量工具，降低误调用率；
3. 独立迭代：RAG优化与工具链优化互不影响，可以分节奏推进；
4. 权限收敛：操作类工具只暴露给运维Agent，便于做权限控制与审计。

三、Prompt工程化：System Prompt与User Prompt各司其职

System Prompt是Agent的“岗位说明书”，定义角色、能力边界、行为约束与输出格式；User Prompt承载具体任务输入，应尽量结构化（如问题、涉及服务、时间范围分字段传入）。几条实用经验：

1. 约束要可判定：把“不要乱说”改写成“知识库未命中时必须回复NEED_HUMAN”，模型才有明确的执行标准；
2. 输出为下游服务：明确JSON Schema，方便程序解析与兜底处理；
3. Prompt当代码管理：版本化存储，配合评测集做回归，避免“改一处、坏一片”。

示意模板：

system: 你是OnCall助手，仅回答运维相关问题。
规则：1) 仅依据检索到的知识作答；2) 无法确定时输出 NEED_HUMAN；
3) 输出格式：{"answer": "...", "confidence": 0~1, "refs": [...]}

四、工具调用：理解Function Calling的本质

Function Calling的本质是：模型不执行任何操作，只输出结构化的调用意图（工具名+参数），真正的执行发生在应用侧运行时，执行结果作为“观察”回填给模型继续推理。理解这一点非常关键——工具的可靠性由工程侧决定，而不是模型。

工具设计的核心原则：

1. 描述即文档：工具名、参数含义、适用场景写得越清楚，模型选择越准；
2. 粒度适中：太粗则不灵活，太细则模型容易在无关工具间打转；
3. 幂等与安全：写操作要有确认机制，高危操作默认拦截；
4. 错误信息可读：报错要包含“下一步怎么办”的提示，帮助模型自我修正。

在工具接入层面，还可以借鉴模型上下文协议（MCP）这类开放标准的思路：把工具提供方与Agent运行时解耦，用统一的方式描述和调用工具，让同一套工具能力被多个Agent复用，避免每个项目重复造轮子。

rag-agent-">五、RAG实践：知识库Agent的成败关键

运维知识的特点是更新频繁、格式杂（Wiki、工单、运维手册、聊天记录）、术语缩写多。直接套用通用的“切分—向量化—召回—生成”链路往往效果平平，需要在每个环节做定制：

1. 切分：按文档结构切（标题、步骤、FAQ条目），而非固定长度硬切；
2. 元数据过滤：给知识块打上服务、组件、版本、时间等标签，检索时先过滤后召回；
3. 混合检索：向量召回与关键词召回结合——运维查询里有大量精确名词（错误码、指标名），纯向量容易漏；
4. 重排与溯源：对候选结果重排，答案附带引用来源，方便值班同学核验；
5. 持续运营：把答不上来的问题回流知识库，形成闭环，RAG是“运营出来的”，不是“一次建成的”。

六、设计模式选型：ReAct与Plan-and-Execute

• ReAct（推理—行动—观察循环）：每一步先思考、再调用工具、根据观察决定下一步，适合故障排查这类“边查边判断”的场景，链路短、反馈快；
• Plan-and-Execute：先生成整体计划再逐步执行，必要时重规划，适合步骤多、耗时长的复杂任务，如一次完整的容量巡检。

选型参考：任务步数少、需要快速反馈用ReAct；任务可预先拆解、单步执行成本高用Plan-and-Execute；实际项目常混合使用——外层规划、内层ReAct。

while not done:
    thought = llm(history + observations)
    if thought.need_tool:
        observations.append(execute(thought.tool_call))
    else:
        return thought.answer

七、工程化落地：决定Agent能否真正上线

1. 可观测性：完整记录每轮的Prompt、思考、工具调用与结果，“为什么答错”必须靠全链路日志定位；
2. 评测体系：构建覆盖高频场景的评测集，每次改动跑回归，用数据驱动迭代，没有评测就没有方向；
3. 成本控制：简单任务用小模型、复杂推理用大模型，配合缓存与结果复用；模型服务可选用百度智能云等云厂商提供的通用大模型能力，也可私有化部署，关键是把模型调用抽象成可替换的一层；
4. 人机协同：置信度不足或涉及高危操作时果断转人工，Agent的定位是“值班助手”而非“替代值班”；
5. 安全底线：工具权限最小化、操作留痕、敏感信息脱敏。

八、总结

做Agent的经验可以浓缩为几句话：以真实问题定义边界；用多Agent拆解复杂度；把Prompt当代码管理；把工具当产品设计；把RAG当运营做；把评测当生命线。当你理解了system prompt、user prompt、function calling、MCP、RAG、ReAct这些名词背后的原理，并能独立完成一个企业级Agent从设计到上线的全过程，这些概念自然不再神秘——真正拉开差距的，从来不是记住名词，而是工程落地的深度。