主题
Agent 生产实践
本章目标与前置知识（补充讲解）
先掌握工具调用和可信赖 Agent。学完应能回答：一次失败发生在哪一步？成功率是多少？质量变化来自模型、检索还是工具？每完成一个有效任务花了多少时间和费用？
旅行助手回答慢，不一定是模型慢：可能在等航班接口、重试检索或排队。 可观测性（Observability） 让我们通过应用输出与运行信号定位原因； 评估（Evaluation） 判断结果是否满足任务标准。日志中的工具请求、耗时和状态是可观察事件，不是模型内部思考过程。
一次用户请求是一条调用链（Trace）；其中检索、模型调用和工具执行各形成执行片段（Span），用父子关系和 ID 连接。只记录最终文本，会丢掉“答错之前检索为空”这样的关键原因。
原课程代码片段的阅读范围
下方精读保留上游主要知识与片段，可能包含历史 SDK 写法、示意端点及未完整定义的函数；这些片段不等同于经过本站验证的完整程序。运行前优先阅读本章实际 Notebook 导读与版本校订。已验证的无 API 实验在“扩展实践”中另行标明。
原课程精读：生产中的 AI Agent：可观测性与评估
随着 AI Agent 从实验原型发展到实际应用，理解其行为、监控其性能并系统地评估其输出的能力变得尤为重要。
学习目标
完成本课后，你将了解/掌握：
- Agent 可观测性和评估的核心概念
- 提升 Agent 性能、成本和效果的技术
- 如何系统性地评估你的 AI Agent
- 如何在生产环境中部署 AI Agent 时控制成本
- 如何为基于 Microsoft Agent Framework 构建的 Agent 配置监测
目标是让你具备将“黑盒”Agent 转变为透明、可管理且可靠系统的知识。
_ 注意： 部署安全可信的 AI Agent 非常重要。也请查看构建可信 AI Agent课程。_
调用链与执行片段
可观测性工具如 Langfuse 或 Microsoft Foundry 通常将 Agent 执行表示为跟踪和执行片段（Span）。
- 跟踪 代表从开始到完成的完整 Agent 任务（例如处理用户查询）。
- 执行片段（Span） 是跟踪中的各个步骤（例如调用语言模型或检索数据）。
查看原课程引用的外部截图：Langfuse 中的跟踪树（外部素材仅保留来源链接。）
没有可观测性，AI Agent 就像“黑盒子”——其内部状态和推理过程不透明，难以诊断问题或优化性能。有了可观测性，Agent 变成了“玻璃盒子”，提供了透明度，这对建立信任和确保按预期运行至关重要。
为什么可观测性在生产环境中至关重要
将 AI Agent 转入生产环境会带来一系列新的挑战和需求。可观测性不再是“锦上添花”，而是一项关键能力：
- 调试与根因分析 ：当 Agent 失败或产生意外输出时，可观测性工具提供跟踪以定位错误来源。这在涉及多次 LLM 调用、工具交互和条件逻辑的复杂 Agent 中尤为重要。
- 延迟和成本管理 ：AI Agent 通常依赖按Token或调用计费的 LLM 和其他外部 API。可观测性允许精确跟踪这些调用，帮助识别过慢或过于昂贵的操作。团队可以据此优化提示、选择更高效的模型或重新设计流程，以控制运营成本并确保良好用户体验。
- 信任、安全与合规 ：许多应用需确保 Agent 行为安全且符合道德规范。可观测性提供 Agent 操作和决策的审计轨迹，可用于检测并缓解提示注入、有害内容生成或个人身份信息（PII）处理不当等问题。例如，你可以通过审查跟踪了解 Agent 为何给出某个回应或使用特定工具。
- 持续改进循环 ：可观测性数据是迭代开发流程的基础。通过监控 Agent 在现实环境中的表现，团队可发现改进点、收集数据进行模型微调，并验证变更效果。这样形成反馈循环，在线评估的生产洞察指导离线实验和优化，逐步提升 Agent 性能。
关键指标跟踪
为监控和理解 Agent 行为，应跟踪一系列指标和信号。虽然具体指标可能因 Agent 目的而异，但某些指标是普遍重要的。
以下是常见的可观测性工具监控指标：
延迟： Agent 响应的速度如何？长时间等待会严重影响用户体验。你应通过跟踪 Agent 运行测量任务及各步骤的延迟。例如，所有模型调用共耗时 20 秒的 Agent 可以通过使用更快模型或并行调用模型来加速。
成本： 每次 Agent 运行的费用是多少？AI Agent 依赖按Token计费的 LLM 调用或外部 API。频繁使用工具或多次提示可迅速增加成本。例如，若 Agent 为了微小质量提升调用了 LLM 五次，你需要评估成本是否合理，是否可以减少调用次数或选用更便宜的模型。实时监控还可帮助发现异常峰值（如造成过多 API 调用的缺陷）。
请求错误： Agent 失败的请求有多少？这包括 API 错误或工具调用失败。为使 Agent 在生产中更健壮，你可以设置回退或重试策略。例如，当 LLM 提供商 A 挂掉时，切换到提供商 B 作为备份。
用户反馈： 收集用户直接评价提供宝贵洞察。包括明确的评分（👍点赞/👎差评，⭐1-5 星）或文本评论。持续的负面反馈应引起警示，表明 Agent 无法按预期工作。
隐式用户反馈： 用户行为即使没有明确评分也提供间接反馈。例如，立即改写问题、重复查询或点击重试按钮。如果你发现用户反复提出相同问题，这往往意味着 Agent 未正常工作。
准确率： Agent 生成正确或理想输出的频率如何？准确率定义因场景而异（如问题解决正确率、信息检索准确度、用户满意度）。第一步是明确 Agent 的成功标准。你可以通过自动检测、评分或任务完成标签来跟踪准确率。例如，将跟踪标记为“成功”或“失败”。
自动评估指标： 也可以设置自动评估。例如，使用 LLM 对 Agent 输出进行评分，判断其是否有帮助、准确等。还有一些开源库支持对 Agent 多个方面评分，如针对检索增强生成 Agent 的 RAGAS，或检测有害语言和提示注入的 LLM Guard。
实践中，多种指标结合使用能更全面反映 AI Agent 的健康状态。本章示例笔记本展示这些指标在实际中的表现，先让我们学习典型评估流程。
监控 Agent
收集跟踪数据需要给代码添加监控埋点。目标是让 Agent 代码能够输出跟踪和指标，供可观测平台捕获、处理和展示。
OpenTelemetry（OTel）： OpenTelemetry 已成为 LLM 可观测性的行业标准。它提供一套 API、SDK 和工具，用于生成、收集和导出遥测数据。
许多监控库封装现有 Agent 框架，方便将 OpenTelemetry 执行片段（Span）导出到可观测工具。Microsoft Agent Framework 原生集成了 OpenTelemetry。下面是给 MAF Agent 添加监控的示例：
python
from agent_framework.observability import get_tracer, get_meter
tracer = get_tracer()
meter = get_meter()
with tracer.start_as_current_span("agent_run"):
# Agent execution is traced automatically
pass本章节的示例笔记本将演示如何给 MAF Agent 添加监控。
手动创建执行片段（Span）： 虽然监控库提供了良好基础，但有时需要更详细或定制的信息。你可以手动创建执行片段（Span）以加入自定义应用逻辑。更重要的是，可以给自动或手动创建的执行片段（Span）添加自定义属性（即标签或元数据），这些属性可包含业务特定数据、中间计算结果或调试分析所需的任何上下文，如 user_id、session_id 或 model_version。
使用 Langfuse Python SDK 手动创建跟踪和执行片段（Span）的示例：
python
from langfuse import get_client
langfuse = get_client()
span = langfuse.start_span(name="my-span")
span.end()Agent 评估
可观测性给我们指标，评估则是分析这些数据（及执行测试）以判定 AI Agent 表现优劣及改进方向。换句话说，获取跟踪和指标后，如何用它们判断 Agent 并作出决策？
定期评估很重要，因为 AI Agent 通常是非确定性的，且可能随时间（通过更新或模型行为漂移）变化——没有评估，就无法知道“智能 Agent”是否真的做得好，或是否出现回退。
AI Agent 评估分为两类： 在线评估 和 离线评估 。两者均有价值且互为补充。我们通常从离线评估开始，这是部署前的最低要求步骤。
离线评估
查看原课程引用的外部截图：Langfuse 中的数据集项（外部素材仅保留来源链接。）
离线评估指在受控环境中使用测试数据集（非实时用户查询）评估 Agent。你使用已知期望输出或正确行为的精选数据集，并让 Agent 运行这些数据。
例如，若你构建了一个数学文字题 Agent，可能有一个含 100 道题且答案已知的 测试数据集。离线评估多在开发期间完成，也可纳入 CI/CD 流水线，检查改进或防止回退。其优势是 可重复，且因有标准答案而能获取清晰准确率指标 。你也可模拟用户查询，用自动指标如前所述衡量 Agent 反应与理想答案的差异。
离线评估的主要挑战是确保测试集全面且持续相关——Agent 可能在固定测试集表现良好，但生产环境遇到截然不同的查询。因此，应不断更新测试集，加入反映真实场景的新边缘案例和示例。混合使用小型“冒烟测试”用例和较大评估集最为有效：小集快速检测，大集提供广泛性能指标。
在线评估
查看原课程引用的外部截图：可观测性指标概览（外部素材仅保留来源链接。）
在线评估指在真实运行环境，即生产中实际使用时，对 Agent 表现的实时监控和分析。
例如，你可能跟踪成功率、用户满意度分数或其他实时流量指标。在线评估优势在于 捕捉实验室无法预见的情况 ——可观察模型随时间漂移（Agent 效能因输入模式变化下降）并抓住测试数据中未涵盖的意外查询和情况。它提供 Agent 在现实环境中的真实表现。
在线评估通常包括收集隐式与显式用户反馈，如前所述，也可能运行影子测试或 A/B 测试（新 Agent 版本与旧版本并行运行进行对比）。挑战在于为实时交互获得可靠标签或评分较为困难——可能需依赖用户反馈或下游指标（如用户是否点击结果）。
两者结合
在线与离线评估并非相互排斥，而是高度互补。在线监控获得的见解（如 Agent 在哪些新查询类型上表现差）可用于丰富和改进离线测试集。相反，离线测试表现良好的 Agent 可以更放心地部署并监控在线表现。
事实上许多团队采用循环模式：
先做离线评估 -> 部署 -> 在线监控 -> 收集新失败案例 -> 添加入离线数据集 -> 优化 Agent -> 重复
常见问题
在部署 AI Agent 到生产时，你可能会遇到各种挑战。以下是一些常见问题及潜在解决方案：
| 问题 | 潜在解决方案 |
|---|---|
| AI Agent 任务执行不一致 | - 优化给 AI Agent 的提示，确保目标明确。 - 识别是否可以将任务拆分为子任务并由多个 Agent 处理。 |
| AI Agent 进入连续循环 | - 明确终止条件，确保 Agent 知道何时停止流程。 - 对于复杂需要推理和规划的任务，使用专门针对推理的大模型。 |
| AI Agent 工具调用表现不佳 | - 在 Agent 系统外测试并验证工具输出。 - 优化工具的参数、提示和命名。 |
| 多 Agent 系统表现不稳定 | - 优化给每个 Agent 的提示，确保它们具体且彼此区分。 - 构建使用“路由”或控制 Agent 的层级系统，确定哪个 Agent 负责处理。 |
许多此类问题通过启用可观测性能更有效识别。前述跟踪和指标帮助精确定位 Agent 流程中的问题，提高调试和优化效率。
成本管理
下面是一些管理将 AI Agent 部署到生产环境成本的策略：
使用更小的模型： 小型语言模型（SLM）在某些 Agent 用例中表现良好，并且将大幅降低成本。如前所述，构建一个评估系统来确定和比较性能与更大模型的差异，是了解 SLM 在你的用例中表现如何的最佳方式。考虑将 SLM 用于意图分类或参数提取等简单任务，同时将更大模型保留用于复杂推理。
使用路由器模型： 一个类似的策略是使用多样化的模型和尺寸。你可以使用 LLM/SLM 或无服务器函数，根据复杂性路由请求到最合适的模型。这也有助于降低成本，同时确保在正确的任务上有良好表现。例如，将简单查询路由到更小、更快的模型，仅在复杂推理任务中使用昂贵的大型模型。
缓存响应： 识别常见请求和任务，并在它们通过 Agent 系统之前提供响应，是减少类似请求数量的好方法。你甚至可以实现一个流程，利用更基础的 AI 模型来识别请求与缓存请求的相似度。这个策略可以显著降低常见问答或常见工作流的成本。
让我们看看这在实践中的运作方式
在本节的示例笔记本中，我们将看到如何使用可观测性工具监控和评估我们的 Agent 的示例。
原示例导读与完整验收链（补充讲解）
原课程的基础 Python Notebook 展示旅行工具和运行时间；费用报销工作流进一步把收据处理、角色执行与结果汇集组织起来。图片/多模态输入仍需要对应模型权限。 打印耗时不等同于已经接入生产级调用链后端 ；保存的截图和输出只证明上游曾保存过一个结果。
运行准备见环境篇，在 Jupyter 打开本页底部对应 Notebook。检查模型部署是否支持输入类型，先用无个人信息的示例收据。预期看见结构化费用信息、工作流事件与最终结果；不保证不同模型生成相同措辞。
从一次请求建立如下验收路径：固定输入样本 → 标记预期文档或动作 → 运行候选版本 → 保存最小事件 → 比较指标 → 决定是否发布。保存模型部署、提示版本、文档版本、代码提交和评估集版本，才能解释回归。
| 指标 | 计算方式 | 需要同时防止什么误判 |
|---|---|---|
| 任务成功率 | 满足全部验收条件的任务 / 总任务 | 只看 HTTP 200 会把错误答案算成功 |
| 引用支持率 | 有证据支持的被检查陈述 / 被检查陈述 | 有链接不代表链接内容支持回答 |
| 工具失败率 | 失败调用 / 总工具调用 | 区分参数错误、授权拒绝与服务故障 |
| p95 延迟 | 95% 请求在该时间内完成 | 均值掩盖长尾与排队 |
| 每成功任务成本 | 总推理与工具等成本 / 成功任务数 | 更便宜但经常失败的模型未必省钱 |
本地实操：先建立一个小回归集（扩展实践）
Python 3.12+，从本项目根目录运行，无需安装第三方依赖：
bash
python3 examples/assistant/evaluate.py
python3 -m unittest discover -s examples/assistant -p 'test_*.py' -vevaluate.py 是 6 个预设问答/拒绝/授权回归用例，输出每例通过与最终计数；单元测试另外检查记忆隔离、幂等性和损坏文件等行为。它们只评估本项目的规则模拟器， 不代表真实大模型在开放问题上的准确率 。
app.py 中 events 只保存工具名、事件类型、摘要等必要数据，避免把用户问题复制到日志。生产环境还需给日志加访问控制、保留期限和脱敏；对低熵内容计算哈希仍可能被猜出原文。
离线评估用固定样本方便对比；在线评估关注真实分布变化、用户撤销和人工升级。先小流量验证，再扩大流量。模型作为评委时要记录评委版本、校准人工样本，防止只奖励“写得像正确答案”的输出。
常见问题、适用范围与练习
| 现象 | 原因 | 解决方式 |
|---|---|---|
| 看不到完整 Trace | 跨异步任务或服务未传递上下文 | 传递 trace ID，检查采样和 exporter |
| 延迟变低但业务投诉增多 | 缓存了过期答案，或跳过校验 | 按任务成功率和证据质量一起评估 |
| 某次演示成功却不能复现 | 输入、索引或部署版本变了 | 保存版本信息，重复固定回归集 |
| 成本突然增长 | 无界循环、长上下文、过度并发 | 次数/时间/输出预算与告警共同限制 |
练习： 给评估集增加“定制商品能否退款”的用例，需要检查哪些东西？
参考答案
至少检查引用包含 custom-policy、保留“质量问题”例外，且不能只引用一般七天规则。只断言出现“退款”二字会把相反结论也判为通过。开放模型实验还应由人工核对事实支持与遗漏条件。
生产评估并非上线前做一次就结束。下一章学习协议，把观测与权限边界延伸到跨组件调用。
原课程代码与补充材料
以下是本章实际源文件对应的阅读页。Notebook 已分解为说明、代码及原文件输出；云端示例未进行联网端到端验证。正文中的片段用于解释，运行时使用完整 Notebook 和准备篇的固定依赖。
本章来源
基于 英文原文 与 简体中文翻译 整理，原作者为 Microsoft 与开源贡献者，采用 MIT 许可证。本页标明“补充讲解”与“扩展实践”的内容为本项目新增。
来源提交：25b7985f3b2d · 获取日期：2026-09-14。参见版本校订记录。