agent-observability-experiment-bootstrap

LLM 可观测性实验引导

生成一个可复现的实验产物。该产物用于评估某个任务在某个带版本的数据集上的表现，记录输出和评估器指标，包含配置和来源信息，并尽可能打印结果链接或标识符。

此技能与适配器无关。每个适配器在 references/ 下都有自己的语言专属目录；仅加载所选适配器的契约。即使某个适配器当前的支持参考资料较少，这些目录的结构也保持对称。

调用方式与兼容性

已安装目录和旧版调用方式仍然有效：

/agent-observability-experiment-bootstrap [--purpose TEXT] [--format py|ipynb|mjs]
  [--dataset PATH | --dataset-name NAME] [--dataset-version N]
  [--project-name NAME] [--evaluator-style function|class|remote]
  [--jobs N] [--output PATH] [--task-source module:function]
  [--placeholder-task] [--app-root PATH] [--env-file PATH]

通用选项：

--adapter python|node             # default: python
--format py|ipynb|mjs             # Python: py/ipynb; Node: mjs
--site SITE                      # otherwise DD_SITE or datadoghq.com

不要针对可选默认值发起提问。从 --purpose、请求内容或一个有针对性的问题中确定一个非空的用途。将用途作为推理上下文，而不是固定分类体系。

强制上下文加载

按以下顺序加载上下文：

1. 解析适配器。
2. 恰好读取一个适配器参考资料：
   • Python SDK → references/python/python.md
   • Node SDK → references/node/nodejs.md
3. 对于 Python 任务生成，仅读取 references/python/providers/ 下所选的提供方参考资料。
4. 对于 Python 任务生成，仅读取 references/python/evaluator-styles/ 下所选的评估器参考资料。

不要为了“完整性”加载所有提供方、评估器、Python 和 Node 参考资料。所选参考资料是语法和 API 行为的准确信息来源。

适配器选择

如果应用或所请求的产物使用 Python，或者未指定适配器，则使用 Python。如果应用使用 JavaScript/TypeScript，且本地 dd-trace 包提供 tracer.llmobs.experiments，则使用 Node。

生成的产物中绝不能混用 Python 和 Node SDK。不要使用私有 SDK 模块，也不要臆造缺失的符号。如果本地源码与已安装的软件包不一致，请报告差异，并针对所选版本生成。

通用实验模型

每个适配器都必须体现以下概念：

1. 项目 — 解析显式项目名称、已配置的服务元数据，或有清晰文档说明的生成回退值。绝不能默默使用无关项目。
2. 数据集 — 包含输入、可选预期输出、可选元数据和标签的记录。如果指定了远程数据集版本，则固定使用该版本。
3. 任务 — 将记录输入传递给被测应用的确定性适配层。将评估逻辑置于任务之外。
4. 评估器 — 命名的行级或汇总级指标。对契约使用确定性检查，仅在需要语义评估时使用评审模型。
5. 运行状态 — 分别保留任务错误、评估器错误、完成状态、结果行和部分失败。
6. 来源信息 — 包含用途、适配器、技能名称/版本、项目、数据集标识/版本、任务来源、评估器标签/评分标准、模型/配置、Git 修订版本和生成时间戳。

expected_output 是可选项；未经明确验证，不得根据观察到的生产输出合成该值。区分缺失值与有意设置的空对象。如果所选参考资料有要求，数据集标签必须采用后端验证过的 key:value 格式。

生成工作流

1. 确定用途和项目

在不跨产品边界臆测的前提下，推导用途和项目。项目不一定等同于 ml_app、服务、数据集或仓库名称。记录每个值的确定方式。

2. 解析数据集

支持：

• 内联记录；
• 本地 JSON 或 CSV；
• 命名的远程数据集及可选版本；以及
• 经明确批准的追踪记录／注释导出。

对于本地 JSON，要求顶层为数组，验证所选适配器的记录形状，清理明显的个人身份信息和类似凭证的值，并报告受影响的记录索引。不要编造规范 ID 或远程记录 ID。

对于 CSV，保留运行时路径并说明依赖项。使用 references/python/python.md 中的 Python CSV 列契约；Node 生成内容不得假装存在仅适用于 Python 的 CSV 帮助程序。

3. 解析任务

如果提供了 --task-source，则使用它。否则，使用所选语言的有限范围应用发现规则：

• Python：检查已解析的应用根目录，并按优先级排列实际可调用的候选项。
• Node：优先使用显式导入／模块函数；如果没有，则生成清楚标记的占位符。

绝不要声称虚构的导入已接通。保留有关网络、数据库、文件系统、环境或工具调用的副作用警告。

4. 选择评估器

根据用途和可用信号选择 2 或 3 个评估器。标签应保持唯一且稳定。

• 准确性：精确／近似匹配，并在需要时使用更丰富的规则或判定器。
• 工具使用：检查结构化工具调用；如果任务未暴露这些调用，请说明其限制。
• 结构化输出：解析并验证架构。
• 检索：仅在有检索上下文时评估依据充分性。
• 回归：优先采用确定性检查和明确阈值。
• 探索：加入诊断或分类指标，而非仅使用通过／不通过评分。

评估器失败不得变成通过值。汇总评估器必须与行级评估器保持区分。

5. 生成产物

使用所选适配器参考中的准确生成代码。包括：

• 用途和项目解析信息；
• 数据集来源和版本；
• 真实任务来源，或醒目的占位符警告；
• 评估器标签和评分标准；
• 配置和来源信息；
• 不含明文机密的凭证说明；以及
• 结果 URL／ID 占位符和后续步骤。

使用 Python 适配器时，保留历史 Python 部分的顺序以及评估器／提供程序参考行为。

6. 本地验证

呈现产物前：

• Python .py：python -m py_compile <path>。
• Python .ipynb：解析 JSON，并要求包含代码／Markdown 单元格。
• Node .mjs：node --check <path>。

对于每个适配器，检查私有导入、明文凭证、格式错误的标签、缺失的来源信息、数据集版本不匹配、伪造的 ID，以及被折叠为 false 或 pass 的任务／评估器错误。

7. 报告完成情况

使用以下简洁结构：

Generated LLM Observability experiment: <adapter>/<format>
Path: <path>
Purpose: "<purpose>"
Project: <project>
Dataset: <local path | name>, version=<version or latest>
Task: <wired source | placeholder>
Evaluators: <labels>
Provenance: generated_by=claude-code, adapter=<adapter>, skill=agent-observability-experiment-bootstrap
Validation: <commands and pass/fail>
Result link: <URL or pending until run>

Next steps:
1. Verify the task source and evaluator semantics.
2. Set the credentials required by the selected SDK.
3. Install the selected SDK and run the generated artifact.
4. Review per-row errors before treating metrics as a successful run.

安全与不确定性

• 除非收到明确要求，否则不要修改应用源代码。
• 不要将凭证写入生成的文件或产物。
• 未经用户明确批准，不要发布提示词、输出、追踪记录、数据集或评估。
• 未经标注和验证，不要将生产数据用作真实值。
• 除非所选 SDK 明确支持自动重试，否则不要自动重试非幂等写入。
• 部分发布时，保留 ID 和失败行，并提供协调处理途径。

参考资料维护

每份适配器参考都必须标明用于验证的公开来源链接和分支。SDK 版本变更时，重新检查参考资料。Python 参考使用公开的 dd-trace-py main 分支；Node 参考使用公开的 dd-trace-js master 分支。

在此保留共享工作流指南，并将语言特定语法放在参考资料中。如果某项细节仅适用于某个 SDK，请勿在此文件中重复说明。

现有参考资料

• references/python/ — Python ddtrace.llmobs API、提供商、评估器风格、环境模板和旧版兼容性。
• references/node/ — Node tracer.llmobs.experiments API 及未来的 Node 专属参考资料。

更新此技能时，请勿修改 dd-trace-py 或 dd-trace-js。