agent-observability-experiment-bootstrap

LLM オブザーバビリティ実験の初期設定

再現可能な実験アーティファクトを1つ生成します。このアーティファクトは、バージョン管理されたデータセットに対してタスクを評価し、出力と評価指標を記録し、設定と来歴を保持します。また、可能な場合は結果へのリンクまたは識別子を出力します。

このスキルはアダプターに依存しません。各アダプターは 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. アダプターの参照資料を1つだけ読みます。
   • 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 SDK と Node SDK を混在させないでください。プライベート SDK モジュールを使用したり、存在しないシンボルを作り出したりしないでください。ローカルのソースとインストール済みパッケージが一致しない場合は、その相違を報告し、選択したバージョンに基づいて生成してください。

共通の実験モデル

すべてのアダプターで、以下の概念を表現する必要があります。

1. プロジェクト — 明示的なプロジェクト名、設定されたサービスメタデータ、または明確に説明された生成値のフォールバックを特定します。無関係なプロジェクトを暗黙に使用しないでください。
2. データセット — 入力、任意の期待出力、任意のメタデータ、タグを含むレコードです。指定されたリモートデータセットのバージョンを固定します。
3. タスク — レコードの入力を、テスト対象のアプリケーションに渡す決定論的なアダプターです。評価ロジックはタスクの外部に置きます。
4. 評価器 — 行単位または集計単位の、名前付きメトリクスです。契約の確認には決定論的なチェックを使用し、意味的な評価が必要な場合に限って判定器を使用します。
5. 実行状態 — タスクのエラー、評価器のエラー、完了状態、結果行、部分的な失敗をそれぞれ分けて保持します。
6. 来歴 — 目的、アダプター、スキル名／バージョン、プロジェクト、データセットの識別情報／バージョン、タスクのソース、評価器のラベル／ルーブリック、モデル／設定、Git リビジョン、生成日時を含めます。

expected_output は任意であり、明示的な検証なしに、本番環境で観測された出力から合成してはなりません。値の欠落と、意図的な空のオブジェクトを区別してください。選択した参照資料で指定されている場合、データセットのタグにはバックエンドで検証された key:value 形式を使用してください。

生成ワークフロー

1. 目的とプロジェクトを特定する

製品の境界をまたいで推測せずに、目的とプロジェクトを特定してください。プロジェクトが ml_app、サービス、データセット、リポジトリと自動的に同じものになるわけではありません。それぞれの値をどのように特定したかを記録してください。

2. データセットを解決する

次をサポートします。

• インラインレコード
• ローカルの JSON または CSV
• 名前付きのリモートデータセットと任意のバージョン
• 明示的に承認されたトレース／アノテーションのエクスポート

ローカルの JSON では、最上位が配列であることを必須とし、選択したアダプターのレコード形式を検証し、明らかな PII や認証情報のような値をサニタイズして、該当するレコードのインデックスを報告します。正規のレコード 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、偽または合格に集約されたタスク／評価器のエラーを確認します。

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 を変更しないでください。