Agent 可观测性+eval

AI Agent 应用的在线可观测性（Observability）和评估（Evaluation）系统的设计方案。

它的核心目标是替代现有的、部署和维护成本较高的 Langfuse 平台，构建一个更轻量、易维护、且能满足特定需求（如与现有 Agent 代码集成、进行自动化评估）的内部平台。

具体是做什么？

在线可观测性 (Observability/Trace):
- 目的: 记录和追踪 Agent 应用的运行过程，特别是它与大型语言模型（LLM）的交互以及内部工具调用（Tool Calling）的详细情况。
- 内容: 收集 Agent 一次完整交互（称为 Trace）以及其中的各个步骤（称为 Span/Observation）的详细信息，包括：
  - Trace: 整个交互的开始/结束时间、用户输入 (input)、Agent 输出 (output)、使用的模型、Token 消耗量、会话 ID (session.id)、Agent 身份 (resource_attributes.service.name) 等。
  - Span: Agent 内部的特定操作，如一次 LLM 调用（generation 类型）或一次工具调用。记录其名称、开始/结束时间、输入/输出、调用的模型、Token 消耗 (usage_details)、关联的会话 ID 等。
自动化评估 (Evaluation/Eval):
- 目的: 自动化地评估 Agent 的性能，特别是其输出质量和工具调用的正确性。
- 方法: 基于收集到的 Trace 和 Span 数据，使用另一个 LLM（Evaluator LLM）作为“裁判”，根据预定义的评估标准（Prompt）对 Agent 的响应进行打分。
- 内容:
  - Dataset (数据集): 用于评估的测试用例集合，包含输入（问题/场景）和期望的输出（或评判标准）。
  - Prompt (评估提示词): 定义评估标准和指导 Evaluator LLM 如何打分的指令和示例。
  - Dataset Run Item: 记录一次评估运行（用一个测试用例评估一个 Agent）的关联信息。
  - Score (评分): Evaluator LLM 给出的评估分数和理由。

具体是怎么做的？

整个流程可以分为几个阶段：

数据收集 (Data Collection / Trace):
- Agent 集成: Agent 应用代码中集成了追踪库（兼容 OpenTelemetry (OTEL) 规范，可能也兼容 Langfuse SDK），在关键节点（如接收用户输入、调用 LLM、调用工具、生成最终输出）记录 Trace 和 Span 数据。
- 数据上报: Agent 将这些结构化的 Trace/Span 数据发送到自建的后端服务进行存储。
数据存储 (Data Storage / Data Model):
- 定义数据模型: 文档中详细定义了 Trace, Span, Prompt, Dataset, Dataset Item, Dataset Run Item, Score 等数据实体的结构和字段，确保收集到的数据格式统一、信息完整。
评估准备 (Eval Preparation):
- 创建 Prompt 模板: 设计并上传用于评估的 Prompt 模板到平台。例如，设计一个评估回答相关性的 Prompt，包含评估标准、示例和待评估数据的占位符。
- 创建 Dataset:
  - 数据生成: 通过人工编写或使用 LLM 生成测试用例（问题/场景）。文档中提到了使用 LLM 根据可用工具列表生成不同难度（基础、中级、高级）的问题。
  - 数据处理: 对生成的数据进行改写（Rephrase）以增加多样性，并进行清洗和去重（基于文本 Embedding 的相似度）。
  - 上传 Dataset: 将处理好的测试用例作为 Dataset Item 上传到平台。
执行评估 (Performing Evaluation):
- 启动 Agent: 启动待评估的 Agent 应用。
- 运行测试: 系统遍历 Dataset 中的每个 Item（测试用例）。
- 触发 Agent 交互: 将测试用例的输入发送给 Agent，并等待其处理完成（通常通过 Session ID 关联整个交互过程产生的所有 Trace）。
- 获取 Trace 数据: 等待 Agent 完成交互并将完整的 Trace 数据上报到后端。
- 执行 Eval: 系统根据预设的评估逻辑（通常是基于 LLM 的）：
  - 获取相关的 Trace/Span 数据（如用户输入、Agent 输出）。
  - 获取对应的评估 Prompt 模板。
  - 将 Trace 数据填充到 Prompt 模板中，形成具体的评估指令。
  - 调用 Evaluator LLM（如 GPT-5）执行评估。
  - 解析 Evaluator LLM 的输出，提取评分（Score）和评语（Comment）。
- 记录结果: 将解析出的 Score 和相关信息作为 ingestion_event 存储到系统中，与对应的 Trace/Run Item 关联。
结果分析 (Analysis):
- 虽然文档没有详细展开，但最终目的是能够查询和分析这些评估分数，以了解 Agent 在不同维度（如相关性、工具调用准确性等）上的表现。