新手构建 AI Agent 的实战经验与避坑指南：从 OnCall 场景到通用设计

agent">一、为什么选择 OnCall 场景来理解 Agent

传统 OnCall 值班有几个非常典型的痛点：告警来源分散、排查路径长、重复问题多、夜间响应成本高。值班人员往往需要同时查看监控面板、日志平台、工单系统和历史文档，再根据经验判断严重程度、定位根因、执行恢复动作。这个过程高度依赖个人经验，且很容易因为信息不全导致误判。

用 Agent 来解决 OnCall 问题，本质上是把“人工值守 + 经验排查”转化为“自动应答 + 智能排查”。一个相对完整的智能 OnCall Agent 通常包含三类能力：

1. 知识库 Agent：负责理解历史工单、运维手册、架构文档、常见故障处理步骤，回答“这个问题以前怎么处理”“这个告警代表什么”等事实性问题。
2. 对话 Agent：负责与用户或值班人员交互，澄清意图、确认上下文、给出下一步建议，并决定何时调用其他工具。
3. 运维 Agent：负责执行具体动作，例如查询监控指标、拉取日志、检查服务状态、触发预案或生成恢复建议。

这三类 Agent 不一定是三个完全独立的服务，更多时候是同一套 Agent 系统中不同职责模块的组合。理解这一点，是后续设计架构的基础。

二、先厘清 Agent 与传统自动化的区别

很多团队第一次做 Agent 时，容易把它做成“带对话界面的脚本调度器”。用户输入一句话，后端匹配关键词，命中后执行固定脚本。这样做不是不行，但它没有发挥 Agent 真正的价值。

Agent 的核心特征是：能够根据目标、上下文和工具反馈，动态调整执行路径。它不是在固定流程上跑，而是在一个可变的决策空间中寻找合适路径。

举一个 OnCall 例子。传统自动化可能写死：

if 告警类型 == "CPU使用率过高" then 执行扩容脚本

而 Agent 的做法是：

• 读取告警内容；
• 查询该服务最近是否有发布；
• 查询该服务历史 CPU 模式；
• 判断是突发流量还是资源泄漏；
• 如果是突发流量，建议扩容或限流；
• 如果是资源泄漏，建议重启并生成排查报告。

两者最大区别在于：Agent 可以根据中间结果调整后续动作。这也意味着 Agent 系统必须认真设计“工具描述”“上下文管理”和“停止条件”。

三、从系统架构层面规划 Agent 项目

一个可落地的 Agent 项目，至少要包含以下层次：

1. 接入层

负责接收用户或监控系统的事件。可能是 Web 控制台、聊天工具、API 回调。OnCall 场景下，接入层还要处理告警去重、降噪、分级和路由。否则 Agent 一上线就会被海量重复告警淹没。

2. 对话与规划层

这一层是 Agent 的“大脑”。它需要完成：

• 意图识别：用户是想查询、诊断、执行，还是闲聊；
• 任务规划：把复杂问题拆解成可执行步骤；
• 工具选择：从工具列表中选择合适的工具；
• 反思与修正：根据工具返回结果判断是否需要调整策略。

这里会涉及 ReAct、Plan-Execute 等设计模式，后面单独展开。

3. 工具层

工具是 Agent 的手和脚。OnCall Agent 常见工具包括：

• 监控查询工具：查询 CPU、内存、QPS、错误率等指标；
• 日志查询工具：根据时间范围、关键字、服务名检索日志；
• 变更查询工具：查询最近发布记录、配置变更；
• 工单工具：创建、查询、关闭工单；
• 执行工具：重启服务、扩缩容、调整流量权重。

工具设计有两个容易忽略的问题。一是工具描述不够清晰，导致模型无法正确选择工具；二是工具返回结果过大，超过上下文窗口，影响后续推理。第一个问题可以通过“为每个工具提供结构化描述、参数说明和使用示例”解决。第二个问题需要工具返回结果时做摘要和截断，而不是直接把几百行日志塞回模型。

4. 知识层

知识层解决“模型不知道企业内部信息”的问题。可以使用 RAG 架构，将运维手册、历史工单、架构文档切块后向量化，在需要时检索相关片段。

知识库建设的关键不是“把所有文档都灌进去”，而是先梳理高频问题类型，再反向整理对应的知识内容。否则容易出现“检索到的内容与问题弱相关”或“知识条目互相矛盾”的情况。

5. 记忆与上下文层

Agent 需要记住当前会话中的关键信息，比如已经被确认的服务名、时间范围、告警级别。同时也需要跨会话记忆，比如“某个服务近一个月内已经发生三次类似告警”。

实现上，短期记忆可以放在会话上下文中，长期记忆则需要外部存储。记忆设计要非常克制，写入过多信息会干扰模型注意力，写入过少则丢失关键上下文。

6. 可观测层

Agent 上线后，必须能够回答：

• 它当时为什么选择这个工具；
• 每一步耗时多少；
• 工具调用失败的原因是什么；
• 最终结论的可信度有多高。

建议对每次 Agent 执行做链路追踪，记录每一轮的输入、输出、工具调用、耗时和模型消耗。没有可观测层，Agent 在生产环境会变成一个“不可解释的黑盒”。

四、提示词设计：Agent 开发中最容易被低估的工程问题

很多人把提示词当成“写一段话”。实际上，一个高质量 Agent 的提示词更像一份小型工程规范。

system prompt 的职责边界

system prompt 应明确：

• Agent 的角色；
• 可使用的工具范围；
• 输出格式；
• 必须遵守的约束；
• 什么情况下必须停止执行并向用户确认。

例如，OnCall Agent 的 system prompt 中应明确：“任何重启、扩容等变更操作前，必须输出操作方案并等待用户确认，不允许直接执行。”这能显著降低误操作风险。

user prompt 的清洗与结构化

用户输入往往很模糊，例如“服务好像有问题”。Agent 不应直接猜测，而应在关键信息缺失时主动追问。可以在 user prompt 中追加从系统中自动获得的上下文，例如当前时间、用户所在团队、最近活跃告警列表等。这样模型在不增加对话轮次的情况下，也能获得有价值的背景信息。

提示词要可测试、可版本化

提示词修改后，应能通过一套评测集验证效果是否提升。评测集至少包含典型问答、边界场景和对抗性输入。不要凭感觉改提示词。

五、工具调用与 Function Calling 的实战细节

Function Calling 让模型能够输出结构化的工具调用意图，但实际工程中要注意以下几点：

1. 参数类型要简单

尽量使用基础类型作为参数，避免复杂的嵌套对象。模型生成复杂 JSON 时容易出错，而参数解析失败会导致整个工具调用中断。

2. 每个工具只做一件事

一个工具如果功能太重，模型在选择时容易犹豫，调用后的结果也难以判断。例如“查询服务信息并返回相关告警和日志”应该拆成三个工具。

3. 工具返回结果要精炼

工具返回内容应经过二次封装，只保留模型决策需要的信息。比如日志查询工具，不应返回原始日志全文，而应返回摘要、错误段、时间范围和样本行。

4. 提供工具使用示例

在工具描述中附带一个简短的使用示例，可以显著提高模型选择正确工具的概率。示例不是为了让模型复读，而是帮助它理解工具的语义边界。

六、Agent 设计模式的真正意义

ReAct 模式

ReAct 的核心思想是让模型交替进行“推理”和“行动”。推理阶段分析当前已知信息，判断下一步需要什么；行动阶段调用工具获取新信息。如此循环，直到获得足够信息得出结论。

ReAct 的价值在于，它让 Agent 的决策过程可被追踪。每一步都有明确的推理文本，这比“直接给最终答案”更适合 OnCall 这种需要解释与审计的场景。

Plan-Execute 模式

Plan-Execute 先制定一个完整计划，再逐步执行。它适合任务边界清晰、步骤间依赖明确的问题。例如故障复盘，可以先规划“收集告警信息—收集变更信息—收集日志—生成时间线—提出改进建议”。

但 Plan-Execute 的缺点是计划可能过时。如果在执行过程中发现新情况，原计划需要调整。因此实际系统中常采用“Plan-Execute-Reflect”的变体，在每一步执行后重新评估计划是否仍然合理。

为什么面试要考设计模式

面试中考察 Agent 设计模式，并不是让候选人背概念，而是看其是否理解“模型不能一步到位解决问题”这一基本前提。能够说清楚不同模式适合什么场景、如何设置停止条件、如何避免无限循环，才说明候选人真正上手做过。

rag-">七、知识库与 RAG 的落地经验

RAG 听起来简单：文档切块、向量化、检索、拼接、生成。但实际效果差异巨大。

文档质量决定天花板

如果原始文档本身写得含糊，RAG 的结果也不会好。建议在建设知识库前先做一轮内容治理，删除过时、重复、矛盾的内容，并统一术语。

分块策略影响检索精度

分块太大，检索到的段落包含太多噪声；分块太小，语义又会破碎。通常需要根据文档类型调整分块大小，并保留标题、章节等结构信息。

检索后要重排序

只依赖向量相似度容易漏掉关键内容。可以结合关键词检索结果，再对候选片段做重排序，提高召回质量。

回答必须带引用

生产环境中的知识库回答，必须标注引用来源。没有出处的回答在故障场景中是不可接受的。引用也方便用户快速定位原文进行复核。

八、Agent 项目的简历与面试准备

很多人问：项目做了，但简历怎么写才不显得空洞？

核心原则是：不要只写“实现了 XXX”，要写“为了实现 XXX，遇到了什么问题，做了什么决策，最终效果如何”。

例如不要写：“使用 RAG 构建知识库问答。”而应写：“原有知识库检索命中率低，故障场景下回答不可靠。分析发现分块策略与查询语句的匹配度不足，于是重新设计分块规则并引入混合检索与重排序，将典型故障案例的回答准确率从某基线提升到可量化目标。”

技术上需要准备的内容至少包括：

• Agent 与传统自动化的区别；
• Function Calling 的执行流程和失败处理；
• RAG 的完整链路及优化点；
• 上下文窗口管理策略；
• 如何评估 Agent 的回答质量；
• 如何避免模型在工具调用时无限循环；
• 如何设计 Agent 的可观测性与兜底机制。

这些问题的答案不能停留在“用工具做了个功能”，而要体现出对底层原理和工程权衡的理解。

九、三个最常见的错误

1. 把 Agent 当成万能方案

Agent 并不适合所有场景。对于路径固定、输入输出明确的任务，传统自动化更稳定、成本更低。Agent 更适合真正需要“判断与决策”的场景。

2. 忽视执行安全

在 OnCall 场景中，Agent 的执行权限必须严格限制。高危操作采用“建议 + 人工确认”模式，而不是完全自动执行。变更动作要可审计、可回滚。

3. 没有评测集就上线

没有评测集就无法判断 Agent 是否在变好。哪怕只准备 50 条典型用例，也能在每次修改后进行回归验证。没有评测的优化基本等于盲调。

十、总结

做一个 Agent 项目，尤其是智能 OnCall 这类贴近生产环境的项目，最有价值的不是调通一个演示，而是完整经历“场景分析—架构设计—提示词管理—工具设计—知识库建设—可观测—安全控制—面试复盘”的全流程。这个过程中积累的经验，远比会调用某个框架接口重要得多。如果能把每个环节的权衡讲清楚，无论是面试还是真实落地，都会有明显优势。