experiments

为 Agent 运行实验

实验是部署前的批量测试。它们会在数据集上运行应用，并使用可复用的评估器比较输出。适用于提示词和模型对比、回归测试、基准测试和 CI 质量门禁。

移交生产环境评估请求

如果用户想要为实时轨迹或对话评分、监控生产环境质量，或拦截不安全流量，则此工作流并不适用。

1. 如果有 online-evaluations 技能，请立即加载并遵循其指引。

2. 否则，告诉用户使用以下命令安装：

   npx [email protected] add langwatch/skills/online-evaluations
   

不要使用此技能配置监控器或护栏。

实验与场景

当需要对许多单轮输入和输出示例进行可衡量的测试时，请使用实验。对于端到端的多轮行为和工具调用序列，请使用 scenarios 技能。

确定范围

对于“测试我的 Agent”这类一般性请求：

1. 阅读 Agent 代码、系统提示词、工具和相关 Git 历史记录。
2. 找出最可能发生回归的行为。
3. 创建特定领域的数据集。
4. 选择能衡量预期行为的评估器；如果目标是在候选方案中选出最佳方案，则进行对比。
5. 创建并运行实际实验。
6. 解读结果并提出具体的改进建议。

对于针对特定行为的请求，请聚焦该行为，同时仍需运行相应实验。

计划限制

LangWatch 免费计划对提示词、场景、评估器、实验和数据集数量设有限制。达到限制时，API 会返回 "Free plan limit of N reached..." 并附上升级链接。

处理方式：

• 在限制范围内操作。如果相关类型最多允许创建 3 个资源，就创建 3 个有意义的资源，而不是 10 个。
• 让每次创建都物有所值：每个资源都应体现明确价值。
• 先展示已完成的工作。如果达到限制，请总结已完成的内容，并说明升级计划可以提高限制。指向平台上的订阅设置；如果 CLI 指向可自托管端点，则指向许可证设置。读取 CLI 实际使用的端点，该端点可能来自 .env、进程环境变量或已保存的 CLI 配置。
• 请勿删除现有资源腾出空间，也不要挪用现有资源来规避限制。

前提条件

使用 langwatch docs <path> 以 Markdown 格式阅读文档。以下是一些实用的入口：

langwatch docs                                    # Docs index
langwatch docs integration/python/guide           # Python integration
langwatch docs integration/typescript/guide       # TypeScript integration
langwatch docs prompt-management/cli              # Prompts CLI
langwatch scenario-docs                           # Scenario docs index

使用 langwatch --help 和 langwatch <subcommand> --help 查找命令。列表和获取命令支持 --format json，可输出便于机器读取的结果。每个列表命令都支持 --limit <n> 限制行数，并支持 --jq <expr> 读取部分结果。分页列表会返回一个封装对象，因此请通过行数组统计行数（--jq '.traces | length'），并在 .pagination.total 读取总数。直接使用 --jq length 统计的是封装对象的字段数，而非行数。请先阅读文档，不要猜测 SDK API 或 CLI 标志。

如果无法使用 shell，可通过普通 HTTP 获取相同的 Markdown 文档。在任何文档路径后追加 .md（例如 https://langwatch.ai/docs/integration/python/guide.md）。索引：https://langwatch.ai/docs/llms.txt。场景索引：https://langwatch.ai/scenario/llms.txt 如果在使用此技能时遇到失败或困惑（命令损坏、文档与实际情况不符、需要绕过的错误），请先征得用户许可，然后运行 npx --yes langwatch report --user-approved，并附上 --title 和 --summary（或 --session <transcript.jsonl>），将问题发送给 LangWatch 团队，帮助他们直接确定需要修复的内容。无需登录或 API 密钥。没有 --user-approved 就不会发送任何内容；--dry-run 会打印确切的载荷，但不会发送。标题、摘要和转录内容会先在本地按模式进行脱敏：密钥和 API 密钥，以及电子邮件地址、电话号码、卡号和公共 IPv4 地址。未匹配任何模式的内容都会按原样发送，包括通过 --email 传入的联系地址。使用 --session 时，务必先运行 --dry-run 并让用户查看载荷，因为转录内容可能包含他们从未审阅过的信息。npx --yes langwatch report --help 会说明这些选项。

项目和 API 密钥：请指定真实项目，而不是个人项目。

LangWatch 有两种项目：

• 团队／共享项目：组织中的真实项目。评估、实验、提示词、数据集、模拟和埋点都必须始终以其中一个项目为目标。
• 个人项目：与单个用户关联的私有「My Workspace」临时空间。切勿将用户的评估、实验或生产跟踪数据发送到这里：它仅供个人探索使用，而且容易被误认为真实项目。

认证方式有两种：

• .env 中的项目 API 密钥（LANGWATCH_API_KEY）：这些技能中所有操作使用的凭据。它的作用范围限定为一个真实项目。这是默认方式；除非用户明确要求其他方式，否则优先使用它。
• langwatch login --device（AI 工具／SSO）：用于包装编码助手（langwatch claude、langwatch codex 等）的个人设备会话。它不适用于评估、提示词、数据集、场景或 SDK 埋点，并且会指向个人工作区。请勿运行它来设置这些技能中的工作。

因此，对于这些技能中任何读取或写入项目的操作，都要确保 CLI 可使用真实共享项目的 LANGWATCH_API_KEY。在本地，它位于项目的 .env 中；在 CI 中，运行器会将它注入进程环境，CLI 两者都能读取。请求新密钥前，先检查该变量是否已设置，并让 CLI 读取其值：切勿打印、复制或发送密钥。不要运行 langwatch login 来选择项目，也绝不要默认使用个人项目。同样要检查这些位置是否存在 LANGWATCH_ENDPOINT：如果已设置，说明项目位于可自托管实例上，CLI 会针对该端点而非 app.langwatch.ai 执行操作。

你读取的内容，不等于你要说的内容。 这些技能是供你使用的工作笔记，不是面向读者的文案。请从项目自身的 .env 中读取 LANGWATCH_API_KEY 和 LANGWATCH_ENDPOINT，以此了解应在哪里开展工作。不要从该文件读取其他内容：其中包含数据库、云服务和提供商凭据，这些都与你无关，而且你读取的每个值都可能进入你的上下文和命令输出。回答中不得出现任何描述你所运行机器的信息：工作区路径、容器端口、此工作器连接的地址。这些信息描述的是工作如何完成，而不是完成了什么；我们的主机信息对读者毫无意义。请说明你做了什么，以及可以在 LangWatch 的哪里找到结果。

编写代码前，请阅读实验文档：

langwatch docs evaluations/experiments/overview
langwatch docs evaluations/experiments/sdk

构建领域专属数据集

示例必须符合应用的实际功能。先阅读系统提示词、函数签名、工具和知识来源。

好的示例应类似用户向此应用提出的真实请求，并涵盖常规情况、边缘情况和过去出现过的问题。除非应用本身是问答系统，否则不要使用“2+2 等于多少？”或“法国的首都是哪里？”这类通用冷知识。

如果现有的 LangWatch 数据集适用，请使用 langwatch dataset list --format json 和 langwatch dataset get --help 检查。否则，请在代码中创建数据集，或使用 datasets 技能。

创建实验

使用与代码库匹配的 SDK。将凭据保存在环境变量中，并使用项目现有的依赖管理器。

Python

import langwatch
import pandas as pd

dataset = pd.DataFrame([
    {
        "input": "A realistic request for this application",
        "expected_output": "The expected behavior",
    },
])

experiment = langwatch.experiment.init("agent-regression")

for index, row in experiment.loop(dataset.iterrows()):
    response = my_agent(row["input"])
    experiment.evaluate(
        "ragas/response_relevancy",
        index=index,
        data={"input": row["input"], "output": response},
        settings={"model": "openai/gpt-6-luna", "max_tokens": 2048},
    )

TypeScript

import { LangWatch } from "langwatch";

const langwatch = new LangWatch();
const dataset = [
  {
    input: "A realistic request for this application",
    expectedOutput: "The expected behavior",
  },
];

const experiment = await langwatch.experiments.init("agent-regression");

await experiment.run(dataset, async ({ item, index }) => {
  const response = await myAgent(item.input);
  await experiment.evaluate("ragas/response_relevancy", {
    index,
    data: { input: item.input, output: response },
    settings: { model: "openai/gpt-6-luna", max_tokens: 2048 },
  });
});

选择评估器前，请阅读 langwatch docs evaluations/evaluators/list，并从 langwatch evaluator types --format json 获取类型 slug，切勿凭记忆填写。如果评估失败，并返回列出 slug 和 expected 列表的 validation_error，请根据该列表修正后重试一次。适用时复用项目中的评估器。评分函数是实验的一部分，而不是实验本身。

比较目标，选出胜者

评估器回答的是“这个输出是否通过？”，比较回答的是“这些输出中哪个更好？”。对于主观质量评估，让评审者并排比较并排列候选项，通常比单独给每个候选项打绝对分数更有参考价值。

在循环中为每个候选项注册一个目标，然后对该行进行一次比较。每个为该行记录了输出的目标都是一个候选项，因此候选项不会被重复命名；判定结果会记录到该行，因此结果页面无需额外日志记录即可显示。

Python

for index, row in experiment.loop(dataset.iterrows()):
    with experiment.target("gpt-6-luna"):
        experiment.log_response(call_gpt(row["input"]))

    with experiment.target("claude-sonnet-5"):
        experiment.log_response(call_claude(row["input"]))

    verdict = experiment.compare(index, input=row["input"])

在异步循环中，使用 experiment.acompare(...) 并等待其完成；它接受相同的选项。

TypeScript

await experiment.run(dataset, async ({ item, index }) => {
  await Promise.all([
    experiment.withTarget("gpt-6-luna", () => callGpt(item.input)),
    experiment.withTarget("claude-sonnet-5", () => callClaude(item.input)),
  ]);

  const verdict = await experiment.compare({ index, input: item.input });
});

传入包含已知正确答案的 golden，以此作为评判每个候选项的基准。省略该参数（默认行为），则根据候选项自身的表现进行评判。

读取 verdict.status，并区分以下五种结果：

• decided：评审者选出了胜者，名称记录在 verdict.winner 中。
• tie：评审者比较了候选项，认为没有哪个比其他候选项更好。
• inconclusive：未能确定胜者；在默认情况下，第二轮会以相反的候选项顺序再次评判，因此这表示两轮结果不一致。
• skipped：该行的输出少于两个，因此没有运行评审。
• error：评审失败，因此完全没有测量候选项的表现。

平局、无法得出结论和出错是三种不同的结果。将其中任何一种说成另一种，都会声称运行中并未实际进行的测量结果。

prompt 会原样替换评审提示词，并支持 {input}、{golden} 和 {candidates} 占位符。除非用户要求自定义提示词，否则请勿设置此项；不设置时，评审会使用与每行携带内容相匹配的提示词。其余评审选项请参阅 langwatch docs evaluations/experiments/sdk。

运行并验证

务必执行实验。未运行的实验是不完整的。

• Python 脚本：使用项目的 Python 环境运行。
• Notebook：执行所有单元格，例如使用 jupyter nbconvert --to notebook --execute。
• TypeScript：使用项目的包管理器运行，例如 pnpm exec tsx experiment.ts。

运行后，使用 CLI 验证结果：

langwatch experiment list --format json

如果 CLI 支持针对已安装版本的更具体读取或运行命令，请先使用 langwatch experiment --help 查找，再使用该命令。

顾问模式

交付初步结果后，切换到顾问模式，帮助用户最大限度地发挥价值。

阶段 1：先阅读。 生成任何内容之前，先从头到尾阅读代码库（每一条系统提示词、每个函数和工具定义），查看与 Agent 相关的 Git 历史记录（先运行 git log --oneline -30，再深入查看与提示词、Agent 和评估相关的提交，因为提交信息中的 WHY 比 WHAT 更重要），并阅读 README 和注释，了解领域背景。

阶段 2：快速见效。 根据你掌握的信息，尽最大努力生成内容。运行测试并迭代，但同一失败最多尝试两次，然后说明阻碍所在，不要反复运行。向用户展示可用的成果。

阶段 3：深入探索。 阶段 2 完成后，总结交付内容，然后提出 2–3 项基于代码库的具体改进建议：领域边缘情况、需要专家术语或真实数据的地方、集成点（API、数据库、文件上传），或 Git 历史中值得通过测试覆盖的回归模式。提供选项，轻松提问，不要提出开放式问题（“想为 X 还是 Y 添加场景？”，“我注意到 Z 是反复出现的问题。要添加回归测试吗？”，“你有可以用的真实客户查询吗？”）。尊重用户说的“够了”，并妥善结束对话。

在阶段 1 和 2 之前，不要请求许可。先交付价值。不要提出泛泛的问题，也不要给出太多建议。所有内容都必须反映实际领域。

常见错误

• 不要使用此技能配置生产监控或防护措施。
• 不要把批量运行称为在线评估。
• 不要使用占位数据集。
• 不要把无结论或出错的比较报告为平局。
• 如果可以查阅已安装文档，不要猜测 SDK API。
• 写完实验后不要就此停止。运行实验并检查实际结果。