ratel-langfuse-integrate

/ratel-langfuse-integrate — エージェントの Langfuse カバレッジとダッシュボードを設定する

Ratel チームが行う方法で、お客様のコードベースに Langfuse を組み込み、その価値を証明するダッシュボードの仕様を策定します。1 つのスキルに 2 つの要素があります。計装の設定（トレースを配置する場所、名前の付け方、設定方法）と、ダッシュボード構築仕様（具体的なウィジェットを含む、構築するボード）です。成果物は計画です。エージェントのコードは編集せず、Langfuse API も呼び出しません。お客様が Langfuse UI を操作してダッシュボードを構築します。これは意図的な設計です。

これは、オブザーバビリティの流れにおける Langfuse 分岐です。汎用の /ratel-observability-assessment が、ベンダーに依存せずに、何を取得するか、どのダッシュボードが重要かを判断し、ベンダーを検出します。そのベンダーが Langfuse の場合、ここに処理を引き継ぎ、計画を具体的な Langfuse プリミティブに落とし込みます。トレースが流れ始めた後の後続作業は /ratel-langfuse-analyze で行い、この計画が生成するライブデータを読み取ります。

考え方：呼び出しグラフではなく、メンタルモデルをトレースする

よくある失敗は、「すべての関数をスパンで囲む」ことです。これではコードの呼び出しグラフに一致するトレースが生成されますが、エージェントが何をしようとしていたのかは何も分かりません。Langfuse のトレースが最も役立つのは、その構造がターンの概念的な構造と一致している場合です。

• トレース＝外部から意味のある作業単位 1 つ（チャットの 1 ターン、ジョブ 1 件、Webhook 1 件）。1 つのリクエストに複数のエージェントターンが含まれる場合、「HTTP リクエスト 1 件」ではありません。1 つのターンに複数のモデル呼び出しが含まれる場合、「モデル呼び出し 1 回」でもありません。
• オブザベーション＝その単位の中でエージェントが実行したステップ 1 つ。サブエージェントの呼び出し、ツール呼び出し、モデル呼び出し、検索ステップなどです。ソースファイルの構成ではなく、委任関係が反映されるようにネストします。
• セッション＝session_id を共有する、関連するトレースのスレッドです。通常はユーザーとの会話、エージェントの実行 ID、またはジョブの相関 ID です。

これらの考え方の詳しい根拠は、../ratel-observability-assessment/references/instrumentation-philosophy.md にまとめられています。用語を Langfuse 固有の形に落とし込んだ対応関係、つまり汎用的な概念がどの Langfuse プリミティブ、タイプ、キーに対応するかは、references/langfuse-mapping.md に記載されています。

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

このスキルでは、ダッシュボードを必ず 2 つのグループに分けて構築します。同じデータから、パートナー企業のスタートアップが求める異なる 2 つのストーリーを示すためです。

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

Ratel 専用のダッシュボードは売り込みのように感じられ、エージェントの健全性だけを示すダッシュボードは、ここに来た理由を忘れたかのように見えます。Ratel が関わる場合は、必ず両方を含めます。

ワークフロー

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

<repo>/.ratel/ratel-observability-assessment.md を探します。これは /ratel-observability-assessment の成果物です。ファイルがあれば、推奨入力として、検出されたスタック、トポロジー、ベンダーに依存しない計装戦略、推奨ダッシュボードの一覧を読みます。検出されたベンダーが Langfuse であることを確認してください。LangSmith（または別のベンダー）と記載されている場合は作業を中止し、これは Langfuse スキルであり、対応する *-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
langfuse と openai／anthropic／langchain／llama_index	Python 汎用	references/stack-python-generic.md
langgraph、crewai、agno、autogen	Python エージェント型	references/stack-python-agentic.md

シグナルが重複する場合（例：LangGraph のスーパーバイザーと、その内部での生の OpenAI 呼び出し）、エージェント型のリファレンスを主に使い、計画内で混在スタックについても明記します。

エージェントの実行面をまったく特定できない場合（LLM クライアントのインポート、エージェントフレームワーク、モデル呼び出しがない場合）は、誠実なスキップの手順を使用します。

ステップ 2 — エージェントのトポロジーを整理する

（上流の評価にトポロジー図がすでにある場合は省略、または再利用します。）Explore エージェントを 1 つ起動する（または非常に小さなリポジトリなら直接調査する）ことで、ファイルパスを示しながら次の 4 つの質問に答えます。

1. ターンはどこで始まりますか？ — HTTP ハンドラー、CLI の動詞、キューのコンシューマー、チャットプラットフォームの Webhook などのエントリーポイントです。ここに session_id があります。
2. エージェントの単位は何ですか？ — スーパーバイザー関数、サブエージェントのファクトリー、役割に特化したループなどです。ユーザーメッセージを受け取り、応答を返すものはすべて該当します。これらがトレースの境界になります。
3. ツールはどこで定義され、呼び出されていますか？ — ツールレジストリー（tools: [...]）、@tool デコレーター、MCP サーバーの接続設定などです。各ツールは tool 型のオブザベーションとして表面化する必要があります（Langfuse v4）。
4. サブエージェント間の引き継ぎはどこで行われますか？ — スーパーバイザーからワーカーへの引き継ぎ、並列ファンアウト、グラフノードの遷移などです。境界を越えてセッション／ユーザー／タグのコンテキストを維持できるよう、propagate_attributes()（またはフレームワークに相当する機能）が必要な箇所です。

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

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

references/langfuse-mapping.md を読み、トポロジーに適用します。

• 外部から意味のある単位ごとにトレース名を 1 つ割り当てます（chat-turn、summarize-thread、nightly-research-job）。
• 役割ごとにオブザベーション名を 1 つ割り当てます（supervisor、research-agent、writer-agent）。ツールごとに tool.<tool-id> を割り当て、モデル呼び出しは llm.<model-shortname> の生成として記録します。
• トレースに session_id と user_id を設定します。早い段階で設定し、propagate_attributes(...) で伝播させます。
• タグ：スタック識別子、環境（dev／staging／prod）、エージェントのバージョン、該当する場合はフィーチャーフラグのアーム。
• メタデータキー：ダッシュボードで切り口として使えるよう、一貫した少数のキーを使用します — agent_role、tool_id、model_id、prompt_version、user_tier、gateway_origin（Ratel が存在する場合）。

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

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

配線が必要なファイルごとに、ルールを再導出するのではなく、スタックリファレンス（references/stack-*.md）の該当するパターンを引用してください。各項目には、ファイルパス、ラップする対象、使用するオブザベーションの種類（span／tool／generation）、およびステップ 3 の表に従って付与する名前／タグ／メタデータを記載します。

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

references/langfuse-value-map.md、../ratel-observability-assessment/references/general-agent-dashboards.md、references/widget-cheatsheet.mdを開きます。顧客の環境で実際に計測されている内容に合った項目を選びます。

デフォルトの選択項目：

• Ratel の価値を示すグループ（Ratel が導入済み、または導入予定の場合のみ）：トークンコストと削減額、検索品質、ゲートウェイの接続元の内訳、上流の健全性、スキル検索の健全性（v0.1.6 系列で提供されたスキル）。ロードマップに依存する項目は、顧客がその機能を含む Ratel のプレリリース版を利用している場合、または採用を明示的に申し込んでいる場合（例：v0.1.9 の提案採用）のみ追加します。名称とウィジェットの仕様はreferences/langfuse-value-map.mdを参照します。
• エージェントの健全性を示すグループ：レイテンシとコストの概要、エラーの状況、ツールの使用状況、セッションの品質、モデルとプロンプトのドリフト。出典は../ratel-observability-assessment/references/general-agent-dashboards.mdです。

各ダッシュボードのセクションには、次の項目をこの順番で記載します。

1. 名前 — 簡潔で、行動につながる名前にします（Token Cost & Savingsなど。Dashboard 1は避けます）。
2. 重要な理由 — 平易な英語で 1 段落にまとめます。顧客の PM が自分に関係のあるダッシュボードかどうか判断できるようにします。
3. 必要なデータ — 依存するトレース名、オブザベーションの種類、タグ、メタデータキーを記載します。ステップ 3 の表に不足している項目は、ここに TODO のブロッカーとして記載します。
4. ウィジェット — 各ウィジェットについて、references/widget-cheatsheet.mdにある 5 つの項目を記入します。データソース（traces / observations / scores）、指標、集計、ディメンション、フィルターに加えて、可視化の形式も記載します。
5. ピボット／ドリルダウン — ダッシュボードで異常が見つかったときに何をクリックするか、ドリルダウン先（ダッシュボードの作成後に顧客が一度貼り付ける、保存済みのトレースフィルター URL）を記載します。
6. ロードマップに関する注記（Ratel ダッシュボードのみ） — 未リリースの Ratel 機能がダッシュボードに役立つ場合、その機能名と目標バージョンを記載します。常に最新の情報を保つため、../ratel-observability-assessment/references/ratel-value-map.mdにあるバージョンマップを使用します。

裏付けとなるデータが計測されていないダッシュボードは削除します。捏造せず、対象から外してください。

ステップ 6 — Ratel 対応フックを決定する（Ratel が導入済み、または導入予定の場合のみ）

マニフェスト内のどこかに@ratel-ai/sdk、Python のratel-aiパッケージ、ratel-ai-core、またはratel-mcp／@ratel-ai/mcp-serverパッケージがあるか確認します。該当するものがある場合、またはこの契約の一環として Ratel の追加を顧客が申し込んでいる場合は、references/ratel-hooks.mdを読み、次の内容を網羅するセクションを計画に追加します。

• 各 Ratel トレースイベントを Langfuse のオブザベーションに対応付けます（search → オブザベーションの種類tool、名前ratel.search_capabilities、skill_search → ratel.skill_search、get_skill_content → ratel.get_skill_content、InvokeStart／InvokeEnd → オブザベーションの種類tool、名前ratel.invoke_toolなど）。名前はreferences/langfuse-value-map.mdで予約されています。
• 各オブザベーションに必要なメタデータ：gateway_origin（directとagentのどちらか）、top_k、hit_count、replace_mode、最上位のヒットのスコア、レイテンシ。
• 顧客が Ratel の接続後に A/B 比較を実施できるよう、「導入前／導入後」の注釈付け戦略を用意します（feature_flagタグによる分割が A/B 比較の対象です）。

Ratel が導入されておらず、導入予定もない場合は、このセクションを完全に省略します。顧客が所有するドキュメントに Ratel の営業文句をあらかじめ盛り込まず、計画の内容は事実に即したものにしてください。

ステップ 7 — 計画を作成する

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

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

1. 概要 — 1段落で、検出したスタック、エージェントのトポロジー、既に計装されているもの（あれば）、この計画で追加するもの（配線＋ダッシュボード）、各グループのダッシュボード数を記載します。
2. セットアップ — SDK のインストールコマンド、環境変数、Langfuse MCP サーバーの登録手順（顧客の Claude Code / Cursor 用）、および貼り付けて動作を確認できる「hello trace」スニペット。
3. トポロジー — ステップ 2 の図。
4. Langfuse の命名／マッピング表 — ステップ 3 の表。 references/langfuse-mapping.md を引用します。
5. ファイルごとの計装変更 — ステップ 4 の内容。該当する references/stack-*.md を引用します。
6. ダッシュボード構築仕様 — ステップ 5 の 2 つのグループ（Ratel-value と agent-health）。references/langfuse-value-map.md、../ratel-observability-assessment/references/general-agent-dashboards.md、および references/widget-cheatsheet.md を引用します。
7. Ratel フック（ステップ 6 に従い、該当する場合）。references/ratel-hooks.md を引用します。
8. 検証チェックリスト — references/verification-checklist.md から転記します。計装が完了したら顧客がチェックできる 6 項目です。
9. 対象外（現時点） — 顧客がロードマップにある Ratel の機能（v<X.Y.Z>）を採用した後に追加するダッシュボード、および現時点ではデータがないため作成できないダッシュボード。

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

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

正直なスキップパス

スキップすべきケースがいくつかあります。その場合は作業を止めて、その旨を伝えてください。成果物を捏造してはいけません。

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

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

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

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

3. 顧客が Ratel-value ダッシュボードのみを希望し、Ratel を利用していない場合。 Ratel のダッシュボードには、少なくともゲートウェイ経路の配線が必要です。それに依存するダッシュボードを設計する前に、小規模な Ratel パイロット（ゲートウェイだけなら半日の統合作業です）を推奨してください。Ratel を利用していないエージェントに Ratel フックを組み込んではいけません。代わりに agent-health グループを作成し、Ratel-value グループは Ratel の採用待ちであると記載してください。

4. 計装／ダッシュボードはあるが、まだライブデータがない場合。 計画は作成しますが、すべてのダッシュボードに「ブロック中：データなし — 本番トラフィックの初回到達後に再評価」と記載してください。空のダッシュボードはチームの意欲を損ないます。

参照ファイル

• references/stack-vercel-ai-sdk.md
• references/stack-typescript-generic.md
• references/stack-python-generic.md
• references/stack-python-agentic.md
• references/langfuse-mapping.md — 汎用セマンティック規約の Langfuse での表示
• references/langfuse-value-map.md — Ratel のオブザベーション名と Ratel 値ダッシュボードウィジェットの仕様
• references/ratel-hooks.md — Ratel イベント → Langfuse オブザベーション
• references/widget-cheatsheet.md — Langfuse v4 ウィジェット用語
• 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