智能体评估

Yuxi 的智能体评估用于回答一个具体问题：某个 Agent 在一组固定任务上能不能稳定完成工作。它不在 Yuxi 内部维护评估数据集、评分规则或对比报表，而是把这些能力交给 Langfuse；Yuxi 只负责按真实 Agent 运行链路执行每条样例，并把结果回写到 Langfuse experiment。

适用边界

这个功能面向 Agent 端到端行为评估，不是知识库检索指标评估。如果你要评估 RAG 检索召回、答案准确率和知识库基准，请使用「知识库评估」。如果你要评估一个 Agent 在编程、研究、工具调用、规划或多步骤任务上的真实表现，则使用本页介绍的 Langfuse dataset experiment 流程。

评估链路保持三个边界：

Langfuse 负责 dataset、experiment、score、对比和可视化。
Yuxi 后端负责创建正常 conversation 和 AgentRun，并复用 worker 执行链路。
yuxi CLI 只负责读取 Langfuse dataset、运行 experiment、调用 Yuxi eval API，不负责创建或上传 dataset。

前置条件

Yuxi 后端已经启用 Langfuse tracing，并在 .env 中配置：

bash

LANGFUSE_PUBLIC_KEY=...
LANGFUSE_SECRET_KEY=...
LANGFUSE_BASE_URL=https://cloud.langfuse.com

本机 CLI 环境也能读取同一组 Langfuse 环境变量。yuxi agent eval 需要直接调用 Langfuse SDK 读取 dataset 和创建 experiment。
已经登录 Yuxi CLI：

bash

yuxi remote add local http://localhost:5173
yuxi login --browser

评估命令必须使用当前 remote 的登录态，不支持在 yuxi agent eval 上直接传 token。CI 环境也必须先执行登录步骤，例如：

bash

yuxi login --api-key "$YUXI_API_KEY"

要评估的 Agent 已经存在，并且当前 CLI 登录用户有权限访问该 Agent。命令使用的是 Agent slug，例如 default-chatbot。

准备 Langfuse Dataset

评估数据集必须先在 Langfuse 中准备好。CLI 不提供上传能力，避免把数据集管理职责混进运行命令。

Dataset item 的 input 推荐使用下面任一字段承载任务文本：

json

{"input": "请用 Python 完成任务并给出最终答案：..."}

也兼容 query、question、prompt。expected_output 可以写标准答案，后续在 Langfuse UI 或 evaluator 中使用。

运行评估

上传 dataset 后，用 dataset name 运行：

bash

yuxi agent eval \
  --dataset-name yuxi-python-tasks-20260619-demo \
  --agent-slug default-chatbot \
  --experiment-name default-chatbot-python-tasks-20260619 \
  --max-concurrency 1 \
  --timeout-seconds 900

命令执行流程：

从 Langfuse 读取 dataset。
对每条 dataset item 提取任务文本。
调用 POST /api/agent/eval/runs。
Yuxi 后端创建正常 conversation 和 AgentRun。
worker 按真实 Agent 链路执行任务。
接口阻塞到 run 终态后返回最终 assistant output。
CLI 将 output 写回 Langfuse experiment item。

--max-concurrency 控制 Langfuse experiment runner 的并发数。复杂 Agent 或本地开发环境建议从 1 开始，避免同时压垮模型服务、worker 或沙盒。

查看结果

评估完成后，在 Langfuse 控制台打开对应 dataset，可以看到刚创建的 experiment run。每条 item 会保存本次 Yuxi Agent 的最终输出。Yuxi 后端也会给评估运行写入 agent_evaluation 标记，方便在 Langfuse traces 中筛选：

source=agent_evaluation
evaluation_dataset_name=<dataset name>
evaluation_dataset_item_id=<item id>
evaluation_experiment_name=<experiment name>

如果没有看到 experiment，先确认 CLI 环境中的 Langfuse key 和 dataset name 是否正确。如果 experiment 有记录但 Yuxi trace 缺失，检查 api-dev 容器是否读取到了同一组 Langfuse 配置。

智能体评估 ​

适用边界 ​

前置条件 ​

准备 Langfuse Dataset ​

运行评估 ​

查看结果 ​

智能体评估

适用边界

前置条件

准备 Langfuse Dataset

运行评估

查看结果