AIエージェントが実際にどのように動いてトークンを使っているかが後から見てわかるようにできる「Langfuse」、オープンソースでセルフホスト可能

AIエージェントが回答を作る裏側では「LLMに問い合わせる」「検索する」「ツールを実行する」「結果を再びLLMへ渡す」といった処理が連続して行われています。その実行経路を丸ごと記録し、どこで何トークンを使用したのかまでブラウザから追跡できるオープンソースツールでセルフホストが可能な「Langfuse」が公開されています。

Langfuse
https://langfuse.com/

langfuse/langfuse: Open source AI engineering platform: LLM evals, observability, metrics, prompt management, playground, datasets. Integrates with OpenTelemetry, LangChain, OpenAI SDK, LiteLLM, and more. YC W23
https://github.com/langfuse/langfuse

◆Langfuseの概要
LangfuseはLLMやAIエージェントの実行内容を「Trace」として記録し「どのLLMを呼び出したか・どのツールを実行したか・どの情報を検索したか・入力および出力処理の消費時間・トークン使用量・推定コスト」などを後から確認できるAIエンジニアリングプラットフォームです。

◆Langfuseの利用方法
・Organizationsの登録とAPIキーの発行
Langfuseを構築後、ブラウザで「http://localhost:3000」にアクセスすると「Organizations」の一覧ページが表示されるので「New Organization」をクリック。

Setup画面になるので「Organization name」に任意の組織名を入力し「Create」をクリック。

「Project name」に任意のプロジェクト名を入力し「Create」をクリック。

プロジェクトの生成が完了しても画面遷移がうまくいかない不具合があるようなので、そのままサイドメニューの「Projects」をクリック。

作成した組織とプロジェクトが表示されれば登録は完了しています。「Go to project」をクリック。

サイドメニューの「Settings」をクリックし「API Keys」をクリックして「Create new API Keys」をクリック。

「Note(optional)」は用途などのメモが必要であれば入力し「Create API keys」をクリック。

APIキーが作成されます。「Secret key」はこの画面でのみ表示されるのでコピーして保存しておきます。

・AIエージェントへの組み込み
今回はAIエージェントとしてGoogle Geminiを利用しLangfuseと連携するために、Google Gen AI SDKとObservability for Google Gemini Models with Langfuse Integrationを利用して、PythonスクリプトからAIエージェントを呼び出した際のトレースを行います。

LangfuseでAI内部の処理を確認しやすくするため、同じ内容を別の検索キーワードでも確認するよう、あえて冗長な命令をプロンプトに加えて実行してみます。

東京の今日の天気を調べて、傘が必要か簡潔にまとめてください。

情報の正確性を高めるため、
最初に得た情報だけで判断せず、
別の検索キーワードでも同じ内容を改めて確認してください。

複数の検索結果を比較したうえで回答してください。

回答は以下のようになりました。

結論：折りたたみ傘を持ってお出かけください。

複数の検索結果を比較確認した結果は以下の通りです。
---
1. 「天気予報」での確認結果（気象庁・ウェザーニュースなど）
天気：一日を通して雲が広がりやすい天気です。日中は晴れ間が出る時間帯もありますが、昼過ぎから夕方・帰宅時間帯にかけて急に雨が降り出し、雷を伴って激しく降るおそれがあります。
気温：最高気温は32℃前後で蒸し暑くなります。

2. 「傘指数・傘マップ」での確認結果（ウェザーニュース・@nifty天気など）
複数の天気メディアの傘指数・傘マップを確認したところ、いずれも東京地方は「折りたたみ傘が必要」の判定となっています。一日中降り続く雨ではないため長傘は不要ですが、午後の天気の急変に備えて折りたたみ傘があると安心です。

ここでLangfuseに戻りサイドメニューから「Trace」をクリックすると先ほど実行したAIエージェントへの質問が登録されているので項目をクリック。

AIエージェントがどのようなデータを何回やりとりしているのか、トークン数はいくらになるのか全て記録されていることが確認できます。このやりとりでのトークン数は1883でした。

今度はプロンプトの内容を以下のようにして検索を1度だけ行うように指定しました。

東京の今日の天気を調べて、傘が必要か簡潔にまとめてください。
検索は1度だけ行うこと。

実行結果は以下の通り。

東京の最新の天気情報によると、湿度が高く（86%前後）、天気が不安定になりやすい状態となっています。

傘の必要性：
急な雨（にわか雨や雷雨）に備えて、折りたたみ傘を持って出かけるのが安心です。

Langfuseで確認するとトータルのトークン数は936となり冗長なプロンプトよりも少ないトークン数で結果が得られました。

AIエージェントが外部ツールを利用した場合は「どのツールを呼び出したか・どの引数を渡したか・どの結果が返ってきたか」もTraceに記録できます。これにより回答がおかしくなった原因がLLMそのものにあるのか、検索結果やツール選択にあるのかを切り分けられます。

・その他の機能
その他の機能としてAIへ与えるプロンプトを保存してバージョン管理できる「Prompt Management」、AIの回答を人間や別のLLMで採点する「Evaluation」、複数の入力に対してプロンプトやモデルを変更した結果をまとめて比較できる「Datasets・Experiments」などの機能があります。また、トークン使用量やコストや処理時間などをダッシュボードで集計できるほか、OpenTelemetryを利用してLangChain・OpenAI Agents SDK・Google ADK・n8n・Dify・Ollama・Codex・Claude Codeなど多数のAIツールと連携できます。

◆Langfuseの構築方法
今回はWindowsにDocker DesktopとGit for WindowsのGit Bashを用意した環境で構築します。作業フォルダーでリポジトリをクローンし、Langfuseフォルダーに移動。

git clone https://github.com/langfuse/langfuse.git
cd langfuse

コンテナを起動。

docker compose up -d

ブラウザで「http://localhost:3000」にアクセスするとログインフォームが表示されるので「Sign up」をクリック。

アカウント作成フォームの「Name」に名前、「Email」にメールアドレス、「Password」にパスワードを入力し「Sign up」をクリック。

登録・ログインが自動的に行われホーム画面が表示されれば構築完了です。