一、概述
Agent 的调试与测试通过四个层次完成：
| 层次 | 解决什么问题 | 入口 |
| ChatUI 预览体验 | 直接对话验证 Agent 是否能正常工作 | Agent 概览页右侧 |
| Trace 追踪 | 排查具体一次调用为什么慢 / 出错 / 答错 | MLflow 实验 > 跟踪 |
| 评估器（Evaluator） | 自动化打分（相关性、安全性、正确性），规模化评估 | MLflow 实验 > 评估器 |
| 智能调优（ALHF） | 把人工反馈转化为 Agent 行为改进 | Agent 详情页 > 智能调优 |
二、前提条件
·已创建并启动 Agent，详见 创建与管理 Agent。
·当前账号对 Agent 关联的 MLflow 实验具备 CAN_EDIT 权限。
三、使用限制
| 限制项 | 说明 |
| 单个实验下 Trace 数量 | 最多支持 100,000 条 |
| LLM 评估器类型 | 支持 LLM 评估器（相关性 / 安全性 / 正确性），代码评估器后续支持 |
| 评估运行对比 | 支持单 Run 查看，多 Run 横向对比后续版本支持 |
| 评估反馈 / 期望卡片 | 单条 Trace 的反馈、期望数量上限详见平台说明 |
五、入口
进入 Agent 概览页，右侧默认嵌入 ChatUI 模板预览体验窗口；也支持在新标签页独立打开。
六、能力清单
| 能力 | 说明 |
| 消息发送 | 文本输入，Enter 发送，Shift + Enter 换行；模型回答中不能发送新消息，可点击停止 |
| 思考过程 | 模型回答前显示「思考中」；思考完成后展示意图理解、执行步骤、模型输出 |
| 工具调用展示 | 区分 Tools / Agent 调用，调用过程显示 Loading，完成后打勾并显示耗时；点击展开查看输入 / 输出 / 耗时 |
| 流式输出 | 模型输出按流式渲染，支持 Markdown 富文本（代码块 / 表格 / 列表） |
| 回答操作 | 点赞 / 点踩（结果会进入 ML Trace） / 复制回答内容 |
| 会话上下文 | 单个会话内模型自动联想上下文 |
| 新增会话 | 关闭当前会话开启新会话 |
| 会话历史 | 需指定一个可存储会话历史的数据库，详细配置详见平台说明 |
| 推荐问题 | 初始态展示固定推荐问题，点击可直接对话 |
注意：ChatUI 是 Agent 上线后用户实际看到的对话界面。建议在调试阶段就把 Agent 的「开场白、推荐问题」配置到位，提升上线后的首次使用体验。
七、Trace 追踪（可观测）
每次 Agent 问答都会生成一条 Trace，自动落入关联的 MLflow 实验。Trace 包含完整调用链：模型调用、工具调用、子 Agent 调用、Token 消耗、耗时等。
八、进入入口
1. 在 Agent 概览页点击 追踪评测 模块快捷入口。
2. 或从 MLflow 实验列表打开实验 → 左侧 可观测性 > 跟踪 。
九、Trace 列表字段
| 字段 | 说明 |
| Trace ID | 全局唯一 ID，点击打开 Trace 详情 |
| Request | 请求内容 |
| Response | 响应结果 |
| Session | 会话 ID |
| User | 执行用户名 |
| Trace name | Trace 命名 |
| Version | Agent 版本，点击跳转到对应版本 |
| Tokens | 消耗 Token 数 |
| Execution time | 执行时长 |
| Request Time | 请求时间 |
| Run name | 关联运行名称（如来自评估运行），无则展示空 |
| Source | 产生 Trace 的入口点或脚本名称 |
| State | 状态：正常 / 错误 |
支持自定义字段过滤、按 Request 模糊搜索。
十、Trace 详情：总览
点击 Trace ID 打开详情弹窗。「总览」展示如下：
| 区域 | 说明 |
| 基础信息 | 状态（OK / ERROR / IN_PROGRESS）/ Trace ID / Token 消耗 / Trace 耗时 |
| 输入 | 用户输入内容、上下文 |
| 调用链 | 大模型 / 子 Agent / 工具的实际调用链；默认收起，点击展开查看每一步的输入 / 输出 / 耗时 |
| 输出 | Agent 给用户的最终输出 |
| 评估项 | 相关性、安全性、用户反馈等评估结果（仅展示，不支持编辑） |
十一、Trace 详情：详情 & 时间线
切换到 「详情 & 时间线」 Tab，可看到树形结构展示的所有 Span（每个 Span 是一个独立操作单元，类型包括大模型调用、工具调用、Agent 调用等）。每个 Span 提供：
·聊天 ：当 Span 输入、输出符合 OpenAI Chat Completions 消息格式时自动渲染对话视图。
·输入、输出 ：按需展示 Span 的输入信息和输出内容（JSON 自动格式化）。
·属性 ：键值对形式展示模型、工具等结构化属性。
·事件 ：Span 执行期间的离散事件（如异常堆栈、错误信息）。
支持搜索关键词，覆盖各节点的调试信息，过滤左侧目录树。
十二、Trace 详情：右侧评估区
每条 Trace 的详情弹窗右侧是评估区，可对该 Trace 添加：
| 评估类型 | 用途 |
| 反馈（Feedback） | 对 AI 已生成回答的质量评分（如「这次回答好不好」） |
| 期望（Expectation） | 对该问题的「理想回答」应该满足的约束（如「必须引用知识库」） |
每条反馈、期望支持以下字段：
| 字段 | 取值范围 |
| 评估类型 | 反馈 / 期望 |
| 评估名称 | ≤ 100 字符；不支持名称中含 . 字符 |
| 数据类型 | 布尔型 / 字符串 / 数字 |
| 评估值 | 字符串 ≤ 500 字符 |
| 评估依据 | 给出该评估的原因，便于后续追溯 / 训练，≤ 500 字符 |
反馈、期望卡片支持展开、收起，可编辑、删除。
十三、评估器（Evaluator）
评估器是对 Agent 输出做自动化打分 的逻辑。当前支持 LLM 评估器，代码评估器后续版本支持。
十四、进入入口
1. 进入 Agent 关联的 MLflow 实验。
2. 左侧导航 评估 > 评估器 。
十五、预置 LLM 评估器
平台预置 3 类 LLM 评估器：
| 类型 | 评估目标 | 输出 |
| 正确性 | 答案是否事实正确（无需自定义 Prompt，下拉选择即可） | yes / no |
| 相关性 | 答案是否回答了问题（不关注正确性 / 完整性） | yes / no |
| 安全性 | 内容是否违反安全策略（仇恨言论、骚扰、暴力煽动等） | yes / no |
十七、步骤 1：打开新建弹窗
在评估器列表点击 新建 LLM 评估器 。
十八、步骤 2：配置通用、评估标准、自动评估
| Tab | 配置项 |
| 通用 | 评估器名称、评估描述 |
| 评估标准 | 选择评估模型（下拉选择已有大模型）、选择内置 LLM 评估器（正确性 / 相关性 / 安全性） |
| 自动评估 | 是否开启自动评估、采样率、筛选字符串（仅对符合筛选条件的 Trace 自动跑评估） |
十九、步骤 3：保存并查看评估器卡片
保存后回到评估器列表，每张卡片显示：
·评估器名称
·评估器类型（LLM 评估器）
·是否在所有未来跟踪上运行
·采样率（基于已配置 Trace 结果计算）
·评估跟踪开启、关闭状态
·编辑按钮、更多（删除）
卡片支持展开、收起，编辑后即时生效。
20、评估运行（Evaluation Runs）
评估运行用于展示和管理 对 Agent 做的多次评估结果，方便对比不同版本、不同提示词配置的表现。
21、进入入口
进入 MLflow 实验 → 评估 > 评估运行 。
22、评估运行列表
| 字段 | 说明 |
| 运行名称 | 自定义名称（如「人工审查 v3」） |
| 创建于 | 评估创建的日期时间 |
| 数据集 | 关联的评估数据集名称，可点击跳转 |
| 版本 | 关联的 Agent 版本，无则显示 – |
| 状态颜色标识 | 红 / 绿 / 黄 / 棕等彩色圆点，自定义标记 |
| 内置 LLM 评估维度 | 当实验配置了内置 3 类评估器时，列表显示对应维度的评估结果 |
操作：
·删除 ：勾选单个、多个运行删除（需确认）。
·比较 ：勾选 2 个运行进入对比视图（后续版本支持）。
·刷新 ：拉取最新数据。
23、单 Run 详情：会话与跟踪列表
点击某个运行后，右侧加载该运行下的所有会话与跟踪：
| 字段 | 说明 |
| 会话 | 仅在「按会话分组」开启时显示 |
| 跟踪 ID | 唯一标识单次模型调用，可点击展开 Trace 详情 |
| 请求 | 用户输入 |
| 响应 | 模型应答 |
| 执行时间 | 精确到毫秒 |
| 状态 | 确定 / 错误 |
支持按 Trace ID / 请求、响应 关键词搜索。
支持通过列配置选择展示属性、评估、期望三类字段；评估、期望项默认展示 3 个，可在列配置中自定义数量。
24、智能调优（ALHF）
智能调优是 DataBuddy 面向业务人员的核心差异化能力，通过「人类反馈 + AI 推荐」闭环让 Agent 自动优化。
25、调优四阶段
1. 配置阶段：提供参考问答对（数据来源：Trace 历史 / 文件上传 / 手动输入） │ ▼2. 反馈阶段：对推荐问答评估"好 / 不好 / 跳过" │ ▼3. 优化阶段：系统自动提取语义记忆，生成推荐 Guidelines │ ▼4. 保存并更新：自动优化Agent的Prompt、 MCP描述等，提升Agent效果
26、入口
1. Agent 概览页 → 智能调优入口卡片 → 点击 开始调优 。
2. 或 Agent 详情页顶部导航 → 点击 智能调优 Tab。
27、步骤 1：配置参考问答对
进入「问答配置」面板，选择问答对来源：
| 来源 | 适用场景 | 操作要点 |
| 从 Trace 历史导入 | Agent 已有线上请求记录 | 穿梭框弹窗选择，至少选 3 条 Trace |
| 从本地文件上传 | 问答对存在本地文件中 | 下载模板，上传 xlsx / csv，单文件 ≤ 200 MB |
| 手动输入 | 冷启动，无历史数据 | 每行两个输入框（问题 + 预期答案），至少 3 组并填完整 |
预览页可再次确认数量、删除条目（保留至少 3 条），可手动新增问题与预期答案。
注意：保存覆盖时，问题没有修改的条目 ID 不变，原有的反馈记录、反馈历史不会丢失。
28、步骤 2：推荐反馈
系统按以下逻辑推荐让用户反馈的对话：
·当前 Guidelines 尚未覆盖的典型场景。
·模型置信度较低的输出。
·冷启动阶段：直接展示前 50 条配置好的问答对。
每张卡片支持三种操作：
| 操作 | 含义 |
| 好 | 正向样本，存入情景记忆强化 Agent 行为 |
| 不好 | 负向样本，需展开文本框 + Ctrl + Enter 提交「不好的原因和期望答案」 |
| 跳过 | 记录但不作为优化依据；如系统认为仍需推荐，后续可继续推送 |
卡片评估后会有飞出动画，标题栏实时显示「剩余 X 条」。动画完成后才能操作下一张。
29、步骤 3：问答检查
通过「问答检查」模块查看所有已配置的问答，逐条对比 Agent 回答与预期答案：
·支持按关键字模糊搜索（覆盖问题和预期答案）。
·支持过滤「反馈过」的问答（已有反馈记录）。
·单条详情：展示问题、预期答案、Agent 实际回答；可点赞、点踩，与「推荐反馈」交互一致。
·历史反馈 ：展示最近 3 次反馈内容（不含「跳过」）。
31、评估准则（Guidelines）
定义「什么是好的回答」，每条 Guideline 同时用于：
·LLM Judge 评估打分。
·提示词优化时的约束条件。
系统会基于以下信息生成推荐 Guidelines：
·Agent 名称与描述。
·用户配置的问答对。
·用户在推荐反馈和问答检查中给出的反馈。
操作：
·逐条审查推荐 Guideline。
·点击 Accept 采纳，或 Reject 拒绝。
·也可点 + Add 手动添加。
·采纳后按钮变为「已采纳」（不可再次点击 Accept），但已采纳的 Guideline 在编辑区可删除。
32、提示词（Instructions）
定义 Agent 的高层目标和核心任务（如「你是一个专业的客服数据分析助手……」），控制回答风格、内容边界。
·Instructions 是方向性引导 。
·Guidelines 是具体评估和约束标准 。
·两者互补，建议同步维护。
33、步骤 5：保存并更新
点击右下角 Save and update 按钮，平台引擎自动把反馈和规则变更拆解，应用到：
·Prompt（提示词）
·Vector Index（向量索引）
·LLM Judge（评估器）
·Evaluation Dataset（评估数据集）
·MCP Tools（工具配置）
·Agent Config（Agent 配置）
注意：当前更新生效存在约 30 秒延迟。保存成功后会提示「已保存更新，预计将在 30 秒内生效，请稍后前往预览体验」，并提供 前往预览体验 快捷链接。
保存成功后，推荐反馈的内容也会异步刷新。
35、Q：智能调优中「好、不好、跳过」 三种操作的差别？
A：好 会强化当前回答模式（正向样本）；不好 需要给出原因和期望答案，作为负向样本和改进方向；跳过 不参与优化，但系统认为仍有价值时会再次推荐。
36、Q：评估器为什么要预置「相关性、安全性、正确性」三种？
A：这三种覆盖了 LLM 应用最常见的质量维度：相关性（是否回答了问题）、安全性（是否违反安全策略）、正确性（事实是否正确）。可以满足绝大多数初期评估需求，更细分的评估维度可通过自定义 LLM 评估器实现。
37、Q：如何在评估运行中对比两个版本的 Agent？
A：当前暂不支持多 Run 横向对比，后续版本会支持勾选 2 个运行进入对比视图。当前可通过为不同版本打不同的「版本标识」，再分别查看 Run 详情人工对比。
38、相关文档
·创建与管理 Agent
·配置 Agent 工具与知识库
·发布与部署 Agent
·Studio 概述