概要

Datadog は、Agent Observability 分析を開発ワークフローに直接取り込む一連の Claude Code スキルを提供しています。ダッシュボードを手動で操作する代わりに、Claude Code セッションからこれらのスキルを呼び出して、ライブ本番環境データに対し、セッションの分類、障害の診断、実験の比較、Python 実験コードの生成、および評価器のブートストラップを実行できます。

これらのスキルは、構造化された実用的な出力 (修正前後の提案を含む RCA レポート、生成された評価器コード、実験の比較など) を生成し、それをコーディングエージェントに直接渡してアプリケーションに修正を適用できます。Claude Code がコードベースにアクセスできる場合、関連するシステムプロンプト、ツール定義、またはルーティングロジックを検索し、セッションを離れることなく特定の差分を提案できます。

セットアップ

前提条件

• Claude Code がインストール済みおよび認証済み
• Agent Observability でインスツルメント済み でトレースを生成している LLM アプリケーションが少なくとも 1 つ必要
• データバックエンド: Datadog MCP サーバー または pup CLI のいずれか

スキルをインストールする

スキルは agent-skills リポジトリで公開されています。次のコマンドを使ってインストールしてください。

npx skills add datadog-labs/agent-skills/agent-observability --full-depth -y

インストール後、すべての Claude Code セッションでスキルが利用可能になります。

Datadog MCP サーバー

Datadog MCP サーバーオプションを使用するには、Agent Observability MCP サーバーを Claude Code セッションに接続してください。

claude mcp add --scope user --transport http datadog-llmo-mcp \
  '?toolsets=llmobs,core'

すべてのスキルは、起動時に MCP サーバーを自動的に検出し、その後も継続して使用します。

オプション B: pup CLI

MCP サーバーを使用したくない場合は、Datadog の内部 CLI である pup を介してスキルを実行することもできます。pup をインストールして認証してください。

pup auth login

各スキルは起動時に MCP サーバーが利用可能かどうかを検出し、利用できない場合は pup を確認して自動的に pup モードに切り替えます。スキルの呼び出し時に --backend pup を渡すことで、明示的に pup モードを強制することもできます。

pup モードでは、すべての Datadog API 呼び出しは MCP ツールではなく pup llm-obs サブコマンドを通じて行われます。出力とワークフローは同一です。

スキル

セッションとトレースの分類

/agent-observability-session-classify は、特定のインタラクションにおいてユーザーの意図が満たされたかどうかを評価します。提供するものに応じて、3 つのモードで動作します。

このスキルは最大 3 つのシグナルソースから情報を取得し、アクセス可能なデータが多いほど精度が向上します。

• Agent Observability トレース — 完全なスパンツリー、会話内容、ツール呼び出しの結果、および評価ジャッジの判定。常に使用可能です。
• RUM 行動シグナル — ページビュー、カスタムアクション、滞在時間、およびトレースの内容を裏付けたり矛盾したりする明示的なフィードバックイベント。RUM がアプリに実装されている場合に使用可能です。
• Audit Trail — サーバーで確認された書き込みイベント (ダッシュボードの作成、モニターの変更、ノートブックの削除など)。アシスタントの操作が実際に反映されたかどうかを証明します。セッションにアセットの作成や編集が含まれる場合に最も信頼できるシグナルとなります。

このスキルは、デフォルトで 1 文の理由を添えたコンパクトな yes / partial / no 判定を返します。完全なマークダウンレポートを取得するには、verbose: true を追加してください。

例:

/agent-observability-session-classify session_id=abc-123
/agent-observability-session-classify trace_id=def-456
/agent-observability-session-classify ml_app=my-chatbot --timeframe now-7d

根本原因分析による障害診断

/agent-observability-trace-rca は、失敗したトレースのスパンツリーをたどり、LLM アプリケーションが不適切な結果を出力している原因を特定します。次の利用可能なシグナルに基づいて、最適な分析モードを選択します。LLM ジャッジによる評価判定 (最も強力なシグナル)、ランタイムエラー、またはレイテンシの異常値やエージェントループの決定などの構造的異常。

このスキルは、失敗したスパンをサンプリングして障害分類にグループ化し、根本原因のカテゴリ、裏付けとなる証拠、具体的な修正案を含む構造化された RCA レポートを作成します。各修正には、トレースからの実際のテキストやコード (システムプロンプトの抜粋、ツール引数の形式、ルーティングロジックなど) が含まれ、BEFORE / AFTER で変更箇所が正確に示されます。

Claude Code がコードベースにアクセスできる場合、このスキルは関連するソースファイルを検索し、すぐに適用可能な差分を提案します。システムプロンプトの不備、ツールの誤用、またはルーティングエラーが発生した場合、セッションを離れることなく、診断からプルリクエストの作成までを行うことができます。

例:

/agent-observability-trace-rca ml_app=my-chatbot
/agent-observability-trace-rca ml_app=my-chatbot eval_name=faithfulness --timeframe now-24h

実験の分析と比較

/agent-observability-experiment-analyzer は実験結果を取得し、候補とベースラインの間で何が変更されたかを明らかにします。単一の実験 (探索分析) またはペア (比較分析) に対して機能します。

このスキルは、どのメトリクスが改善または悪化したか、どのイベントカテゴリが変化したか、そして候補がどこで期待を下回ったかを強調表示するため、自信を持って昇格の判断を下すことができます。

例

/agent-observability-experiment-analyzer experiment_id=exp-123
/agent-observability-experiment-analyzer experiment_id=exp-456 baseline_id=exp-123

Python SDK を使用して実験コードを生成する

/agent-observability-experiment-py-bootstrapは、ddtrace.llmobs SDK を使用して標準の リファレンスノートブック と一致する、自己完結型の .py スクリプトまたは Jupyter .ipynb ノートブックを出力します。

データセットには、ローカルの DatasetRecordRaw[] JSON (ファイルにインライン化)、CSV (LLMObs.create_dataset_from_csv を介して実行時に読み込み)、名前による既存の Datadog データセット (LLMObs.pull_dataset)、またはデフォルトの小さなインライン 3 レコードサンプルを使用できます。

**以下のフラグはすべて任意です。**引数なしで /agent-observability-experiment-py-bootstrap を呼び出すと、必要な情報が求められ、デフォルトの 3 レコードのサンプルに対して実行可能なファイルが生成されます。

例

/agent-observability-experiment-py-bootstrap --purpose "validate output accuracy"
/agent-observability-experiment-py-bootstrap --purpose "test tool selection on ambiguous queries" --dataset ./data/qa.json
/agent-observability-experiment-py-bootstrap --dataset-name qa_v3 --project-name customer-qa
/agent-observability-experiment-py-bootstrap --task-source mymodule.handlers:respond --evaluator-style remote
/agent-observability-experiment-py-bootstrap --placeholder-task --format ipynb

トレースデータから評価器をブートストラップする

/agent-observability-eval-bootstrap は、ml_app (またはコンテキスト内にすでにある RCA レポート) からの本番環境トレースを分析し、観測された障害モードを捕捉する評価器のスイートを提案します。4 つのアーティファクトのいずれかを出力します。

最初の 3 つのモードは同じ評価器プロポーザルワークフロー (ワークフロー) を共有しており、スイートの具体化方法のみが異なります。4 番目のモード (--emit-dataset) は独立しており、ml_app (@status:ok にフィルタリング済み) のルートスパンをサンプリングし、レコードごとに input_data と expected_output を抽出し、文字列値に対して PII スクラブを実行し、データセットとして Datadog に公開して実験を実行できる JSON ファイルを書き出します。レコードごとの tags は自動正規化されるため (生の文字列は tag:<value> としてラップされます)、Dataset.append() がレコードを拒否することはありません。expected_output フィールドは本番環境の動作ベースラインとして文書化されており、グラウンドトゥルースではありません。ラベル付きゴールドセットに昇格する前の回帰スタイルの実験 (リファクタリングによって観測される出力が変化するかどうか)に役立ちます。

例

/agent-observability-eval-bootstrap ml_app=my-chatbot
/agent-observability-eval-bootstrap ml_app=my-chatbot --publish
/agent-observability-eval-bootstrap ml_app=my-chatbot --data-only
/agent-observability-eval-bootstrap ml_app=my-chatbot --emit-dataset ./datasets/my_chatbot_seed.json --trace-limit 25

エンドツーエンドのパイプラインを実行する

/agent-observability-eval-pipeline は、agent-observability サブスキルを単一の監視されたナレーション付きワークフローに連結し、本番環境トレースから、評価器、データセット、実験、および分析へと進むプロセスを実現します。各フェーズには同じエンベロープがあります。生成されるエンティティに名前を付けるバナー、その目的を説明する教育ブロック、アクション (サブスキルの呼び出しまたは小さな実行可能ステップ)、および確認を待つチェックポイントです。既存の評価器や実験がなく、決定論的なウォークスルーを希望する場合の推奨される開始点です。

Phase 1: Classify ml_app traces      → agent-observability-session-classify (ml_app mode)
Phase 2: Root cause analysis         → agent-observability-trace-rca
Phase 3: Bootstrap evaluators        → agent-observability-eval-bootstrap
Phase 4: Create + publish dataset    → agent-observability-eval-bootstrap --emit-dataset + LLMObs.create_dataset(records=...)
Phase 5: Generate + run experiment   → agent-observability-experiment-py-bootstrap + python <generated_file>
                                       (with an in-phase review beat between codegen and run)
Phase 6: Analyze experiment          → agent-observability-experiment-analyzer

各フェーズには標準的な短い名前があり、--start-at および --stop-after で受け入れられる値と同じです。単一のフェーズを明確に参照する必要がある場合は、常にこれらの名前を使用してください (例: スクリプト内、チームメイトとのチャット、サポートチケットなど)。

フェーズ 4 と 5 のみがマシン上でコードを実行します。それ以外は読み取り専用であるか、生成されたファイルを --output-dir に書き込むだけです。従来の 3 フェーズの評価パイプラインの動作 (分類 → RCA → 評価器のブートストラップのみ) は、--stop-after eval-bootstrap を渡すことで維持されます。フェーズ 5 では、コード生成と実行の間に一時停止するため、プロバイダーのトークンが消費される前に生成された実験ファイルを確認できます。run と入力すると実行、edit と入力すると一時停止して調整、または stop と入力すると正常に終了できます。

**どのフェーズからでも開始および終了できます。**パイプラインは、各チェックポイントがレンダリングされる前に、各フェーズの主要な出力 (分類サマリー、RCA レポート、評価スイート、データセット、公開されたデータセット名、実験ファイル、実験実行、分析レポート) を <output-dir>/state/0N-<name>.{md, json} に保存します。これは以下を意味します。

• stop 任意のチェックポイントで (または --stop-after <phase> を最初から) 実行を正常に終了し、再開可能な成果物をディスクに残します。
• **--start-at <phase>**以前のすべてのフェーズの状態ファイルを読み込み (または指定した場合はオーバーライドフラグを受け入れ)、指定されたフェーズに直接スキップします。数時間後や数日後に再開することも、以前の処理を再実行することなく「この実験を再分析する」に直接ジャンプすることも可能です。

各フェーズでのチェックポイントの語彙: continue は進む、stop は正常に終了する、redo は現在のフェーズを再実行する (オプションの調整メモを付加)、back は 1 フェーズ戻る。その他の入力は調整として扱われます。

**<ml_app> のみが必要です。**以下の各フラグはオプションです。スキルはそれぞれに対して適切なデフォルトを選択します。最小限の呼び出しは /agent-observability-eval-pipeline <ml_app> です。テーブルの残りの部分は、デフォルトを上書きしたり、フローの途中で再開したり、特定の出力場所を指定したりする場合に使用します。

例

# Full six-phase walkthrough for a brand new ml_app
/agent-observability-eval-pipeline my-chatbot --project-name my-chatbot

# Organize the dataset and experiment under a specific Datadog project
# (the project is created lazily — no need to pre-create it in the UI)
/agent-observability-eval-pipeline my-chatbot --project-name customer-qa-eval

# Classic three-phase eval-pipeline behavior — preserves backward compatibility
/agent-observability-eval-pipeline my-chatbot --stop-after eval-bootstrap

# Resume from where a previous run stopped
/agent-observability-eval-pipeline my-chatbot --start-at experiment

# Re-analyze a previous experiment run without re-running it
/agent-observability-eval-pipeline my-chatbot --start-at analyze --experiment-id <UUID>

# Run a single phase in isolation
/agent-observability-eval-pipeline my-chatbot --start-at dataset --stop-after dataset

プロジェクト名 — --project-name が省略された場合、スキルはコードベースから自動的に導出します (順序: pyproject.toml → setup.cfg → setup.py → package.json → cwd ベース名)。省略された場合は experiment-sdk-default が使用されます。解決された名前は、フェーズが実行される前に Precheck の出力に表示されるため、再呼び出しすることなく確認または上書きできます。Datadog プロジェクト自体は、フェーズ 4 でデータセットが公開される際に LLMObs.enable(project_name=...) によって遅延作成されます。UI で事前に作成しておく必要はありません。

一般的なワークフロー

LLM アプリケーションの評価が初めての場合は、以下のフローが推奨されます。

1. パイプラインを実行して、本番環境のトレースから、評価器、シードデータセット、実験、分析までを一通り実行します。

   /agent-observability-eval-pipeline <ml_app> --project-name <project>
   

   従来の評価器のみの出力 (データセットや実験なし) で停止するには、--stop-after eval-bootstrap を渡します。前回の実行を再開するには、--start-at <phase> を渡します。パイプラインは <output-dir>/state/ から以前の状態を再読み込みし、そこから継続します。

2. **修正を適用します。**フェーズ 2 で作成された RCA レポートには、トレースエビデンスに基づいた具体的な修正前後の提案が含まれています。レポートをコーディングエージェントに渡すか (または直接実行する)、コードベース内のシステムプロンプト、ツール定義、またはルーティングロジックを修正してください。

3. オフライン実験を実行します。生成された評価器をラベル付きデータセットに対して使用して、本番環境で有効にする前にその品質を検証してください。評価開発者ガイド を参照してください。

4. オンライン評価器を公開します。評価器が検証されたら実行します。/agent-observability-eval-bootstrap を --publish で実行すると、Datadog 内にオンライン LLM ジャッジ評価器が作成され、本番環境のトレースに対してリアルタイムで自動的に実行されます。コードの変更は不要です。

   /agent-observability-eval-bootstrap <ml_app> --publish
   

5. **監視および反復します。**アプリの進化に合わせて /agent-observability-trace-rca および /agent-observability-eval-bootstrap を再実行し、新たな障害モードを検出し、評価器スイートを最新の状態に保ってください。

役立つドキュメント、リンク、記事:

Agent Observability 評価ドキュメント LLM 実験ドキュメント 評価開発者ガイド: カスタム評価器の構築ガイド Bits Evals で AI エージェントの品質を向上させるブログ datadog-labs/agent-skillsGITHUB