ratel-langsmith-integrate

/ratel-langsmith-integrate — エージェント向けの LangSmith 計測とダッシュボードを設定する

Ratel チームが行う方法で、お客様のコードベースに LangSmith を組み込み、その価値を証明するダッシュボードの仕様を策定します。1 つのスキルに 2 つの要素があります。計測の設定（トレースをどこに追加するか、どう命名するか、どう設定するか）と、ダッシュボード構築仕様（Monitor とカスタムダッシュボードで作成するチャートと、具体的な設定）です。成果物は計画です。エージェントのコードは編集せず、LangSmith API も呼び出しません。お客様が LangSmith の UI を操作してダッシュボードを作成することが意図されています。

これは、可観測性の流れにおける LangSmith 分岐です。汎用の /ratel-observability-assessment が、ベンダーに依存せず、何を記録するか、どのダッシュボードが重要かを判断し、ベンダーを検出します。ベンダーが LangSmith の場合、ここに処理を引き継ぎ、計画を具体的な LangSmith のプリミティブに落とし込みます。トレースが流れ始めた後の下流のフォローアップは /ratel-langsmith-analyze で行い、この計画によって生成されたライブデータを読み取ります。

理念：コールグラフではなく、メンタルモデルをトレースする

よくある失敗パターンは、「すべての関数を run でラップする」ことです。そうすると、コードのコールグラフと一致する run ツリーができますが、エージェントが何をしようとしていたかは何もわかりません。LangSmith のトレースは、1 ターンの概念的な構造に沿った構成にすると、最も役立ちます。

• Trace（ルート run） = 外部から見て意味のある 1 単位の作業（1 回のチャットターン、1 件のジョブ、1 件の webhook）。1 つのリクエストに複数のエージェントターンが含まれる場合は「HTTP リクエスト 1 件」ではありません。また、1 ターンに複数のモデル呼び出しが含まれる場合は「モデル呼び出し 1 回」でもありません。
• Child run = その単位の中でエージェントが実行した 1 つのステップ。サブエージェントの呼び出し（chain run）、ツール呼び出し（tool run）、モデル呼び出し（llm run）、検索ステップ（retriever run）などです。ソースファイルの配置ではなく、委譲の構造を反映するようにネストします。
• Thread = スレッドのメタデータキー（session_id、thread_id、conversation_id）を共有する関連トレースの集合です。通常は、ユーザーとの会話、エージェントの run-id、またはジョブの相関 ID です。

詳しい根拠は、../ratel-observability-assessment/references/instrumentation-philosophy.md にまとめられています。用語を LangSmith 固有の形に落とし込んだ内容、つまり汎用概念をどの run タイプやメタデータキーに対応させるかは、references/langsmith-mapping.md に記載されています。

ダッシュボードを 2 つのグループに分ける理由

このスキルでは、パートナー企業であるスタートアップが同じデータから 2 種類のストーリーを求めるため、常に 2 つのグループのダッシュボードを構築します。

1. 「Ratel が数値を改善している」（Ratel の価値グループ）— トークン消費の削減、検索品質の向上、「ツールが見つからない」エラーの減少、セッションあたりのコスト低下などです。これらは、取り組みの価値を裏付けます。Ratel が導入済み、または導入予定の場合にのみ含めます。
2. 「エージェントは正常に動作している」（エージェント健全性グループ）— レイテンシのパーセンタイル、ツールごとのエラー率、放棄されたセッションの割合、フィードバックスコアの分布などです。Ratel の導入状況に関係なく役立ちます。お客様自身のエンジニアが自分たちのバグを見つけられるため、信頼の構築につながります。

Ratel 専用のダッシュボードだけでは営業資料のように感じられ、エージェント健全性専用のダッシュボードだけでは、私たちがここにいる理由を忘れたように感じられます。Ratel が関わる場合は、両方を含めてください。LangSmith の組み込みの Monitor タブは、プロジェクトごとにエージェント健全性のストーリーの大部分をすでにカバーしています。無料で得られるものを作り直す必要はありません（ステップ 5 を参照）。

ワークフロー

ステップ 0 — 上流の可観測性評価を読む（推奨入力）

<repo>/.ratel/ratel-observability-assessment.md を探してください。これは /ratel-observability-assessment の成果物です。存在する場合は、優先入力として扱います。検出されたスタック、トポロジー、ベンダーに依存しないインストルメンテーション戦略、推奨ダッシュボードの一覧を読みます。検出されたベンダーが LangSmith であることを確認してください。Langfuse（または別のベンダー）と記載されている場合は、処理を中断し、これは LangSmith スキルであり、一致する *-integrate スキルが必要であることをユーザーに伝えてください。

ファイルが存在する場合は、ステップ 1〜2 の詳細な検出を省略してレンダリングに進めます。スタックとトポロジーをそのまま使用し、ステップ 3 に進んでください。

ファイルが存在しない場合でも、処理をそこで止めないでください。ステップ 1〜2 で独自にスタックとベンダーを簡単に検出し、ダッシュボードの構築には用語の統一が必要なように、拒否するのではなく、いくつか質問してください。

1. 1 回のチャットのやり取り／1 つのジョブに対する正規のルート実行名は何ですか？
2. 使用中（または使用予定）の env、stack、agent_version のタグ値は何ですか？
3. Ratel は何らかの形（ゲートウェイ、SDK、または導入予定）でインストルメントされていますか？

回答を得てから進めてください。推測した用語に基づくチャートは、見た目は正しくても、グループ化が間違っていることがあります。

ステップ 1 — スタックを検出する

（上流の評価ですでにスタックが特定されている場合は省略します。）マニフェストファイルを読み、言語とフレームワークを特定します。スタック固有のパターンについては、該当するリファレンスを参照してください。

# TypeScript / Node detection
test -f package.json && cat package.json | jq -r '.dependencies // {}, .devDependencies // {} | keys[]' | sort -u

# Python detection
test -f pyproject.toml && cat pyproject.toml | grep -A 200 '^\[' || true
test -f requirements.txt && cat requirements.txt
test -f uv.lock && head -50 uv.lock

依存関係を次のスタックプロファイルのいずれかに対応付けます。

マニフェスト内のシグナル	スタック	リファレンス
ai、@ai-sdk/*	Vercel AI SDK	references/stack-vercel-ai-sdk.md
@mastra/core、または openai／@anthropic-ai/sdk を直接呼び出す手書きのループ	TypeScript 汎用	references/stack-typescript-generic.md
langsmith + openai／anthropic／langchain／llama_index	Python 汎用	references/stack-python-generic.md
langgraph、crewai、agno、autogen	Python エージェント型	references/stack-python-agentic.md

シグナルが重複する場合（たとえば、LangGraph のスーパーバイザーと、その内部での生の OpenAI 呼び出しの両方がある場合）は、エージェント型のリファレンスを主に選び、計画に混合スタックに関する注記を加えてください。

エージェント関連の要素をまったく特定できない場合（LLM クライアントのインポート、エージェントフレームワーク、モデル呼び出しがない場合）は、正直にスキップする方法を使用してください。

現在の識別子（SDK 名、wrapAISDK の利用可否、環境変数）を正確に把握するには、作成時に最新のドキュメントを取得してください。docs.langchain.com/langsmith（annotate-code、threads、dashboards）または Context7 経由で langchain-ai/langsmith-sdk のドキュメントを参照してください。API をでっち上げないでください。

ステップ 2 — エージェントのトポロジーをマッピングする

（上流の評価にトポロジー図がすでに含まれている場合は、スキップするか再利用してください。）Explore エージェントを 1 つ起動するか（非常に小規模なリポジトリの場合は直接調査して）、ファイルパスを示しながら、次の 4 つの質問に答えてください。

1. ターンはどこで始まりますか？ — エントリポイント：HTTP ハンドラー、CLI の動詞、キューコンシューマー、チャットプラットフォームの Webhook などです。スレッドキー（session_id）はここで取得します。
2. エージェントユニットには何がありますか？ — スーパーバイザー関数、サブエージェントのファクトリー、役割に特化したループなどです。ユーザーメッセージを受け取り、応答を返すものが該当します。これらがルート／子ランの境界になります。
3. ツールはどこで定義され、呼び出されますか？ — ツールレジストリ（tools: [...]）、@tool デコレーター、MCP サーバーの配線などです。各ツールは tool 型のランとして表示される必要があります。
4. サブエージェント同士のハンドオフはどこで発生しますか？ — スーパーバイザーからワーカーへの引き継ぎ、並列ファンアウト、グラフノードの遷移などです。LangSmith は親ランのメタデータやタグを子ランに伝播しないため、スレッドキーとメタデータを再付与する必要がある箇所です。

計画には、簡潔なトポロジー図（ASCII または Mermaid）として記録してください。網羅的である必要はありません。実装時に顧客が参照できる全体像を 1 つ示すことが重要です。

ステップ 3 — LangSmith の命名／マッピング表を作成する

references/langsmith-mapping.md を読み、トポロジーに適用してください。

• 外部から見て意味のあるユニットごとにルートラン名を 1 つ設定します（chat-turn、job.summarise-thread、cron.nightly-research）。run_type="chain" を指定します。
• 役割ごとに子ラン名を 1 つ（supervisor、research-agent、writer-agent）、ツールごとに 1 つ（tool.<tool-id>、run_type="tool"）設定します。モデル呼び出しには llm.<model-shortname>、run_type="llm"、検索には retrieve.<store>、run_type="retriever" を指定します。
• すべてのランにスレッドキー（session_id、または thread_id／conversation_id）を設定します。ルートに設定し、メタデータは継承されないため、各子ランにも再付与してください。
• タグ：スタック識別子、環境（dev／staging／prod）、エージェントのバージョン、該当する場合は機能フラグの割り当て。
• メタデータキー：グラフでグループ化できるよう、一貫性のある少数のキーを使用します。agent_role、tool_id、model_id、prompt_version、user_tier、（Ratel が存在する場合は）gateway_origin です。

計画には、導入するすべてのラン名／タグ／メタデータキーを、顧客が共有ドキュメントに貼り付けられる 1 つの表にまとめ、references/langsmith-mapping.md を引用してください。ダッシュボード仕様（ステップ 5）と /ratel-langsmith-analyze は、どちらもこの表を参照します。表がないと、これらは機能しません。このマッピングは、ベンダーに依存しない規約（../ratel-observability-assessment/references/semantic-conventions.md）を LangSmith のプリミティブに適用したものです。ルールを改めて導出しないでください。

ステップ 4 — ファイルごとの計測変更を仕様化する

配線が必要なファイルごとに、改めてパターンを導出するのではなく、スタックリファレンス（references/stack-*.md）から該当するパターンを引用してください。各項目には、ファイルパス、何をラップするか、使用するラン型（chain／tool／llm／retriever）、およびステップ 3 の表に従って付与する名前／タグ／メタデータを記載します。すべてのランに必須となるスレッドキーも含めてください。

ステップ 5 — ダッシュボードを仕様化する（二つのグループ）

references/langsmith-value-map.md と ../ratel-observability-assessment/references/general-agent-dashboards.md を開きます。まず、組み込みの Monitor タブでプロジェクトごとにすでに確認できる項目（トレース、LLM 呼び出し、コストとトークン、ツール、実行タイプ、フィードバックスコア）を確認します。これらをカスタムチャートとして再仕様化しないでください。次に、実際に計測されている項目に合ったカスタムチャートを選びます。

デフォルトの選択：

• Ratel の価値グループ（Ratel が導入済み、または導入予定の場合のみ）：トークンコストと削減額、検索品質、ゲートウェイのオリジン別内訳、アップストリームの健全性、スキル検索の健全性（v0.1.6 系列で提供されたスキル）。ロードマップ上の条件付き項目は、顧客がその機能を含む Ratel のプレリリース版を利用している場合、または採用を明示的に表明している場合（例：v0.1.9 の提案採用）に限り追加します。名称とチャート仕様は references/langsmith-value-map.md に記載されています。
• エージェント健全性グループ：レイテンシとコストの概要、エラーの状況、ツールの使用状況、セッション品質、モデルとプロンプトのドリフト。../ratel-observability-assessment/references/general-agent-dashboards.md を参照します。ただし、このプロジェクトの Monitor タブですでに確認できるものは除外し、残りを LangSmith のカスタムチャートとして作成します。Langfuse の「observation」フィルターは run type／run name フィルターに、Langfuse の「trace」フィルターは is_root に置き換えます。

各ダッシュボードセクションは、次の順序で記述します。

1. 名称 — 短く、行動につながる名前にします（Dashboard 1 ではなく Token Cost & Savings）。
2. 重要な理由 — 平易な英語で1段落にまとめます。顧客の PM が、自分に関係するダッシュボードかどうかを判断できるようにします。
3. 必要なデータ — 依存する実行名、実行タイプ、タグ、メタデータキーを記載します。ステップ 3 の表にない項目は、ここに TODO のブロッカーとして記載します。
4. チャート — 各チャートについて、references/langsmith-value-map.md のチャート用語にある5つのフィールドをすべて記入します。指標（Y 軸）、フィルター（実行名／実行タイプ／タグ／メタデータ／is_root）、グループ化（タグ／メタデータ／実行名／実行タイプ — 上位5件）または明示的なデータ系列、チャートタイプ（折れ線／棒）です。グループ化の上位5件では不十分な場合、明示的な A/B 比較にはデータ系列を使用します。
5. 切り口／ドリルダウン — チャートに異常が見られたときにクリックする項目と、そのドリルダウンの場所を記載します（チャート作成後に顧客が再利用する、保存済みの実行テーブルフィルター）。
6. ロードマップの注記（Ratel ダッシュボードのみ）— ダッシュボードに未提供の Ratel 機能があると役立つ場合は、その機能名と対象バージョンを記載します。最新の情報を保つため、../ratel-observability-assessment/references/ratel-value-map.md のバージョン一覧を再利用します。

裏付けとなるデータが計測されていないダッシュボードは除外します。作り上げずに、スキップしてください。

Step 6 — Ratel を考慮したフックを決める（Ratel がすでに存在する、または導入予定の場合のみ）

マニフェストのいずれかの箇所に、@ratel-ai/sdk、Python の ratel-ai パッケージ、ratel-ai-core、ratel-mcp パッケージ、または @ratel-ai/mcp-server パッケージが記載されているか確認します。記載がある場合、または今回の取り組みの一環として顧客が Ratel を導入する予定の場合は、references/ratel-hooks.md を読み、以下を含むセクションを計画に追加します。

• 各 Ratel トレースイベントを LangSmith の run にマッピングします（search → run_type: tool、名前は ratel.search_capabilities、skill_search → ratel.skill_search、get_skill_content → ratel.get_skill_content、InvokeStart／InvokeEnd → run_type: tool、名前は ratel.invoke_tool など）。名前は references/langsmith-value-map.md で予約されています。
• 各 run に必要なメタデータ：gateway_origin（direct と agent のいずれか）、top_k、hit_count、replace_mode、最上位ヒットのスコア、レイテンシ。メタデータは継承されないため、スレッドキーも再度付与します。
• Ratel の接続後に顧客が A/B 比較を実施できるよう、「導入前／導入後」のアノテーション戦略を設けます（feature_flag タグの分割を group-by または Data Series でグラフ化するのが A/B 比較の方法です）。

Ratel が存在せず、導入予定もない場合は、このセクション全体を省略してください。顧客所有のドキュメントに Ratel の営業文句をあらかじめ組み込まないでください。計画は誠実な内容にしてください。

Step 7 — 計画を作成する

計画を <repo>/.ratel/ratel-langsmith-integrate.md に作成します（.ratel/ ディレクトリが存在しない場合は作成してください。リポジトリで別のドキュメント規約がすでに使われている場合は、ユーザーにパスを確認してください）。

計画には、次の項目をこの順序で含めます。

1. 概要 — 1 段落で、検出したスタック、エージェントのトポロジー、すでに計装されている内容（あれば）、この計画で追加する内容（接続とダッシュボード）、各グループのダッシュボード数を記載します。
2. セットアップ — SDK のインストールコマンド（Python／JS 用の langsmith）、環境変数（LANGSMITH_TRACING=true、LANGSMITH_API_KEY、LANGSMITH_PROJECT、LANGSMITH_ENDPOINT）、LangSmith MCP サーバーの登録手順（後から /ratel-langsmith-analyze で run を読み取れるようにするための、顧客の Claude Code／Cursor 用 langsmith-mcp-server 設定）、および貼り付けて動作を確認できる「hello trace」のコード例。
3. トポロジー — Step 2 の図。
4. LangSmith の命名／マッピング表 — Step 3 の表。出典として references/langsmith-mapping.md を明記します。
5. ファイルごとの計装変更 — Step 4 の内容。対応する references/stack-*.md を出典として明記します。
6. ダッシュボード構築仕様 — Step 5 の 2 つのグループ（Ratel の価値とエージェントの健全性）。組み込みの Monitor タブですでに確認できる内容を記載し、references/langsmith-value-map.md および ../ratel-observability-assessment/references/general-agent-dashboards.md を出典として明記します。
7. Ratel フック（Step 6 に従い、条件付き）。出典として references/ratel-hooks.md を明記します。
8. 検証チェックリスト — references/verification-checklist.md から転記します。計装が導入されたら顧客がチェックできる 6 項目を含めます。
9. 対象外（現時点） — 顧客がロードマップにある Ratel 機能を v<X.Y.Z> で採用した後に追加するダッシュボード、および現時点では利用できないデータを必要とするダッシュボード。

目次をチャット内に表示します。セクション一覧に加え、「重要な理由」を一文で示した番号付きのダッシュボード一覧も記載し、ファイルパスをユーザーに伝えてください。計画本文全体やチャート仕様全体をチャットに貼り付けないでください。成果物はファイルです。

トレースが流れ始めた後の次のステップとして、ライブデータを読み取り、修正案を提示するために /ratel-langsmith-analyze を実行するようユーザーに伝えてください。

正直なスキップ基準

いくつかのケースでは処理を止めて、その旨を伝えてください。成果物を決して捏造しないでください。

1. エージェントの実装箇所が見つからない。 ステップ 1 の後、LLM クライアントのインポート、エージェントループ、モデル呼び出しのいずれも見つからない場合は、処理を止めてください。計画書は作成しないでください。ユーザーに次のように伝えてください。

   エージェントの実装箇所が見つかりませんでした。確認したファイル：<確認したファイル>。このコードベースのエージェントコードが標準的でない場所にある場合は、その場所を教えてください。再度確認します。

   エージェントを含まないコードベースに対して無理に計装計画を作ると、役に立たない文書が生まれ、パートナーからの信頼を損ないます。

2. 参照資料のないスタック（例：Ruby、Go、ニッチなフレームワーク）。それでも計画書は作成しますが、スタック固有のセクションには「Python の汎用リファレンスに基づく類推」と明記し、新しいリファレンスの作成をフォローアップとして開始するかどうか、ユーザーに確認してください。確信があるように装わないでください。

3. Ratel がなく、Ratel の価値を示すダッシュボードだけを希望している顧客。 Ratel のダッシュボードを利用するには、少なくともゲートウェイ経由の経路が接続されている必要があります。Ratel に依存するダッシュボードを設計する前に、小規模な Ratel のパイロットを推奨してください（ゲートウェイだけなら、統合は半日で完了します）。Ratel を使用していないエージェントに Ratel のフックを無理に追加しないでください。代わりにエージェントの健全性グループを表示し、Ratel の価値を示すグループは Ratel の導入待ちであることを記してください。

4. 計装やダッシュボードが必要だが、まだ実データがない。 計画書は作成しますが、すべてのダッシュボードに「ブロック中：データなし — 本番トラフィックが初めて流れた後に再評価」と記してください。空のダッシュボードはチームの士気を下げます。

リファレンスファイル

• references/stack-vercel-ai-sdk.md
• references/stack-typescript-generic.md
• references/stack-python-generic.md
• references/stack-python-agentic.md
• references/langsmith-mapping.md — 汎用セマンティック規約の LangSmith での表現
• references/langsmith-value-map.md — Ratel の実行名、Ratel の価値を示すグラフの仕様、LangSmith のグラフ用語
• references/ratel-hooks.md — Ratel のイベントから LangSmith の実行への対応
• references/verification-checklist.md

共通のベンダー中立リファレンス（/ratel-observability-assessment が管理。複製せずリンクします）：

• ../ratel-observability-assessment/references/instrumentation-philosophy.md
• ../ratel-observability-assessment/references/semantic-conventions.md
• ../ratel-observability-assessment/references/general-agent-dashboards.md
• ../ratel-observability-assessment/references/ratel-value-map.md