ratel-langsmith-analyze

/ratel-langsmith-analyze — 実行データを読み取り、改善策を提案する

LangSmith MCP サーバーから集計データと外れ値となる実行を取得し（またはフォールバックとして langsmith SDK を使用し）、既知のエージェントの障害パターンのカタログと照合して、顧客が今週から実行できる調査結果レポートを作成します。出力は、Ratel 関連の機会（Ratel を統合または強化できる箇所）と、一般的なすぐに取り組める改善点（誰でも修正できるもの）の 2 つに分類します。

一般的な調査結果は埋め草ではありません。信頼を得るための手段です。自社製品だけを勧めるコンサルタントは、セールス担当者のように見えます。私たちはそうではありません。

LangSmith のデータモデルは プロジェクト → トレース → 実行ツリー です。トレースはルート実行とその子実行ツリーで構成されます。各実行の run_type は chain、llm、tool、retriever、parser、prompt、embedding のいずれかです。セッションや会話は、実行に設定された thread_id / session_id メタデータキーで管理されます。このモデルを念頭に置いてください。Langfuse における「トレース」は、ここでは ルート実行 に相当し、「オブザベーション」は 子実行 に相当します。

良い調査結果とは

次の条件を満たす調査結果は、良いものです。

1. 顧客が自分で確認できるように、少なくとも 1 つの 実行 ID または トレース ID、あるいは保存済みの フィルター URL / フィルター文字列を示している。
2. 問題点だけでなく、何をすべきかを示している。曖昧な調査結果（「エラー率が高い」）は、パートナーの時間を無駄にします。
3. 修正が重要な理由を示している。顧客の PM が読めるよう、1 文で説明している。
4. Ratel または 一般 のタグが付いている。両者を混在させると、価値が伝わりません。
5. Ratel 関連の調査結果の場合、解決に使える Ratel のバージョンを示している。概念的なシグナルとバージョンの対応関係は、共通の ratel-value-map.md（ベンダーに依存しない信頼できる情報源。現在のベースラインは v0.1.6 系列）から取得してください。

次のような調査結果は、良くありません。

• ダッシュボードにある内容を言い換えている（「p50 レイテンシーは 4.2s」）。LangSmith の Monitor タブにすでに表示されています。
• 「改善できる可能性があります」や「調査する価値があるかもしれません」のような限定表現を使っている。調査結果であるか、そうでないかのどちらかです。
• 分量を埋めるために作り上げている。

ワークフロー

ステップ 1 — MCP が利用可能か確認する（または SDK にフォールバックする）

LangSmith の読み取り用インターフェースに接続できることを確認します。MCP の選択肢が 2 つ、SDK のフォールバックが 1 つあります。

# Preferred: confirm LangSmith MCP tools are present.
# Via the Ratel gateway: search_capabilities(query="langsmith runs traces threads datasets")
# Or inspect Claude Code's MCP config for one of:
#   - the Remote MCP (OAuth):      https://api.smith.langchain.com/mcp
#     (EU region: https://eu.api.smith.langchain.com/mcp; self-hosted: <host>/api/mcp, LangSmith v0.15+)
#   - the standalone server:       langsmith-mcp-server (uvx / PyPI; LANGSMITH-API-KEY header)

LangSmith MCP サーバーに接続できない場合は、すぐに中止します。

LangSmith MCP サーバーが検出されませんでした。まず /ratel-langsmith-integrate を実行して、Remote MCP（https://api.smith.langchain.com/mcp、OAuth）またはスタンドアロンの langsmith-mcp-server を登録してから、このスキルを再実行してください。

SDK へのフォールバック（オフライン / MCP なし）。 MCP を登録できない場合でも、LANGSMITH_API_KEY とプロジェクト名を利用できるなら、langsmith Python SDK の Client.list_runs(...)、read_run(run_id, load_child_runs=True)、実行統計を使用して、Bash 経由で直接分析できます。どちらの方法でも使えるクエリの形式は、references/query-patterns.md に記載されています。SDK を使用した場合は、レポートのヘッダーにその旨を記載してください（データは同じで、アクセス方法だけが異なります）。

いずれかの方法を利用できない場合は、先に進まないでください。このスキルはライブデータなしでは役に立ちません。

ステップ 2 — 対象期間を設定する

ユーザーに確認するか、呼び出し時に指定された内容を使用します。

• 期間（デフォルト：過去 24 時間、またはルート実行 100 件のうち少ない方）。
• プロジェクト — LangSmith はプロジェクトごとに実行を分割するため、読み取る project_name を把握する必要があります。
• 任意のフィルター（thread_id / session_id、実行の name、run_type、tags、環境メタデータ）。
• 対象とする任意の Ratel 機能フラグのアーム（例：feature_flag / tool_pool のメタデータ値またはタグ）。A/B テストを実施する場合に便利です。

選択した対象範囲をチャットに表示し、顧客が分析対象を把握できるようにします。

ステップ 3 — 集計データを取得する

references/query-patterns.md のクエリを使い、次の順に取得します。

1. 対象期間のルート実行数、p50／p99 レイテンシ、合計トークン数／コスト、エラー率（is_root の実行を対象とする run-stats）。
2. レイテンシ、トークン数／コスト、子実行数ごとのルート実行の上位 10 件。
3. 呼び出し回数の多いツール上位 10 件（run_type = "tool"）、エラーが発生した実行の上位 10 件（error = true）。
4. 使用中のフィードバックキーがあれば、そのスコア分布。
5. feature_flag（または tool_pool）が設定されているタグ／メタデータキーでの内訳。

これで以降の分析の枠組みができます。また、「ルート実行の 80% で thread_id が設定されていない」といった、単一の集計で確認できる、些細ながら重要な知見も明らかになります。

ステップ 4 — 外れ値を詳しく調べる

次の実行について、実行ツリー全体を取得します。

• 最も遅いルート実行。
• 最も高コスト（トークン数が最多）のルート実行。
• 「エラー」リスト上位のルート実行。
• （フィードバックが存在する場合）スコアが最も低いスレッド。
• 対照として、通常のレイテンシ帯からランダムに選んだルート実行を 2 件。

子実行を読み込み（read_run(..., load_child_runs=True) または MCP の同等機能）、入力と出力を確認します。実行ツリーの形だけを見るのではなく、エージェントが実際に何をしたかを確認してください。最も価値のある知見は、トランスクリプトを読むことで得られます。

ステップ 5 — 共有の知見カタログと照合する

共有の finding-catalog.md を開きます（ベンダー中立で、ratel-observability-assessment が管理しています）。各パターンについて、顧客が出力したデータが検出条件に一致するかを確認し、カタログの一般的な用語を LangSmith の概念に対応付けます（unit-of-work → ルート実行、step → 子実行、tool call → tool 実行、model call → llm 実行、session → thread_id）。一致する場合は、そのパターンのテンプレートを使って知見を出力します。

カタログを機械的にすべて確認しないでください。システムに Ratel が存在しない場合は、Ratel のセクション全体をスキップします。フィードバックスコアがない場合は、スコア関連のパターンをスキップします。カタログはふるいであり、チェックリストではありません。

ステップ 6 — 知見を生成する

各知見は次のテンプレートに従います。

### F<N>. <one-line title>

- **Severity**: high | medium | low
- **Category**: ratel | generic
- **Evidence**: run ids / trace ids / filter string / filter URL / aggregate value
- **Why this matters**: <one sentence>
- **Recommended action**: <concrete next step the customer can take this week>
- **Solved by Ratel?**: <no | yes, v0.1.X — feature name> (only for ratel category)

重大度の基準：

• 高 — トラフィックの 10% を超える範囲に影響する、または Monitor タブ／カスタムダッシュボードを機能しなくするデータ品質の問題。
• 中 — 意味のある範囲に影響するが、根幹を支えるものではない。
• 低 — 確認されたが小規模で、一度記載する価値がある。

カテゴリ（ratel、generic）ごとに、重大度の高い順に知見をまとめます。レポートを実用的なものにするため、カテゴリごとの知見は最大 10 件にします。10 件を超える場合は「（残り N 件の知見は後続のバッチにまとめました）」と記載し、残りは付録に記録します。

Ratel カテゴリでは、共有の ratel-value-map.md にある、概念上のシグナルから Ratel のバージョンへの対応付けを使います。ここにバージョンに関する主張をハードコードしないでください。

ステップ 7 — レポートを作成する

<repo>/.ratel/langsmith-analysis-<YYYY-MM-DD>.md に出力します。レポートは実行ごとに 1 つずつ蓄積し、以前のレポートを上書きしないでください。このディレクトリは /ratel-langsmith-integrate が書き込むディレクトリと同じにします。

構成：

# LangSmith analysis — <date>

## Scope
- Project: <project_name>
- Window: <range>
- Access path: <Remote MCP | standalone MCP | langsmith SDK fallback>
- Filters: <list>
- Root runs analysed: <n>
- Findings: <n total>, <n ratel>, <n generic>

## Aggregates at a glance
<3-5 bullets with the headline numbers>

## Findings — Ratel-flavored
<F1, F2, ... in severity order>

## Findings — Generic
<G1, G2, ... in severity order>

## Honest skip (if applicable)
<see honest skip path below>

## Appendix — raw query results
<the aggregates from step 3, formatted as tables>

両方のカテゴリから重大度の高い順に上位 3 件の知見を選び、1 行ずつ要約してチャットに表示します。残りの内容が記載されたファイルパスをユーザーに伝えます。

正直にスキップする場合

データが実際に健全である場合（エラー率が1%未満で、レイテンシーの外れ値がなく、thread_id の欠落も、フィードバックの悪化も、ツールのずれもない場合）は、その旨を伝える簡潔なレポートを作成してください。

今週、対応すべき重要な所見はありません。 の期間に 件のルート実行を分析しました。全体的な健全性は通常の範囲内です。トラフィックが を超えて増加した場合、または新しいエージェントバージョンがデプロイされた場合に、再度分析する価値がありそうです。

これは失敗ではありません。これもまた重要な情報です。問題がないときにそう伝えるコンサルタントは、パートナーから信頼されます。所見を捏造しないでください。 ノイズの多いレポートを一度出すと、顧客はそれ以降のレポートをずっと無視するようになります。

同様に、結論を出すにはトラフィックが少なすぎる場合（期間内のルート実行が約20件未満の場合）も、その旨を伝えてください。

期間内のルート実行は 件のみです。顧客の次回のトラフィックを伴うリリース、または次回のテストキャンペーン後に再実行してください。参考として集計値を含めていますが、所見は示していません。

参考ファイル

• references/query-patterns.md — 検証済みの LangSmith MCP ツールのクエリ形式と、langsmith SDK の list_runs フィルターパターン（集計、詳細調査、サンプル）
• finding-catalog.md — 検出パターン、推奨される修正、Ratel との対応付けをまとめた、ベンダーに依存しない共有カタログ（ratel-observability-assessment が管理）
• ratel-value-map.md — 「Ratel がいつ何を提供するか」を示す、ベンダーに依存しない共有の信頼できる情報源（概念上のシグナル → バージョン）。Ratel に関連する所見にタグを付ける際に参照してください。

全体の流れにおける位置付け

このスキルは、トレーシングが稼働した後に /ratel-langsmith-integrate から案内されるフォローアップです。前段の流れは /ratel-assessment → /ratel-observability-assessment（ベンダーの検出と中立的な提案）→ /ratel-langsmith-integrate（具体的な接続設定とダッシュボード）→ このスキル（稼働中のデータを読み取り、修正を提案）です。