1. 白皮书

第四天的白皮书探讨了如何保障 Agent 的工作质量。当前正处于 Agentic 时代的开端，尽管 Agent 能力巨大，但是其固有的非确定性和不可预测性打破了我们传统的质量保障体系。
Agent 的质量保障应植根于架构设计本身，而非仅依赖开发尾声的测试环节。
本指南立足于三大核心要义：

• 轨迹即真相：我们必须突破仅评估最终输出的局限。Agent 质量与安全性的真正衡量标准，在于其完整的决策过程。
• 可观测性是基础：无法观测的过程，无从评判。我们详细阐述了可观测性的 “三大支柱”—— 日志记录（Logging）、轨迹追踪（Tracing）与指标监测（Metrics），它们是捕捉 Agent “思考过程” 的关键技术基础。
• 评估是持续循环：我们将这些理念整合为 “智能体质量飞轮”（Agent Quality Flywheel）—— 这是一份实操指南，可将相关数据转化为可落地的洞察。该体系结合了可规模化的 AI 驱动评估工具与不可或缺的 “人机协同（Human-in-the-Loop, HITL）” 判断机制，以推动Agent 的持续优化。

1.1. 如何阅读这个白皮书

本指南的结构是从“为什么”逐步过渡到“是什么”，最后到“如何做”。参考本章节可以导航到与您角色最相关的章节。

• 面向所有读者：从第1章: “非确定性世界中的智能体质量” 开始。本章确立了核心问题，解释了传统质量保证体系为何不适用于人工智能智能体，并介绍了定义我们目标的 Agent quality 四大支柱（有效性、效率、稳健性和安全性）。
• 面向PM、数据科学家和QA：如果您负责确定衡量内容以及如何评判质量，请重点关注第2章: “Agent 评估的艺术：过程评判”。本章是您的战略指南。它详细介绍了用于评估的“由外而内”层级结构，阐释了可扩展的“"LLM-as-a-Judge”模式，并阐明了HITL的关键作用。
• 面向工程师、架构师和SRE：如果你负责构建系统，那么第3章: “可观测性：洞悉 Agent 的思维” 就是你的技术蓝图。本章将从理论过渡到实践，通过“厨房类比”（普通厨师与 gourmet 厨师）来解释监控与可观测性的区别，并详细介绍可观测性的三大支柱：Logs、Traces和Metrics——这些是你构建“可评估” Agent 所需的工具。
• 对于团队负责人和战略制定者：要了解这些部分如何构成一个自我改进的系统，请阅读第4章: “总结：在自主世界中建立信任”。本章将这些概念整合为一本可操作的行动手册。它介绍了 Agent Quality Flywheel” 作为持续改进的模型，并总结了构建可信人工智能的三大核心原则。

1.2. 非确定性世界中的 Agent 质量

随着AI飞速发展，我们正从构建执行指令的可预测工具，迈向设计能够解读意图、制定计划并执行复杂多步骤行动的自主 Agent。让 AI Agents 变得强大的机制，也正是使其具有不可预测性的原因。
传统的质量保证体系（QA）虽然对确定性系统很有效，但不足以应对现代人工智能的细微差别和突发行为。一个 Agent 可能通过了100个单元测试，却仍会在实际应用中发生灾难性故障，因为其故障并非代码中的漏洞，而是 LLM 判断上的缺陷。

1.2.1. 为什么 Agent Quality 需要新的方法

对于工程师而言，风险是需要识别和处理的问题。在传统软件中，故障是明确的：系统崩溃、抛出空指针异常，或者返回明显错误的计算结果。这些故障显而易见、具有确定性，并且可以追溯到逻辑中的特定错误。
AI Agents 的失败方式则不同。它们的失败往往不是系统崩溃，而是质量的微妙下降。这源于模型权重、训练数据和环境交互之间的复杂相互作用。这些失败具有隐蔽性：系统继续运行，应用程序接口调用返回 200(success)，输出看起来也合理。但实际上，这种输出存在严重错误，具有操作危险性，并且在悄无声息地侵蚀信任，这正是Agent 的自主性和复杂性导致的。

故障模式	描述	示例
算法偏差（Algorithmic Bias）	智能体将训练数据中存在的系统性偏差转化为实际操作，且可能放大此类偏差，进而导致不公平或具有歧视性的结果。	- 负责风险汇总的金融智能体，因训练数据存在偏差，会基于邮编对贷款申请施加过度惩罚。
事实幻觉（Factual Hallucination）	当智能体无法找到有效信息来源时，往往会以高度确信的态度生成听起来合理但与事实不符或虚构的信息。	- 某研究工具在学术报告中生成极为具体但完全错误的历史日期或地理位置，破坏学术诚信。
性能与概念漂移（Performance & Concept Drift）	随着智能体所交互的现实世界数据（即 “概念”）发生变化，其原有训练内容逐渐失效，导致性能随时间推移而下降。	- 欺诈检测智能体无法识别新型攻击模式。
突发非预期行为（Emergent Unintended Behaviors）	智能体为实现目标，会形成新颖或超出预期的策略，这些策略可能效率低下、无实际帮助，甚至具有利用性。	- 发现并利用系统规则中的漏洞。- 与其他机器人发生 “代理冲突”（例如，反复覆盖对方的编辑内容）。

这些失败使得传统的调试和测试模式失去了效果。你无法使用断点来调试幻觉问题；你也不能编写单元测试来防止它的出现。根本原因分析需要深入的数据分析、模型重新训练和系统性评估——这完全是一门新的学科。

1.2.2. 范式转变：从可预测代码到不可预测 Agents

核心技术挑战源于从以模型为中心的人工智能向以系统为中心的人工智能的演进。评估 Agent 与评估 LLM 有着本质区别，因为 Agent 是一个系统。这种演进是分阶段逐步进行的，每个阶段都增加了新的评估复杂性。

1. 传统机器学习：定义明确，我们依靠精确率、召回率、F1分数和均方根误差等统计指标，对照预留的测试集进行评估。这个问题虽然复杂，但“正确”的定义是清晰的。
2. 被动式大语言模型：随着生成式模型的兴起，我们失去了简单的衡量指标。LLM 输出具有概率性。即便输入完全相同，输出也可能存在差异。评估变得更为复杂，需要依赖人工评分以及模型间的基准测试。尽管如此，这些系统在很大程度上仍是被动的、文本输入-文本输出工具。
3. 大语言模型+检索增强生成（LLM+RAG）：故障可能出现在大语言模型或检索系统中。智能体给出糟糕的答案是因为大语言模型推理能力差，还是因为向量数据库检索到了不相关的片段？我们的评估范围从仅针对模型扩展到包括分块策略、嵌入和检索器的性能。
4. 主动式人工智能智能体：如今，我们正面临一场深刻的架构变革。LLM 不再仅仅是文本生成器，它已成为复杂系统中负责推理的“大脑”，被整合到一个能够自主行动的循环中。这种具有智能体特性的系统带来了三项核心技术能力，这些能力打破了我们现有的评估模型：
   • 规划与多步骤推理：Agent 将复杂目标（如“规划我的旅行”）分解为多个子任务。这会形成一条 trajectory(轨迹)：思考→行动→观察→思考……。LLM 的非确定性如今在每一步都会加剧。第一步中一个微小的、随机的词汇选择，到第四步时可能会让 Agent 陷 入一条完全不同且无法恢复的推理路径。
   • 工具使用与函数调用：Agent 通过API和外部工具（代码解释器、搜索引擎、预订API）与现实世界交互。这带来了动态的环境交互。智能体的下一步行动完全取决于外部不可控世界的状态。
   • Memory：Agent 持有状态。短期记忆追踪当前任务，而长期记忆使 Agent 能够从过去的交互中学习。这意味着 Agent 的行为会不断演变，基于“学到”的内容，昨天有效的输入今天可能会产生不同的结果。
5. 多智能体系统：当多个活跃智能体被整合到一个共享环境中时，就会出现极高的架构复杂性。这不再是对单一轨迹的评估，而是对系统级涌现现象的评估，由此带来了新的根本性挑战：
   • 突发系统故障：系统的成功取决于智能体之间非预设的交互，例如资源争夺、通信瓶颈和系统性死锁，这些问题不能归咎于单个智能体的故障。
   • 协作式评估与竞争式评估：目标函数本身可能会变得模糊。在协作式多智能体系统中（例如供应链优化），成功是一个全局指标；而在竞争式多智能体系统中（例如博弈论场景或拍卖系统），评估通常需要跟踪单个智能体的性能以及整体市场/环境的稳定性。

这种能力组合意味着评估的主要单位不再是模型，而是整个系统的轨迹(trajectory)。智能体的涌现行为源于其规划模块、工具、记忆与动态环境之间复杂的相互作用。

1.2.3. Agent Quality 支柱：评估框架

如果我们不能再依赖简单的准确率指标，而必须对整个系统进行评估，那么我们该从何处入手呢？答案是一种被称为“Outside-In(由外而内)”的战略性转变方法。
这种方法将 AI 评估锚定在以用户为中心的指标和整体业务目标上，不再仅仅依赖内部的、组件级的技术分数。我们不能只问“模型的F1分数是多少？”，而应该开始问“这个 Agent 是否能带来可衡量的价值，并且与用户的意图一致？”
这一策略需要一个整体框架，将高级别的业务目标与技术性能联系起来。我们从四个相互关联的支柱来定义 Agent 的质量：

• 有效性：这是核心终极问题：Agent 是否成功且精准地实现了用户的真实意图？该支柱直接关联以用户为中心的指标与业务关键绩效指标（KPI）。对于零售Agent 而言，这不仅是 “是否找到了商品？”，更是 “是否促成了转化？”；对于数据分析 Agent，则不是 “是否写出了代码？”，而是 “代码是否产出了正确的洞察？”。有效性是衡量任务成功的最终标准。
• 高效性：Agent 是否高效地解决了问题？一个预订简单航班却需要 25 个步骤、5 次工具调用失败以及 3 次自我修正循环的 Agent，即便最终成功，也应被视为低质量 Agent。效率通过消耗的资源来衡量：tokens（成本）、实际耗时（延迟）以及轨迹复杂度（总步骤数）。
• 稳健性：Agent 如何应对现实世界的各种挑战与复杂状况？当 API 超时、网站布局变更、数据缺失或用户提供模糊提示时，Agent 能否优雅地处理失败？稳健的 Agent 会重试失败的调用，在需要时向用户请求澄清，并如实报告无法完成的事项及原因，而非崩溃或产生幻觉。
• 安全性：这是不可妥协的底线。Agent 是否在其设定的伦理边界与约束范围内运行？该支柱涵盖从负责任 AI 的公平性与无偏性指标，到抵御提示注入攻击和数据泄露的安全防护等所有方面。它确保 Agent 专注于任务本身，拒绝有害指令，并成为组织可信赖的代理。

这个框架阐明了一件事：如果只看最终答案，你就无法衡量这些支柱中的任何一个。如果不计算步骤，就无法衡量效率。如果不知道哪个API调用失败了，就无法诊断稳健性故障。如果无法检查 Agent 的内部推理过程，就无法验证安全性。

1.3. Agent 评估的艺术：过程评判

Agent 评估是一个全面的验证过程。它提出了一个复杂得多且至关重要的战略性问题：“我们是否打造了正确的产品？”这个问题是“Outside-In”评估框架的战略核心，意味着需要从内部合规转向评判系统的外部价值以及与用户意图的契合度。这要求我们评估 Agent 在动态环境中运行时的整体质量、稳健性和用户价值。
AI Agent 能够规划、使用工具并与复杂环境交互——极大地复杂化了评估它的方方式。我们必须超越对输出的“测试”，转而学习对过程的“评估”的艺术。本章正是为此提供了一个战略框架：评判 Agent 从初始意图到最终结果的整个决策轨迹（trajectory）。

1.3.1. Outside-In 评估层级

为避免在海量的单元级评估指标中迷失方向，必须创建一个自上而下的战略性过程。我们将其称为“由外而内”层级法。这种方法会优先考虑唯一最终重要的指标——现实世界中的成功，之后再深入探究这种成功或失败背后的技术细节。该模型分为两个阶段：先从黑箱入手，再将其打开。

1.3.1.1 Outside-In 端到端评估

第一个也是最重要的问题是：“Agent 是否有效地实现了用户的目标？”
这是“由外而内”的视角。在分析任何内部想法或工具调用之前，我们必须根据 Agent 既定的目标来评估其最终表现。
此阶段的指标侧重于整体任务的完成情况。我们衡量的是：

• 任务成功率：对最终输出是否正确、完整且解决了用户实际问题的评分，例如编码智能体的PR接受率、金融智能体的数据库交易成功率，或客服机器人的会话完成率。
• 用户满意度：对于交互式智能体而言，这可以是直接的用户反馈评分（例如，点赞/点踩）或客户满意度评分（CSAT）。
• 整体质量：如果 Agent 的目标是可量化的（例如，“总结这10篇文章”），那么衡量标准可能是准确性或完整性（例如，“它是否总结了全部10篇？”）。

如果 Agent 在这个阶段获得100%的分数，我们的工作可能就完成了。但在复杂系统中，这种情况很少见。当 Agent 生成有缺陷的最终输出、放弃任务或无法得出解决方案时，“由外而内”的视角会告诉我们哪里出了问题。现在我们必须打开这个“黑箱”，看看原因何在。

1.3.1.2 Inside-Out 轨迹评估

一旦确定了上一步是失败的，我们就转向“由内而外”的视角。我们通过系统评估 Agent 执行轨迹的每个组成部分来分析：

1. LLM Planning(思考)：这方面的故障包括 LLM 幻觉、无意义或偏离主题的回应、语境污染或重复输出循环。
2. Tool Usage(选择和参数)：分析 Agent 是否调用了错误的工具、未能调用必要的工具、虚构工具名称或参数名称/类型，或者进行了不必要的调用。即使它选择了正确的工具，也可能因提供缺失的参数、错误的数据类型或格式错误的API调用JSON而失败。
3. Tool Response(观察)：工具正确执行后，Agent 必须理解其结果。Agent 在此环节经常出错，比如误读数值数据、未能从响应中提取关键实体，或者更严重的是，没有识别出工具返回的错误状态（例如，API的404错误），却仍按调用成功的情况继续处理。
4. RAG性能：如果 Agent 使用 RAG，其轨迹取决于所检索信息的质量。失败情况包括检索到不相关的文档、获取过时或错误的信息，或者 LLM 完全忽略检索到的上下文，仍然生成幻觉答案。
5. 轨迹效率与稳健性：除了正确性之外，我们还必须评估过程本身：暴露低效的资源分配，例如过多的API调用、高延迟或冗余工作。它还能揭示稳健性故障，例如未处理的异常。
6. 多智能体交互：在高级系统中，轨迹涉及多个 Agents。此时，评估还必须包括 Agents 间的通信日志，以检查是否存在误解或通信循环，并确保 Agents 在不与其他 Agents 发生冲突的情况下坚守其既定角色。

通过分析轨迹，我们可以从“最终答案是错误的”（黑箱）过渡到“最终答案是错误的，因为……”（玻璃箱）。这种诊断能力水平正是Agent 评估的全部目标。

1.3.2. Agent 评判的主题和内容

知道要评估什么：轨迹(trajectory) 已经成功了一半。另一半则是如何进行评估。对于质量、安全性和可解释性等细微方面，这种判断需要一种复杂的混合方法。自动化系统能提供效率，但人类的判断仍是质量的关键。

1.3.2.1. 自动化评估指标

自动化指标具有速度快和可重复性高的特点。它们在回归测试和输出基准测试中很有用。例如：

• 基于字符串的相似度（ROUGE、BLEU），用于比较生成文本与参考文本。
• 基于嵌入的相似度（BERTScore、余弦相似度），用于衡量语义贴近度。
• 特定任务基准，例如 TruthfulQA2

自动化指标虽高效却流于表面：它们只能捕捉表面的相似性，无法体现更深层次的推理或用户价值。

1.3.2.2. LLM 作为评判者

我们该如何自动化评估 “这个总结是否优质？” 或 “这个方案是否合理？” 这类定性输出呢？答案：LLM-as-a-Judge 方式，即采用另一款强大的模型来评估当前 Agent 的输出。
向作为 “评估者” 的模型提供以下信息：Agent 的输出结果、原始提示词、“标准答案” 或参考依据（若存在），以及一份详细的评估标准（例如，“从实用性、准确性和安全性三个维度，按 1-5 分给该响应打分，并说明评分理由”）。这种方法能提供可规模化、高效且精度惊人的反馈，尤其适用于 Agent “思考过程” 质量、工具响应解读等中间环节的评估。尽管它无法取代人类判断，但能帮助我们在数千种场景中快速评估 Agent 性能，让迭代式评估流程具备可行性。(最好进行对比性评估AB两个结果对比)

1.3.2.3. Agent 作为评判者

LLM 虽能对最终响应打分，但对 Agent的评估需要更深入 —— 不仅看结果，更要审视其背后的推理逻辑与执行行为。为此，Agent-as-a-Judge 这一新兴范式应运而生：它让一个 Agent 完整评估另一个 Agent 的执行轨迹，核心是聚焦 “过程” 而非仅评判 “输出”。其关键评估维度包含三大方面：

• 计划质量：Agent 制定的方案逻辑是否清晰、是否具备可落地性？
• 工具使用：所选工具是否契合任务需求，且应用过程是否正确？
• 上下文处理：Agent 能否有效利用前期获取的信息辅助决策？

这种方法在过程评估中特别有价值，因为失败往往源于有缺陷的中间步骤，而非最终输出。
要落地 “智能体作为评估者”，可按以下步骤操作：

1. 配置 Agent 框架，使其记录并导出完整的执行轨迹，轨迹中需包含 Agent 的内部计划、所选工具列表，以及传递给工具的精确参数；
2. 再创建一个专用的评估 Agent，并为其配置包含评估标准的 Prompt，让它直接对轨迹数据进行评估。Prompt 需聚焦过程性问题，例如：“1. 从轨迹来看，初始计划是否符合逻辑？2. 工具 A 是否是合适的首选工具，还是应选用其他工具？3. 传递的参数是否正确且格式规范？” 如此一来，即便 Agent 最终输出看似正确，也能自动检测出过程中的问题（如计划效率低等）。

1.3.2.4. HITL 评判

自动化虽能实现规模化评估，却在深度主观性任务（如创意质量评估、语气微妙性判断）和复杂领域知识应用上存在局限。而 Human-in-the-Loop(HITL) ，正是弥补这一短板的核心手段 —— 它能捕捉自动化系统遗漏的关键定性信号与细微判断，为 Agent 质量校准提供 “人类视角”。
不过需明确的是，人工评分并非绝对的 “客观真相”：面对高度主观的评估维度，标注者间很难达成完全一致。因此，HITL 的核心价值在于建立 “经人类校准的基准”，确保 Agent 行为符合复杂的人类价值观、场景化需求，以及医疗、法律、金融等专业领域的精准性要求。具体而言，HITL 流程通过三大关键功能落地：

1. 领域专业支持：针对医疗、法律等专业 Agent，需依靠领域专家评估其输出的事实准确性与行业标准符合性；
2. 细微差异解读：人类能精准判断 Agent 互动中的微妙特质，比如沟通语气是否恰当、是否契合用户潜在意图、伦理层面是否合规；
3. 构建 “黄金集合”：在自动化评估启动前，由人类打造包含典型、边缘及对抗性场景的测试基准，明确 Agent 成功的核心目标，为后续评估提供参照。

1.3.2.5. 用户反馈和 Reviewer 界面

评估还必须收集 Agent 真实的用户反馈。每一次互动都是反映其 “实用性”“清晰度” 与 “可信度” 的重要信号。这类反馈既包含 “点赞 / 踩” 这类直观的定性信息，也涵盖可量化的产品内成功指标，比如代码类 Agent 的拉取请求（PR）通过率、旅行类 Agent 的预订完成率。
要让用户反馈真正助力 Agent 优化，需遵循四大最佳实践：

1. 低门槛反馈设计：用 “点赞 / 点踩”、快捷滑块或简短评论等轻量化方式，降低用户反馈的操作成本，提升参与意愿；
2. 场景化反馈关联：将用户反馈与完整对话记录、Agent 的推理轨迹绑定，让后续问题定位有迹可循，避免 “反馈孤立无援”；
3. 专业化评审界面（Reviewer UI）：采用双面板布局，左侧展示对话流程，右侧呈现 Agent 的推理步骤，支持直接标注 “计划不合理”“工具误用” 等问题，让评审更精准；
4. 反馈聚合看板：通过仪表盘汇总所有反馈数据，自动凸显高频问题与潜在风险，为 Agent 迭代指明方向。

好用的界面是评估框架落地的关键 —— 一套优秀的 Reviewer UI 能让用户反馈和评审意见更直观、传递更高效，最终转化为可落地的优化动作，避免评估流于形式。

1.3.3. AI 归责 & 安全评估

对生产级 Agent 而言，评估绝不止 “能否完成任务” 这一项 —— 负责任 AI（RAI）与安全性，是必须跨越的 “硬性门槛”。哪怕一个 Agent 的任务完成度达 100%，若存在安全隐患、可能造成伤害，它仍是彻底的失败品。
安全性评估并非孤立环节，而是需贯穿 Agent 全开发生命周期的专业工作，核心落地路径包含三大方向：

1. 破坏性测试：主动用对抗性场景 “挑战” Agent，比如尝试诱导其生成仇恨言论、泄露用户隐私信息、传播有害刻板印象，或是触发恶意操作，以此暴露潜在安全漏洞；
2. 自动过滤 + 人工审核双保障：先用技术过滤器初步拦截违反政策的内容，但因自动化工具难以识别细微的偏见或隐性不良信息，必须搭配人工审核进一步把关，形成 “技术筛查 + 人类判断” 的双重防线；
3. 严格对标伦理准则：将 Agent 的输出与预先制定的伦理规范、核心原则逐一比对，确保其行为符合道德标准，避免因设计漏洞导致意外后果。

1.4. 可观测性：洞悉 Agent 的思维

1.4.1. 从监控到可观测性

在上一章中，我们确定 AI Agent 是一种新型软件。它们不只是遵循指令，还能做出决策。这种根本差异要求我们采用新的质量保证方法，将我们从传统的软件监控带入更深层次的可观测性领域。

1.4.1.1. 可观测性三大支柱

我们无法直接读取 LLM 的想法，但可以分析它留下的痕迹。这是通过将我们的可观测性实践建立在三个基础支柱上来实现的：(LOG)日志、(Traces)追踪 和 (Metrics)指标。

1.4.2. 支柱一：Logging

什么是 Logs ？日志是可观测性的原子单位。可以把它们看作是 agent’s 日记中带有时间戳的记录。每条记录都是关于某个离散事件的原始、不可变的事实：“在10:01:32，我被问到一个问题。在10:01:33，我决定使用 get_weather 工具。” 它们告诉我们发生了什么。

1. 不仅是 print()：什么让 Log 变得有效？
   需要具备大规模存储、搜索和分析日志数据的能力，可以自动从服务收集日志，允许进行标准化查询(SQL)，以发现 Agent 行为中的趋势。

2. 关键日志条目解析
   要重建 Agent 的“思考过程”，日志必须包含丰富的上下文。结构化的JSON格式是黄金标准。

   • 核心信息：一份优质的日志应包含完整的上下文：提示词/输入输出、中间推理步骤（智能体的“思维链”，）、结构化工具调用（输入、输出、错误）以及 Agent 内部状态的任何变化。
   • 权衡：冗长与性能：高度详细的DEBUG日志是开发人员排查问题的得力助手，但在生产环境中可能过于“嘈杂”，并造成性能开销。这就是结构化日志如此强大的原因：它允许你收集详细数据，同时高效地对其进行过滤。

   以下是一个展示结构化日志强大功能的实际示例，改编自ADK的DEBUG输出：

   // 一条记录单次 LLM 请求的结构化日志
   ...
   2025-07-10 15:26:13,778 - DEBUG - google_adk.google.adk.models.google_llm - Sending out request, model: gemini-2.0-flash, backend: GoogleLLMVariant.GEMINI_API, stream: False 
   2025-07-10 15:26:13,778 - DEBUG - google_adk.google.adk.models.google_llm - 
   
   LLM Request:
   System Instruction: 关于你的行为描述是："可掷 8 面骰子并判断结果数值的 Hello World agent"。你需执行掷骰子操作，并回答与骰子结果相关的问题.....
   
   Contents:
   {"parts":[{"text":"掷一个 6 面骰子"}],"role":"user"} 
   {"parts":[{"function_response":{"name":"roll_die","response":{"result":2}}}],"role":"user"} {"parts":[{"function_call":{"args":{"sides":6},"name":"roll_die"}}],"role":"model"} 
   
   Functions:
   roll_die: {'sides': {'type': <Type.INTEGER: 'INTEGER'>}} 
   check_prime: {'nums': {'items': {'type': <Type.INTEGER: 'INTEGER'>}, 'type': <Type.ARRAY: 
   'ARRAY'>}} 
   
   2025-07-10 15:26:13,779 - INFO - google_genai.models - AFC is enabled with max remote 
   calls: 10.
   2025-07-10 15:26:14,309 - INFO - google_adk.google.adk.models.google_llm - 
   
   LLM Response:
   Text: 我已掷出一个 6 面骰子，结果为 2.
   

一种有效的日志记录模式是在行动前记录 Agent 的意图，在行动后记录结果。这能立即明确失败的尝试与故意决定不采取行动之间的区别。

1.4.3. 支柱二：Tracing

什么是Tracing? 如果说 logs 是日记条目，那么traces就是将它们串联成一个连贯故事的叙事线索。追踪会从最初的用户查询到最终的答案，全程跟进单个任务，将各个日志（称为spans）拼接成一个完整的端到端视图。追踪通过展示事件之间的因果关系揭示出关键的“原因”。

1.4.3.1. 为什么追踪至关重要

考虑一种复杂的 Agent 故障：用户提出问题，却得到了毫无意义的答案。

• 孤立日志可能显示：错误：RAG搜索失败 以及 错误：LLM响应验证失败。你能看到这些错误，但根本原因尚不明确。
• Trace记录揭示了完整的因果链：用户查询 → RAG 搜索（失败）→ 错误的工具调用（收到空输入）→ LLM 错误（被错误的工具输出弄混淆）→ 不正确的最终答案

这条 Trace 能让根本原因立即显现，这使其在调试复杂、多步骤的智能体行为时不可或缺。

1.4.3.2. 智能体 Trace 的关键要素

现代追踪基于 OpenTelemetry 等开放标准构建。其核心组件包括：

• Spans：trace 中各个已命名的操作（例如，llm_call span、tool_execution span）。
• Attributes：每个 Span 附带的丰富元数据——prompt_id、latency_ms、token_count、user_id等。
• 上下文传播：通过唯一的 trace_id 将 Spans 链接在一起的“魔法”。整合完整图景，将 Agent 调用与所有后续的模型和工具调用关联起来。

1.4.4. 支柱三：Metrics

什么是Metrics？ Metrics 就是评论家发布的最终评分卡。它们是定量的、汇总的健康分数，能让你立即、一目了然地了解 Agent 的整体表现。
评论家并非仅凭对最终结果评判就随意给出评分。他们的判断是基于所观察到的一切得出的。Metrics 也是如此：它们并非新的数据来源，而是通过长期汇总日志和追踪数据得出的。它们要回答的问题是：“平均而言，性能表现有多好？”
对于AI Agents 而言，将 Metrics 分为两个不同的类别是很有用的：可直接测量的系统指标和更复杂、更具评估性的质量指标。

1.4.4.1. 系统指标：生命体征

系统指标是衡量运营健康状况的基本量化指标。它们通过聚合函数（如平均值、总和或百分位数）直接从日志和追踪的属性中计算得出。可以将这些指标视为 Agent 的生命体征：脉搏、体温和血压。
需要跟踪的关键系统指标包括：

• 性能：延迟(P99)和错误率
• 成本：tokens 和 API Cost
• 有效性：任务完成率和工具使用频率

1.4.4.2. 质量指标：评判决策过程

质量指标是在原始可观测性数据基础上，超越了效率层面的进一步评估，用于评估 Agent 的推理过程及最终输出质量本身。 这些并非简单的计数器或平均值，而是通过在原始可观测性数据之上应用一个判断层而得出的二阶指标，包括：

• 正确性与准确性：Agent 提供的答案是否符合事实？如果它对文档进行了总结，该总结是否忠实于原文？
• 轨迹遵循度：Agent 是否遵循了给定任务的预期路径或“理想方案”？它是否按正确顺序调用了正确的工具？
• 安全性与责任性：Agent 的响应是否避免了有害、有偏见或不适当的内容？
• 有用性与相关性：Agent 的最终回复对用户是否真的有帮助，且与他们的查询相关?

生成这些指标不仅需要简单的数据库查询。这通常涉及将Agent的输出与“黄金”标准数据集进行比较，或者使用 LLM-as-a-Judge，根据评分标准对响应进行打分。

1.4.5. 整合：原始数据到可执行

拥有 logs、traces 和 metrics 之后，你需要将它们整合并转化为实际行动和可落地的业务洞见。这涉及三个关键的操作实践：

1. 仪表盘与告警
   单一仪表盘无法满足智能体多维度的管理需求，必须按 “系统健康” 和 “模型质量” 拆分视图，让不同角色精准获取所需信息：
   • 运营仪表盘（面向 SRE/DevOps 团队）
     • 核心定位：监控智能体 “基础生命体征”，确保系统稳定运行
     • 追踪指标：P99 延迟（反映极端情况下的用户等待时间）、错误率（工具调用 / API 请求失败比例）、API 成本（外部服务调用开销）、令牌消耗（LLM 使用成本）
     • 核心价值：实时捕捉 “硬故障”，比如当 P99 延迟连续 5 分钟超过 3 秒时，立即触发告警，提示工程团队排查系统瓶颈（如服务器负载过高、工具响应超时），避免影响用户体验
   • 质量仪表盘（面向产品 / 数据科学 / AgentOps 团队）
     • 核心定位：洞察智能体 “决策与输出质量”，发现细微的性能漂移
     • 追踪指标：事实准确率（输出内容与真实信息的匹配度）、轨迹合规性（智能体推理步骤是否符合预设流程）、实用性评分（用户对输出的满意度）、幻觉率（生成虚假信息的比例）
     • 核心价值：捕捉 “软问题”，例如当 “实用性评分” 24 小时内下降 10% 时，即便系统指标（如延迟、错误率）正常，也能及时预警 —— 提示团队排查是否是新模型部署后推理逻辑变化、或训练数据偏差导致质量退化
2. 安全与隐私保护
   在生产环境中，日志和轨迹会不可避免地记录用户输入，其中可能包含身份证号、手机号等个人身份信息（PII）。因此，数据脱敏机制必须成为日志流水线的 “标配环节”：在数据长期存储前，需通过技术手段自动过滤或加密 PII 信息，既符合《个人信息保护法》等隐私法规，也能避免用户数据泄露风险。这不是 “可选项”，而是智能体合规运营的底线。
3. 平衡数据粒度与系统开销
   若对生产环境中每一次请求都记录高细节日志（如 DEBUG 级别），会导致两大问题：一是存储与计算成本飙升，二是系统 latency（延迟）增加。解决之道在于 “动态采样” 这一最佳实践：
   • 开发环境：使用高粒度日志（DEBUG 级别），方便工程师调试代码、验证逻辑；
   • 生产环境：默认采用低粒度日志（INFO 级别），同时按场景灵活采样 —— 例如仅追踪 10% 的成功请求，用于统计整体性能；但对 100% 的错误请求完整记录轨迹，确保每个故障都有详细诊断数据。
     这种方式既能为指标计算提供足够的性能样本，又不会让系统过载，实现 “成本可控” 与 “故障可查” 的双赢。

1.5. 总结

在 AI 智能体（Agent）技术飞速发展的今天，如何让具备自主性与非确定性的智能体突破传统软件质量模型的局限，成为企业可信赖的工具？本文将整合白皮书核心内容，拆解智能体质量保障的 “飞轮体系” 与三大核心原则，为落地企业级智能体提供行动蓝图。

1.5.1. 从 “能做事” 到 “可信任” 的跨越

AI 智能体的特殊性在于其 “自主决策” 能力 —— 它不像传统软件那样遵循固定逻辑，而是会基于模型推理、工具调用、环境交互动态调整行为。这种特性让评估标准从 “任务是否完成” 升级为 “任务如何完成”：效率是否最优？操作是否安全？用户体验是否良好？毕竟，当智能体的失误可能引发业务风险（如金融领域的决策偏差、医疗场景的建议错误）时，“盲目部署” 绝不可行。
为应对这一挑战，白皮书首先确立了智能体质量的四大支柱，作为所有评估与优化的核心目标：

• 有效性：是否精准达成用户真实意图（如零售智能体不仅要找到商品，更要推动转化）；
• 成本效益：完成任务的资源消耗是否合理（如避免过多工具调用、冗余推理步骤）；
• 安全性：是否符合伦理边界与合规要求（如规避偏见、防止数据泄露）；
• 用户信任：是否能持续提供可靠、可解释的服务，建立长期信任关系。

1.5.2. 智能体质量飞轮：让系统 “自我进化”

优秀的智能体不仅能稳定执行任务，更能通过持续评估不断优化。白皮书提出的 “智能体质量飞轮”，正是将 “定义质量 - 观测行为 - 评估过程 - 反馈迭代” 整合为闭环的运营体系，像推动一个重型飞轮般，从初始的 “费力启动” 到后续的 “惯性加速”，形成质量与信任的良性循环。其四大核心步骤如下：

步骤 1：定义质量（明确方向）

飞轮的第一步是锁定目标 —— 以 “四大质量支柱” 为具体标准，而非抽象的 “好与坏”。例如，为客服智能体设定 “有效性” 指标为 “用户问题解决率≥90%”，“安全性” 指标为 “敏感信息泄露率 = 0”，让后续评估有明确依据。

步骤 2：构建可见性（筑牢基础）

“看不见的过程无法管理”。通过可观测性实践（对应白皮书第 3 章），让智能体生成两类关键数据：

• 结构化日志：像 “智能体日记”，记录每一步操作（如 “15:30 调用天气 API，参数为北京”）；
• 端到端轨迹：像 “叙事线索”，串联零散日志，呈现完整决策链（如 “用户请求→LLM 规划→工具调用→结果生成”）。
  这些数据是衡量 “四大支柱” 的 “证据库”，也是飞轮转动的核心燃料。

步骤 3：评估过程（驱动运转）

有了可见性数据，下一步就是用 “由外而内” 的评估框架（对应白皮书第 2 章）判断性能：

• 外部评估（黑盒视角）：看最终输出是否达标（如任务成功率、用户满意度）；
• 内部评估（玻璃盒视角）：拆解决策轨迹，定位问题根源（如 “推理逻辑混乱”“工具调用参数错误”）。
  评估时需结合 “自动化工具” 与 “人类判断”：用 LLM-as-a-Judge 实现规模化评分（如批量检测输出准确性），用人机协同（HITL）处理复杂场景（如医疗、法律领域的专业验证），兼顾效率与精准度。

步骤 4：构建反馈循环（加速惯性）

飞轮的关键在于 “失败即资产”—— 将生产环境中捕获的每一次失误（如智能体生成错误金融建议、未识别 API 异常），通过标注转化为 “黄金评估集” 中的回归测试用例。这样一来，系统会从错误中学习：下次遇到类似场景时，自动规避风险，实现 “越用越聪明” 的自我进化。

1.5.3. 三大核心原则：落地可信智能体的 “底层思维”

若只能记住白皮书的一个知识点，那一定是这三条原则 —— 它们是所有技术实践与运营策略的 “指南针”：

原则 1：评估是 “架构级设计”，而非 “最后一步测试”

就像一级方程式赛车从设计之初就嵌入遥测传感器，而非赛后加装一样，智能体的 “可评估性” 必须从第一行代码开始规划。例如，在开发初期就定义日志格式、轨迹采集规则，让后续的质量分析无需 “返工补课”。质量不是 “测试出来的”，而是 “设计出来的”。

原则 2：轨迹即真相，过程比结果更重要

智能体的最终输出只是 “故事的最后一句话”，真正决定质量的是其 “思考过程”。比如，两个客服智能体都回答了用户的物流问题，但一个是通过精准调用物流 API 获取实时数据，另一个是靠模型 “ hallucination（幻觉）” 生成虚假信息 —— 仅看结果无法区分优劣，只有分析完整轨迹才能判断可靠性。而这一切，都依赖于步骤 2 中构建的深度可观测性。

原则 3：人类是最终仲裁者，自动化是辅助工具

自动化（如 LLM 评估、安全过滤器）能解决 “规模化” 问题，但 “好” 的定义、微妙场景的判断（如客服语气是否亲切、法律建议是否合规）必须锚定人类价值观。就像 AI 可以帮老师批改试卷，但评分标准（什么是 “A+”）、作文的创意与逻辑判断，最终仍需人类决定。

1.5.4. 未来：可靠的 Agentic

当前正处于智能体时代初期，打造具备推理、规划与行动能力的 AI 是极具变革性的技术突破，但能力提升伴随构建可信系统的重大责任。

掌握 “评估工程”（即白皮书所阐述的智能体评估理念与方法）是下一波 AI 竞争的核心差异点。若仍将智能体质量视为事后补充，会陷入 “演示前景好、落地却失败” 的循环；而投入资源建立严谨且与架构深度融合的评估体系，才能突破概念炒作，落地真正具备变革力的企业级 AI 系统。

智能体研发的终极目标不只是 “能运行”，更是 “被信任”。这种信任并非偶然，而是通过持续、全面且架构层面可靠的评估体系逐步构建而成。

2. 代码实验室

2.1. Log in Develop

• 通过 Web 界面运行 Agent 然后观察 lm_call 和 tool_call 的具体细节内容
• 通过本地 debug 级别日志查看LLM 请求和回复的具体细节

2.2. Log in Production

通过 Callbacks 回调函数添加日志到代码中

Google ADK 支持将 Callbacks 封装进自定义 Plugin 或者使用内置的 LoggingPlugin 自动捕获 Agent 活动。

from google.adk.runners import InMemoryRunner
from google.adk.plugins.logging_plugin import (
    LoggingPlugin,
)  # <---- 1. Import the Plugin
from google.genai import types
import asyncio

runner = InMemoryRunner(
    agent=research_agent_with_plugin,
    plugins=[
        LoggingPlugin()
    ],  # <---- 2. Add the plugin. Handles standard Observability logging across ALL agents
)

print("✅ Runner configured")

LangGraph 内部有 BaseCallbackHandler 同样可以实现回调函数；LangSmith 可以实现 Web 页面观察 Trace Timeline；使用开源的 LangFuse 也可以实现观测和分析。

2.3. Evaluation

• Web界面运行保存成功的用例用于后续在运行时评估对比使用
• 用 JSON 文件记录多个场景运行成功用例+评估标准，Agent批量执行这些场景并和JSON记录结果进行自动化型评估

LangGraph 原生没有 Evaluation 模块，不过实现起来很简单。

参考文献：
5-Day AI Agents Intensive Course with Google
Agent Quality
Day 4a - Agent Observability
Day 4b - Agent Evaluation