agent-observability-online-experiment

在 LLM 应用上设置在线实验

在线实验会将实时流量分配给 LLM 应用的对照版本和处理版本。Datadog 功能标志会为每个 主体 分配一个变体，而 Agent Observability 评估分数（以及成本和令牌用量）则用于衡量结果。本技能会带你完成整个设置流程，从功能标志到启动实验。

Agent Observability 的在线实验可能需要为用户的组织启用此功能。如果任何步骤提示该功能不可用，请告知用户联系其 Datadog 代表，而不要重试。

何时使用此技能

• 用户想在真实流量上测试某项更改（提示词、模型、检索策略、工具集），而不是在固定数据集上测试。
• 用户有一个分支上的更改，想了解它在生产环境中是否更好、更省成本，或兼而有之。
• 用户想进行一项实验，其指标来自 Agent Observability 评估、令牌计数或成本。

不要将此技能用于基于数据集的离线实验（请使用 LLM Observability 实验工具）、分析已运行的实验（使用 agent-observability-experiment-analyzer 或 Datadog 实验工具），或推广现有离线实验。

基本原则

• 使用一个设置审批检查点。 在任何写入操作之前，先完成第 0 阶段的只读探索，给出合理建议，并在一次确认请求中完整呈现拟议设置。内容应包括功能标志、变体、指标定义或复用的指标 ID、期望的变化方向、环境、主体、流量分配、代码更改，以及你计划进行的每一项组织写入操作。用户批准该方案后，对于已明确列出的功能标志、草稿、链接、指标、启用或分配写入操作，不要再逐项询问。
• 在同一检查点明确说明生产风险。 如果方案会启用生产功能标志或替换生产环境中的流量分配，请说明此更改会立即生效。用户明确批准该生产方案后，就足够了；不要再重复相同信息进行第二次确认。只有在回读发现实际替换与已批准方案有重大差异或具有破坏性时，才再次询问。
• 启动是独立步骤，除非用户已明确要求。 只有用户明确要求启动实验时才启动。如果用户最初的请求包含启动要求，请将其纳入单次设置方案；否则，完成草稿后即可结束，直到用户提出要求前，不要询问是否启动。
• 每次只进行一步，并回读结果。 每次写入后，都要读回对象，并报告服务器实际存储的内容，而不是你发送的内容。
• 不要并行附加指标，也不要在编辑其他指标的同时附加指标。 附加操作会将实验的完整指标集发送给服务器，因此并发编辑可能会相互覆盖。
• 如实说明失败。 如果某个步骤遭到拒绝（权限问题、生产限制），请说明原因并提供手动替代方案。不要寻找变通方法。
• 不要猜测标识符。 环境 ID、功能标志 ID、指标 ID 和变体键都必须来自服务器。

阶段 0 — 发现、推荐并一次性确认

不要在调查过程中每次只询问一项输入。先完成所有可用的只读发现：

• 检查当前工具列表，并确认会话具备此工作流所需的 llmobs、experiments 和 feature-flags 能力：环境发现；标记查询、创建、启用和分配管理；实验查询、创建、关联和启动；以及实验指标查询、创建和附加。技能的工具集配置使用 OR 语义控制其可见性；这并不保证三个工具集都已启用。如果缺少能力，请报告所有缺失的能力组以及需要启用的工具集，然后在执行任何写入之前停止，不要反复重试单项操作。
• 检查应用及其部署配置。确认它会向 Agent Observability 报告，查明它提交评估的位置（如果有），找出处理组会改变的代码路径，并推断其 ml_app、DD_ENV 和稳定的主体标识符。
• 列出环境，查找是否已有适用于拟议变更的标记和实验，并在提议创建新对象前搜索现有实验指标。

然后制定完整方案。根据上下文进行推断，并在合理时采用以下默认值：

输入	说明
应用及其 ML 应用名称	应用向 Agent Observability 报告的 ml_app。
对照组和处理组	两者之间的差异。通常，对照组使用当前代码路径，处理组则使用待测试的变更。
假设	用一到两句话说明预期机制及其对质量、令牌数或成本的影响。
评分指标	推荐最相关的现有数值评估分数，并注明期望变化方向。请参阅阶段 4。
环境	根据部署配置和用户的实时流量目标进行推断。一个实验只能关联一个环境。
流量拆分	默认对照组和处理组各占 50%。
标记名称	默认使用简短、描述性且采用 kebab-case 的名称。
主体	定义一个主体的判定标准。请参阅阶段 2。

需要搜索指标名称时，在判定指标不存在之前，先尝试不同命名形式：空格、连字符、下划线和有意义的子字符串。检查重复定义，不要仅凭名称选择指标。只有在来源、列、筛选条件、聚合方式和期望变化方向均与方案匹配时，才优先选用已被活跃实验使用的定义。不要根据指标名称推断其适用的 ML 应用范围。如果用户要求使用的现有指标缺少 ML 应用筛选条件，或在其他方面与推荐定义不符，请在方案中说明这一点，并建议复用还是替换。

提出一条简洁的确认请求，其中包含：

• 应用和 ml_app；
• 对照组、处理组和假设；
• 拟议的标记键及布尔变体；
• 主体标识符，以及评估标记的代码位置；
• 目标环境和 50/50 或拟议的流量拆分；
• 主要评估指标、已保存的定义或拟议定义，以及期望变化方向；
• 令牌数和成本次要指标；
• 将复用现有对象还是创建新对象；
• 完整的写入清单，包括适用时的生产环境启用／流量分配；
• 是否包含启动操作（仅当用户已请求启动时）。

最后只问一个问题：确认这套完整方案，还是告诉我需要修改什么。 只有在存在无法通过代码、服务端状态或安全默认值解决的真正阻塞性歧义时，才提出后续问题。

阶段 1 — 创建功能标志

创建一个包含两个变体的布尔型标志：control = false，treatment = true。将 control 设为默认变体。

• 创建标志时，不要添加分配、定向规则或百分比发布。将标志关联到实验本身不会创建分配：关联后，请在阶段 5 创建或更新一个关联到实验的 FEATURE_GATE 分配。额外的规则会干扰分流。
• 先检查是否已存在具有该键的标志；如果用户表示要复用，请复用该标志。
• 如果组织中完全没有功能标志，服务可能会引导用户进入首次设置流程。用户已指定要创建的标志时，可以直接创建；只有在用户似乎是 Datadog Feature Flags 新用户时，才提及引导流程。
• 记录标志 ID 和两个变体的 ID。

列出环境即可查看可用环境（通常为 Production、Staging、Development）。注明哪些是生产环境：某些生产环境操作无法通过服务执行，必须在 Datadog UI 中完成。

阶段 2 — 接入应用程序

对于每个主体，应用程序必须完成三件事：评估功能标志、运行匹配的行为，并在同一主体标识符下报告分数和跨度。

选择主体标识符。 在整个被测交互过程中，该标识符必须保持稳定。

• 有已登录用户的应用程序：使用稳定的用户 ID。
• 没有用户，但有会话：使用会话 ID。
• 自主工作流：在运行开始时生成一个 UUID，并在整个运行过程中重复使用。

在三个地方使用相同的值：功能标志评估上下文的 targetingKey、评估分数上的 subject_identifier 标签（这是 Datadog 在线实验指南要求的关联键），以及每条追踪的根跨度上的 subject_identifier 标签，成本和令牌指标会读取该标签。如果这些值不一致，Datadog 就无法将标志曝光与结果关联起来，实验会显示缺失的指标数据。

评估标志。 按照应用程序所用语言对应的 Feature Flags SDK 操作。对于 Python，这意味着使用较新版本的 ddtrace 和 OpenFeature SDK，注册一次 Datadog 提供程序，并评估一个将 targeting_key 设为主体标识符的布尔标志。SDK 需要设置 Datadog API 密钥、站点和 DD_ENV。将评估默认设为 false（对照组），并捕获故障，使标志服务中断时回退到对照组，而不是导致应用程序崩溃。

无论应用程序使用哪种语言，功能标志管理指南都可能指向 React 集成资源。请将其视为通用工具指南，而不是添加 React 代码的指示。请使用应用程序实际语言对应的 SDK，并优先采用仓库中现有且可正常工作的提供程序／评估模式。

选择应用变体的位置。 如果某种行为被嵌入到会持久化的状态中（例如存储在对话对象中的系统提示词），则应在创建该状态时评估标志，而不是在每次调用时评估，这样主体就不会在交互过程中切换变体。在可行的情况下，在代码中从对照组派生出处理组，以避免两者出现偏差。

报告分数。 使用 Agent Observability SDK 提交分数评估，并将 subject_identifier 添加到其标签中。只有 score 指标类型为数值的评估才能用作实验指标；布尔、分类及其他类型均不可用。

为跨度和评估添加标签。 在应用程序自己的代码中，为 Agent Observability 跨度和评估分数添加 subject_identifier 标签（例如 subject_identifier:73b2efe1-03e3-40c1-ab6a-bd2a6cfbc865）。在数据摄取期间，Datadog 会将该标签转换为事件的 @usr.id 字段，而实验正是通过该字段与标志曝光进行关联。请设置标签，而不是 @usr.id：SDK 不会直接设置该字段，转换是在 Datadog 后端完成的。

成本和令牌指标会读取每条已完成根追踪的汇总数据，因此该标签必须添加到追踪的根跨度上：也就是最外层的工作流或 Agent 跨度。请通过 SDK 的跨度注释调用为该跨度添加标注。对于跨度范围的托管评估器，还要将相同标签添加到该评估器评分的每个跨度上，因为它会根据被评估跨度自身的标签推导主体。追踪范围的托管评估器可以将根跨度的主体传递给其结果。为被评估的子跨度添加标签不会造成成本或令牌重复计数，因为这些指标仍只统计根追踪。

代码必须部署后，实验才能收集任何数据。请明确告知用户：标志、分配和实验可以在部署前创建，但只有应用程序在关联环境中评估标志后才会开始记录数据；应用程序的 DD_ENV 必须与该环境匹配。

第 3 阶段 — 创建实验并关联标记

1. 创建一个名称清晰并包含假设的实验草稿。之后可以附加主要指标，因此在指标创建之前创建草稿也没问题。
2. 将第 1 阶段的标记关联到实验。
3. 读取实验信息。草稿在启动之前可能会报告设置不完整，这本身并不表示出错。如果存在具体阻碍，启动步骤会报告出来。
4. 确认草稿的主体类型，并验证其 Product Analytics 属性为 @usr.id，与第 2 阶段的 subject_identifier 标记生成的字段一致。启动实验需要主体类型，但不要接受服务端任意选择的默认值：映射到其他字段的主体类型无法参与这些 Agent Observability 结果。继续之前，请明确选择与 @usr.id 兼容的主体类型。如果可用功能无法检查或配置该映射，请引导用户前往 Datadog UI，并暂停操作，直至确认映射。

另一种方式是不先创建标记，而是通过单个操作创建标记及其与实验关联的分配（create-experiment-feature-flag 工具）。此方式要求实验和环境事先存在。上面的分步流程让每次写入都更小，也更容易读取确认，因此本技能采用此流程。

报告实验的名称和 ID。使用服务端返回的 ID，以及组织 Datadog 站点的应用主机名，构造其 Product Analytics 直达 URL： https://<app-host>/product-analytics/experiments/<experiment-id>。US1 使用 app.datadoghq.com；EU 使用 app.datadoghq.eu；us5.datadoghq.com 等区域站点直接使用对应主机名；datad0g.com 使用 dd.datad0g.com。完成设置说明后，在最终交接内容中包含此链接，无论实验仍处于草稿状态还是已经启动。

第 4 阶段 — 创建并附加指标

优先复用，再考虑创建

先列出已有的实验指标。如果某个指标已经衡量此 ML 应用的用户评分，就复用它。如果已有指标基于 Agent Observability 数据构建，请读取其已存储的定义并复制其中的列名，不要自行猜测。成本和令牌指标也采用同样的做法。

主要指标：评分评估

主要指标是第 0 阶段批准的评分。如果用户没有指定评分，请列出此 ML 应用已有的评估，并在单次设置方案中推荐最相关的数值评分。除非回读结果与已批准的定义相矛盾，否则不要在此处暂停并再次询问用户。

• 来源： Agent Observability 评估指标，筛选范围为此 ML 应用和评估标签。
• 聚合： 评分值的平均值。
• 期望变化： 代表改善的方向，取值为 METRIC_INCREASES 或 METRIC_DECREASES。此字段必填，错误的值会颠倒所有结果的解读，因此请在第 0 阶段的方案中明确填写。

示例定义（列为标准评估事件字段：标签、评分值和 ML 应用）：

data source:        DATADOG
source type/subtype: LLMOBS / LLMOBS_EVAL_METRICS
aggregation:        average of @score_value
source filter:      @ml_app = <ml_app> AND @label = <evaluation label>
desired change:     METRIC_INCREASES (for a score where higher is better)

次要指标：Token 和成本

添加两个次要指标，让用户了解这项变更的成本。两者都衡量已完成的 LLM Observability 根 Trace，并按每条 Trace 求平均值：

• 平均 Trace Token 数：@trace.total_tokens 的平均值。期望变化：METRIC_DECREASES。
• 平均 Trace 成本：@trace.estimated_total_cost 的平均值。期望变化：METRIC_DECREASES。

使用 Agent Observability Span 数据源（LLMOBS / LLMOBS_SPANS），操作选择 average，列类型选择 int。通过常规事件筛选器按 @ml_app = <ml_app> 筛选，避免同一主体使用的其他应用中的 Trace 进入结果。不要添加 Trace 完成状态或根 Span 状态筛选器：平台会自行应用这些资格规则，指标定义无法覆盖它们。不要对所有 Span 求和，否则会将子 Span 和未完成的 Trace 计入。如果组织已有 LLM Observability Span 指标，请从其已存储的定义中复制列名和类型，不要依赖此处提供的名称；但只有在其已存储的筛选条件已限定为此 @ml_app 时，才能复用该指标。Trace 汇总值应为整数。如果指标没有数据，请先检查列类型，因为已存储的类型必须与平台公开的类型一致。

附加指标

每次只附加一个，切勿并发附加：

1. 将评分指标附加为主要指标。
2. 将 Token 指标附加为次要指标。
3. 将成本指标附加为次要指标。

重新读取实验并确认主要指标已设置。某些实验读取结果会省略次要指标；在这种情况下，请使用成功附加指标的响应中完整的指标集合进行确认，并明确说明常规实验读取结果不会显示这些指标。

第 5 阶段 — 环境与流量分配

一个实验只能通过一个分配关联到一个环境。

1. 在用户指定的环境中启用功能标志。服务可能会拒绝在生产环境中启用标志，并引导用户前往 UI。如果发生这种情况，请向用户提供该标志的 UI 链接，并请他们在那里启用。更改分配（第 3 步）是单独的操作，在生产环境中仍可能可用。

2. 列出目标环境中该标志的完整分配集合，以及已关联到此实验的其他任何环境中的完整分配集合。设置分配会完全替换现有集合，因此在每个替换请求中，都要保留所有无关分配及其全部设置。

3. 添加或更新恰好一个关联到该实验的功能门分配，同时在完整替换列表中保留无关分配。其变体权重以百分比表示，合计必须正好为 100（例如，control 为 50，treatment 为 50）。在同一次调用中加入曝光计划，否则实验将无法启动（见下一段）。 曝光计划必须包含以下所有字段，否则启动步骤会报告实验尚未就绪。尽管通用分配架构说明功能门应省略计划，但这条建议适用于未关联实验的功能门。

   • 采用均匀间隔的发布策略，并设置该策略所需的 selection_interval_ms；
   • 将开始时间设为 none，使计划不会自行启动，并由实验自身的启动操作控制时间；
   • 仅设置一个发布步骤，exposure_ratio 为 1.0（取值范围为 0 到 1 的比例，而非 100），is_pause_record 为 false，grouped_step_index 为 0，使变体权重中的百分比适用于所有流量；
   • 在计划的 control_variant_key 中指定 control 变体（不设置此项也能保存分配，但启动步骤随后会报告分配权重无效）。

   此处不要使用分阶段逐步增加的流量发布。50/50 的比例已由权重表示。

4. 如果实验已关联到其他环境中的某个分配，请读取该环境的完整分配集合，并在创建新分配前，仅移除关联到此实验的分配，同时保留其他所有分配及其设置。除非已批准的配置明确要求移除环境中的所有分配，否则不要将环境替换为空列表。如果分配键已存在，请确认冲突分配的归属：仅当它属于已批准的配置时才复用；否则选择新的唯一键。如果这种恢复方式与已批准的方案存在实质差异，请再次征求确认。

5. 读回分配并确认环境、权重和实验关联。

生产环境中的分配更改会立即生效。如果环境要求审批功能标志更改，则更改可能会等待审批，而不是立即应用。已批准的第 0 阶段方案已包含环境和生产确认；除非现有分配集合与该方案所述的待替换集合存在实质差异，否则不要再次询问。

阶段 6 — 开始实验

只有在用户明确要求时才开始。开始前，立即独立验证以下事项，不要只依赖开始操作的就绪检查：

• 已在关联的环境中启用标记。
• 已设置并关联 50/50（或所选比例）的分配。
• 已关联主要指标。
• 应用程序变更已部署，或者用户明确接受在部署前开始计时。

如果已知关联的环境处于禁用状态，请勿调用开始操作。开始就绪检查可能会验证分配结构，但不会强制检查标记是否已启用或是否已部署，因此成功开始并不能证明流量能够流入。

然后开始实验（使用 start-experiment 工具）。该工具会运行自己的就绪检查，并返回它能够检测到的结构性阻碍以及相应操作。执行所有操作，然后重试一次。预计可能需要不止一轮：它只会报告当前能够检测到的阻碍，修复其中一个可能会暴露出下一个（例如，先发现缺少曝光计划，然后发现该计划中的对照变体无效）。修复分配会替换标记的整套分配，因此请先读取分配；只有当所需的替换内容不同于阶段 0 中批准的内容时，才再次询问。如果返回权限错误，请说明该账户没有开始实验的权限，停止操作，并提供 UI 中的预览并开始流程。不要循环重试。

实验开始后，读取实验信息并报告其状态。

阶段 7 — 流量开始后验证

应用程序部署并开始接收流量后：

• 运行实验诊断。诊断会检查曝光平衡、标记的零数据指标、不可靠指标以及样本比例失配。
• 如果某项指标没有数据，请按以下顺序检查：是否正在针对该主体评估标记（实验的代码位置查找会显示源代码中使用标记的位置）；评估是否有数值分数；subject_identifier 是否与 targetingKey 完全一致；根 Span 是否带有该标签；追踪是否完整；指标的列名和类型是否正确。
• 如果指标定义有误，请更新该指标，而不是创建重复指标。

数据充足后，如需读取结果，请使用 agent-observability-experiment-analyzer，或使用当前 MCP 服务中可用的 Datadog 实验工具。

常见问题检查清单

• 标记、评估和 Span 之间的主体标识符不匹配。
• 根 Span 缺少主体标签，因此成本和令牌指标无法与曝光关联。
• 主体类型映射到了 @usr.id 以外的属性。
• Span 作用域的托管评估缺少其评分所用 Span 上的主体标签。
• 成本或令牌指标被定义为所有 Span 的总和，或使用了追踪汇总以外的 Span 属性。
• 成本或令牌指标缺少 @ml_app 筛选条件。
• 在一个环境中启用了标记，但应用程序运行在另一个环境中。
• 实验关联到了错误环境的分配（只能关联一个分配）。
• 替换分配时丢弃了无关分配或其曝光计划。
• 分配权重总和不是 100。
• 分配集没有曝光计划，或者其计划没有 control_variant_key，这会阻止开始步骤。
• 评估结果是布尔值或类别值，而不是分数。
• 指标的 desired change 方向设置错误。
• 并行关联指标。
• 用户尚未提出要求就开始，或标记尚未在应用程序运行的环境中启用就开始。