评估 AI Agent 技能：用 Langfuse 让技能质量变得可衡量

译注： 本文翻译自 Langfuse 技术博客，原作者 Lotte Verheyden。原文链接：Evaluating AI Agent Skills。译文在保留原文核心观点的基础上进行了意译润色，并保留了所有原始配图。

2026 年 2 月 26 日

我们为 Langfuse 构建了一个 AI Agent 技能，让代理能够使用 Langfuse：通过 CLI 访问 API、查阅文档、遵循可观测性最佳实践。但你怎么知道代理真的正确使用了这个技能？ 当你修改技能时，又怎么知道它变好了而不是变差了？我们用 Langfuse 找到了答案。

评估方案

你可以通过以下方式系统性地评估一个技能：将一组用户提示词作为数据集（Dataset）存储在 Langfuse 中，用这些提示词运行实验------即启动编码代理来处理这些提示词，并追踪代理的行为。基于结果改进技能，然后再次运行流水线来衡量质量变化。

这种方法将技能评估视为类似于 prompt 评估：定义输入、捕获行为、为输出评分，然后迭代。OpenAI 为 Codex 技能描述了一个类似的循环，使用 JSONL 追踪和确定性评分器。核心理念是一样的：让技能质量变得可衡量，从而系统性地改进它。

数据集

我们创建了 2 个数据集：

数据集	描述
cli-tests	一组用户提示词，代理应当使用 CLI 来访问 Langfuse。
instrumentation-tests	一组使用相同用户提示词 `"用 Langfuse 为我的应用做插桩（instrument my application with Langfuse）"`的数据，每次指向一个包含小型已有应用的文件夹。

预期输出是一组需要 LLM 评判器（LLM-as-a-judge）来验证的事项清单。

实验设置

我们使用 Claude Agent SDK 来运行代理。你可以按照这份集成指南轻松将 Langfuse 与 Claude Agent SDK 集成。

想跟着一起做？这个评估设置的完整代码在这个示例仓库中。

仓库结构

该仓库由运行实验的脚本和启动代理所需的仓库组成。技能全局安装在 Claude 账户上。

arduino 复制代码

run-experiment-auto.py
.env
agent-sandbox-repos
  ├── default-hello-world
  ├── langchain-chain
  └── ...

启动代理

每次实验运行都会在一个测试仓库中启动一个代理。有几点需要注意：

注入上下文

Langfuse 凭证作为环境变量注入，使代理可以直接与 API 和 CLI 交互。

Langfuse 技能 全局安装在 Claude 账户上，因此我们需要在 ClaudeAgentOptions 中设置 setting_sources=["user", "project"] 来让代理访问全局技能。

权限设置为 bypassPermissions，以避免代理在等待用户输入时卡住。

python 复制代码

options = ClaudeAgentOptions(
    max_turns=args.max_turns,
    cwd=item_cwd,
    permission_mode="bypassPermissions",  # 我们不想让代理卡在等待权限确认
    setting_sources=["user", "project"],
    stderr=lambda line: stderr_lines.append(line),
    env=_load_agent_env(item_cwd),
)

重置仓库

每次运行后，仓库会被重置到原始状态，这样下一次运行从干净的基础开始。这对于 instrumentation 数据集尤其重要------因为代理会修改应用代码：你希望每次运行都从相同的基线开始。

追踪代理

代理的行为被追踪到 Langfuse，这为我们提供了每次工具调用、CLI 命令和文件编辑的完整记录。

Langfuse 技能

Langfuse 技能赋予 AI 代理两项核心能力：通过 Langfuse CLI 进行编程式 API 访问 ，以及通过 llms.txt、页面抓取和搜索进行文档检索 。你可以在这篇情人节博文和这篇关于自动提示词改进的博文中了解更多关于技能的内容。

在撰写本文时，我们还有一些针对更具体用例的独立技能，比如 prompt 迁移和为已有代码做插桩。最终目标是将这些合并到主 Langfuse 技能中，让用户只需安装一个。

改进技能

在知道该改进什么之前，我们需要先查看第一次数据集运行的追踪。以下是一次 Claude Agent SDK 运行的追踪示例：

你可以立即看到技能在追踪中被相对较早地调用了------这是个好迹象。深入每一步会发现更多关于代理行为的信息。有几个问题立刻凸显出来：

大量 CLI 命令导致了错误。
代理有时会切换到使用 Curl 命令而非 CLI。
代理有时会编造不存在的 CLI 资源和操作。
代理有时完全不使用技能。

基于这些观察，我们确定了每次迭代需要跟踪的初始指标 ：每次运行的 CLI 错误数、成功前的重试次数、以及代理是否回退到 Curl 或完全跳过了技能。一旦 CLI 使用稳固了，我们就可以转向更高级的问题，比如代理是否真的在遵循插桩最佳实践。

第 1 轮迭代：未强制使用 Langfuse URL

第一次实验运行在超过 90% 的情况下显示了相同的模式：代理会检查凭证是否已设置，使用一条 CLI 命令，然后得到错误 No server URL found。在某个时刻，它会尝试变通方法------显式地用 --server 设置服务器，而不是使用环境变量。这种行为引入了 1-2 次不必要的 CLI 往返。

根本原因在技能本身。在我们展示如何设置环境变量的示例中，有一条注释说 Langfuse 主机地址是可选的。

bash 复制代码

export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...
export LANGFUSE_BASE_URL=https://cloud.langfuse.com

只需把那条注释从"可选"改为"必填"，代理就开始预先检查它并在缺失时设置它。该特定错误的重试次数立即降到了零。你可以在这个提交中看到修改前后的对比。

第 2 轮迭代：幻觉出的 CLI 参数

修复了服务器地址问题后，第二种模式凸显出来：代理会编造不存在的 CLI 资源和操作。

text 复制代码

> npx langfuse-cli api prompts get --name summarizer
Exit code 1
error: unknown option '--name'

CLI 在每个层级都有 --help 让你发现可用选项，但代理只有在遇到错误后才会使用它，而不是主动使用。这导致 Langfuse CLI 命令的平均错误率为 25%。

在技能中添加明确指令，告诉代理始终使用 --help 来发现可用内容，将 Langfuse CLI 错误降到了零。

值得注意的是，代理需要的操作数量实际上并没有减少。重试消失了，但被每条命令之前的 --help 调用取代了。零错误比不断重试好，但效率差距告诉我们下一步该投资在哪里：在 CLI 的顶层暴露更多信息，让代理减少发现步骤。

第 3 轮迭代：技能调用问题

现在该转向第二个目标了：将可观测性最佳实践融入主技能。我们添加了一份关于插桩指南的新参考文档，并重写了主 SKILL.md，使其更具概念性------将技能定位为"有效地使用 Langfuse"，而不是仅仅列出 CLI 和文档访问方式。

	描述
修改前	与 Langfuse 交互并访问其文档。在需要通过 CLI 以编程方式查询或修改 Langfuse 数据------追踪、prompt、数据集、评分、会话和任何其他 API 资源时，或查阅 Langfuse 文档、概念、集成指南或 SDK 用法时使用。此技能涵盖基于 CLI 的 API 访问（通过 npx）和多种文档检索方法。
修改后	跨用例有效使用 Langfuse 的技能：插桩、prompt 管理、调试和数据访问。包含核心原则、工作流和针对特定用例的最佳实践。

结果是技能完全不再被调用。像"获取最近十条追踪"这样的用户提示词，之前能正常工作，现在却让代理去本地仓库里找日志，甚至去用竞品而不是 Langfuse。技能完全没有被考虑到。

经过几次迭代后，我们回到了一个非常相似的描述，但添加了新的参考文档。这个提交展示了修改前后的对比。

第 4 轮迭代：评估自动插桩

如何评估一个复杂任务的结果是否正确？我们做了以下工作来验证代理是否能用 Langfuse 可观测性正确插桩一个已有应用：

这需要略微不同的评估设置。每次 Claude Agent SDK 运行都以相同的提示词开始，但在不同的子文件夹中，每个文件夹包含一个小型已有应用。一个文件夹可能是基本的 OpenAI 聊天应用，另一个可能是 LangChain RAG 管道。数据集的输入和预期输出据此调整。

这就是 LLM 评判器（LLM-as-a-judge）发挥作用的地方。检查插桩是否正确不能通过字符串匹配来完成。LLM 评判器可以将代理的修改与预期输出进行对比，并对插桩是否正确进行评分。

经验总结

从这个过程中总结出几点经验：

魔鬼藏在细节里。 一条注释写了"可选"而不是"必填"，就导致了每个测试用例的一致性失败。
明确表达技能的价值。 当我们让技能描述更抽象时，代理就不再能识别什么时候该使用它了。特定的关键词匹配极其重要。
人工审查追踪非常有价值。 数字告诉你出了问题，但逐步查看单条追踪才能找到原因。

后续计划

还有很多可以改进的地方。以下是一些考虑：

在 references 文件夹下添加具体的最佳实践。这需要配套的数据集来测试技能。
提升技能的效率，即减少 CLI 调用次数。
自动插桩技能仍有改进空间，特别是在复杂场景中。

如果你想自己尝试这些技能，可以在 Langfuse Skills GitHub 仓库中找到它们。