langfuse

Langfuse

このスキルでは、アプリケーションの計装、プロンプトの移行、トレースのデバッグ、プログラムからのデータへのアクセスなど、一般的なあらゆるワークフローで Langfuse を効果的に使う方法を説明します。

基本原則

Langfuse を使う際は、常に次の原則に従ってください。

1. まずドキュメントを確認：記憶に基づいて実装することは絶対に避けてください。コードを書く前に、必ず最新のドキュメントを取得してください（Langfuse は頻繁に更新されます）。ドキュメントの確認方法については、以下のセクションをご覧ください。
2. データへのアクセスには CLI を使用：Langfuse のデータをクエリまたは変更する場合は、langfuse-cli を使用してください。CLI の使用方法については、以下のセクションをご覧ください。
3. ユースケースに応じたベストプラクティス：ユーザーに詳しい情報を尋ねたり、実装を始めたりする前に、該当するユースケース固有のガイドラインを以下のリファレンスで確認してください。
4. 最新バージョンの Langfuse を使用：ユーザーから別の指定がある場合や、別のバージョンを使う正当な理由がある場合を除き、常に最新バージョンの Langfuse SDK／API を使用してください。別のエージェントが実行する計画を作成する場合も、使用する正確なバージョンを明記してください。
5. UI の操作をユーザーに案内する場合、ラベルや場所が不明なときは、ユーザーのスクリーンショットを確認するか、該当する画面を見せてもらってください。UI のラベルが API、SDK、CLI のフィールドとまったく同じ名前だと決めつけないでください。

ユースケース別のリファレンス

• 既存の関数／アプリケーションを計装する：references/instrumentation.md
• AI システムの品質測定やリグレッションテストに適した評価データセットを作成する、または見つける：references/create-dataset.md
• コードベースから Langfuse にプロンプトを移行する：references/prompt-migration.md
• プロンプトを作成する、または既存のプロンプトの一部を変更する（小さな編集やデバッグ／調整を含む）：references/prompt-engineering.md
• ユーザーがシグナルの取得、モニタリング、評価指標におけるギャップを特定するための評価を設定する必要がある場合（「トレースはあります。評価を設定するにはどうすればよいですか？」）：references/setting-up-evals.md
• 明示的な評価、行動イベント、会話シグナル、タスクの結果など、ユーザーフィードバックのシグナルをスコアとして取得する：references/user-feedback.md
• Langfuse CLI を使う際の追加のヒント：references/cli.md
• v4 プラットフォームへの移行に向けて Langfuse プロジェクトを準備する：references/v4-project-migration.md
• ラベル付きの例を使って新規または既存の LLM-as-a-Judge を調整し、そのプロンプトを反復改善して、承認済みの判定器をデプロイする：references/judge-calibration.md
• 直接依頼された場合、またはエージェントによるトレースの調査後も評価の設定に具体的な障害モードが見つからない場合に、体系的なエラー分析を行う：references/error-analysis.md
• langfuse/experiment-action を使って CI/CD の実験ゲートを設定する：references/ci-cd.md
• LLM アプリケーションまたは AI エージェントのコストを最適化する：references/cost-optimization.md
• このスキルについてフィードバックを送信する：references/skill-feedback.md

1. CLI による Langfuse API

langfuse-cli を使用すると、コマンドラインから Langfuse REST API 全体を操作できます。npx 経由で実行するため、インストールは不要です。

まず、スキーマと使用可能な引数を確認します。

# Discover all available resources
npx langfuse-cli api __schema

# List actions for a resource
npx langfuse-cli api <resource> --help

# Show args/options for a specific action
npx langfuse-cli api <resource> <action> --help

認証情報

呼び出しを行う前に、環境変数を設定します。

export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...
export LANGFUSE_BASE_URL=https://cloud.langfuse.com # example for EU cloud. For US cloud it's us.cloud.langfuse.com, and can also be a self-hosted URL. The server must always be specified in order to access Langfuse.

LANGFUSE_HOST の代わりに LANGFUSE_BASE_URL を使用している場合は、export LANGFUSE_HOST="$LANGFUSE_BASE_URL" を実行してください。 設定されていない場合は、シェルまたは .env ファイルに設定するようユーザーに伝えてください。キーは Langfuse プロジェクトの「Settings」→「API Keys」で確認できます。そこでプロジェクトの API キーペアを作成してもらってください。Langfuse アカウントをまだお持ちでない場合は、https://langfuse.com/cloud から無料で作成できることを案内してください。セキュリティ上の理由から、チャットにキーを貼り付けるよう求めないでください。

CLI の詳細なリファレンス

一般的なワークフロー、ヒント、使用方法の詳細については、references/cli.md をご覧ください。

2. Langfuse Documentation

Langfuse のドキュメントにアクセスする方法は 3 つあります。優先度の高い順に記載しています。利用可能な場合は、curl よりもアプリケーション標準のウェブ取得ツールや検索ツール（例：WebFetch、WebSearch、mcp_fetch など）を必ず優先してください。以下の URL とパターンは、どの取得方法でも使用できます。curl の例はあくまで参考です。

セルフホスト版の Langfuse を使用する場合は、インストール済みバージョンと一致するように、デプロイ環境から提供される API リファレンスを優先してください。

2a. ドキュメントインデックス（llms.txt）

すべてのドキュメントページの完全なインデックスを取得します。

curl -s https://langfuse.com/llms.txt

タイトルと URL を含む、すべてのドキュメントページの構造化された一覧が返されます。これを使ってトピックに適したページを見つけ、そのページを直接取得してください。

または、https://langfuse.com/docs から始めて、サイト内を探索し、必要なページを見つけることもできます。

2b. 個別ページを Markdown として取得する

llms.txt に記載されているページは、パスの末尾に .md を追加するか、リクエストヘッダーに Accept: text/markdown を指定すると、Markdown として取得できます。必要な情報が記載されているページがわかっている場合に使用してください。コード例と設定の詳細を含む、整形された Markdown が返されます。

curl -s "https://langfuse.com/docs/observability/overview.md"
curl -s "https://langfuse.com/docs/observability/overview" -H "Accept: text/markdown"

2c. ドキュメントを検索する

特定のページがわからず、すべてのドキュメントと GitHub の Issue／Discussion から情報を探したい場合：

curl -s "https://langfuse.com/api/search-docs?query=<url-encoded-query>"

例：

curl -s "https://langfuse.com/api/search-docs?query=How+do+I+trace+LangGraph+agents"

次の内容を含む JSON レスポンスが返されます。

• query：元のクエリ
• answer：一致したドキュメントの配列を含む JSON 文字列。各ドキュメントには以下が含まれます。
  • url：ドキュメントページへのリンク
  • title：ページのタイトル
  • source.content：ページから抜粋した、関連するテキストの配列

関連ページが見つからない場合や、さらに詳しい情報が必要な場合、検索は優れた代替手段です。すべての GitHub Issue と Discussion もインデックス化されているため、問題のデバッグ時に特に役立ちます。レスポンスが大きくなる場合があるため、関連する部分だけを抽出してください。変更履歴の投稿が検索結果に表示されることもありますが、機能が存在することの確認にのみ使用し、実装の根拠にはしないでください。例が古くなっている可能性があるため、必ずドキュメントと API／SDK リファレンスに基づいて実装してください。

ドキュメントのワークフロー

1. まず llms.txt を確認し、関連するページのタイトルに目を通して全体像を把握します
2. 適切なページが見つかったら、特定のページを取得します
3. トピックが明確でない場合や、さらに詳しい情報が必要な場合は、検索を利用します

スキルに関するフィードバック

ユーザーから、このスキルの動作が期待どおりでない、案内が正しくない、情報が不足している、または改善できると伝えられた場合は、Langfuse スキルのメンテナーにフィードバックを送ることを提案してください。以下のような場合が含まれます。

• スキルが誤った指示や古い指示を提示した
• ワークフローを実行しても期待した結果にならなかった
• ユーザーが、このスキルで扱われていない内容も対象にしてほしいと望んでいる
• ユーザーが「こう動作するべきだ」や「これは間違っている」などと明確に述べている

Langfuse 自体（製品）に関する問題では、これを行わないでください。対象となるのは、このスキルの指示や動作に関する問題のみです。

該当する場合は、references/skill-feedback.md に記載された手順に従ってください。