top of page
検索

ADK (Agent Development Kit) で開発したAgentの挙動 を Langfuseで可視化しよう！

  • 執筆者の写真: KAMON Nobuchika
    KAMON Nobuchika
  • 13 時間前
  • 読了時間: 6分

更新日：36 分前


  1. はじめに


本記事では、Agent Development Kit (ADK) によって構築されたAIエージェントの挙動をLiteLLMを通じてLangfuseで可視化する方法について解説していきます。

  • ADKの基本的な内容やその評価についてはこちら

  • Langfuse についての 説明についての記事はこちら


生成AIアプリケーションやAIエージェントを開発し、そのパフォーマンスを最大限に引き出す上で、内部処理の可視化は成功の鍵を握ると言っても過言ではありません。これは、ADKを用いた開発においても例外ではありません。


可視化ツールとして Cloud Trace のような選択肢も考えられますが、本記事では、導入の容易さ、直感的な操作性、そして LLMOps 全体のトレーサビリティをオープンソースで実現できるLangfuseに焦点を当てます。


ただし、ADK から Langfuse へ直接Traceを連携させようとすると、現時点（2025年5月8日）では注意が必要です。例えば、OpenTelemetry 経由で Langfuse にトレースを送信した場合、全ての情報がメタデータとして一括りに扱われてしまい、詳細な分析やデバッグが困難になるなどの課題があります。


そこで本記事では、この課題を解決し、ADKで開発するエージェントの情報を Langfuse 上で効果的に可視化するためのアプローチとして、ADK と Langfuse が共にネイティブサポートしている LiteLLM を利用する構成をご紹介します。この構成を採用することで、LLM とのやり取りを含む詳細なトレース情報を、構造化された形でスムーズに Langfuseへ連携させることが可能になります。構成はおおまかには以下のようになります。


ADK で作ったAgentと同じ環境にProxyとしてLiteLLMを起動
ADK で作ったAgentと同じ環境にProxyとしてLiteLLMを起動

それでは、LiteLLM のセットアップから進めていきましょう。



  1. LiteLLM とは


LiteLLMは、OpenAI、Azure、VertexAI/Gemini、Anthropicなど、100種類以上の様々な大規模言語モデル（LLM）に対して、統一されたシンプルなインターフェースでアクセスできるようにするライブラリです。 これにより、開発者は特定のLLMプロバイダーにロックインされることなく、アプリケーションの要件に応じて最適なモデルを柔軟に選択・切り替えることが可能になります。 LiteLLM は、APIキー管理、呼び出しのフォーマット統一、そしてリクエストのロギングやコールバック, 同一コードでの切り替え, 帯域制限やコスト管理といった機能など提供し、LLM 運用において大きな助けとなります。LiteLLM には SDK として利用するモードと、Proxy として動作させるモードがありますが、今回はついでにProxy モードのセットアップ方法も紹介しながら構成を作っていきます。


LiteLLM (Proxyモード) のセットアップ


セットアップは非常にシンプルです。公式の手順 がありますので、基本的にはこれに沿って進めるだけで立ち上げることが可能です。 litellm_config.yaml に model 定義などを入れるのですが、今回は以下のような設定をしています。


model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o 
      api_key: "os.environ/OPEN_AI_API_KEY"
  - model_name: gemini-2.0-flash
    litellm_params:
      model: vertex_ai/gemini-2.0-flash
      vertex_project: "YOURPROJECTNAME"
      vertex_location: "us-central1"
      vertex_credentials: "os.environ/VERTEXAIFILE"
  - model_name: gemini-2.5-flash
    litellm_params:
      model: vertex_ai/gemini-2.5-flash-preview-04-17
      vertex_project: "YOURPROJECTNAME"
      vertex_location: "us-central1"
      vertex_credentials: "os.environ/VERTEXAIFILE"
  
general_settings:
  master_key: sk-1234

litellm_settings:
  drop_params: True
  success_callback: ["langfuse"] 
  redact_user_api_key_info: true

module list の中に、model_name として任意の名前をつけ、後ほどこの名前をプログラム内から利用することで、指定したモデルが使われるようになります。APIキーやクレデンシャルは、.env ファイルを作り、環境変数として読みこませておきます。


そして設定最下部に success_callback: ["langfuse"] を入れることを忘れないようにしましょう。逆にいうとLangfuse のための設定はこの１行だけという簡単さです。


続いて環境変数ファイル (.env)を、以下のような内容で作成します。


export LITELLM_MASTER_KEY="sk-1234"
export LITELLM_SALT_KEY="sk-1234"
export LANGFUSE_PUBLIC_KEY="pk-lf-****"
export LANGFUSE_SECRET_KEY="sk-lf-****"
export LANGFUSE_HOST="YOURLANGFUSEHOSTURL"
export OPEN_AI_API_KEY="sk*****"
export VERTEXAIFILE="FILENAME"
export OPENAI_API_BASE=http://localhost:4000/v1

続いて docker-compose.yml をちょっと編集します。volumes と command が最初はコメントアウトされているので、それをアンコメントして、VertexAI認証用のファイルを読み込ませています。(セキュリティ的にベストプラクティスではないですが、一時的な検証用ということで簡単な方法で実装しています) もちろん、たとえばOpenAI だけで良い場合は対応不要です。


    volumes:
      - ./litellm_config.yaml:/app/litellm_config.yaml
      - /SOURCE.json:/app/vertexaifile.json
    command:
      - "--config=/app/litellm_config.yaml"

docker compose up で Proxy を起動し、以下のように curl で疎通確認をしてみてください。結果をLangfuse内で Trace として確認できるはずです。


% curl --location 'http://0.0.0.0:4000/chat/completions' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer sk-1234' \
    --data '{
    "model": "gpt-4o",
    "messages": [
        {
        "role": "user",
        "content": "気の利いたアメリカンジョークをかましてくれ！"
        }
    ]
}'

すると、Langfuse側では以下のように Trace を確認することができます。


ジョークはつまらないですが、Trace は見えます
ジョークはつまらないですが、Trace は見えます

ここまでで一旦準備は完了です。



  1. ADK のコードを準備する


基本的には全てこちらのコードを利用し、以下に示す点のみを編集するだけです。


agent.py の冒頭で LiteLLM のモジュールをインポートします。

from google.adk.models.lite_llm import LiteLlm
from google.adk.agents import LlmAgent

続いて最下部を以下の通りに変更します。

lite_model = LiteLlm(model="openai/gemini-2.0-flash")
root_agent = LlmAgent(
    name="weather_time_agent",
    model= lite_model,
    description=(
        "Agent to answer questions about the time and weather in a city."
    ),
    instruction=(
        "You are a helpful agent who can answer user questions about the time and weather in a city."
    ),
    tools=[get_weather, get_current_time],
)

以上です！


LiteLlm の中の model には litellm_config.yaml であらかじめ定義したmodel名を定義しますが、その際に指定した openai インターフェイスに則った LiteLLM Proxy のエンドポイントを指定するため、明示的に "openai/" と指定しています。Google が提供する LLM であるGemini にアクセスするのに openai/gemini という記載になることに違和感があるかもしれませんが、これにより OPENAI_API_BASE と .env に定義した先にリクエストが飛ぶようになるため、必須の設定となります。


そして、実行するとこのように出力されます。(フォルダ名は任意に変えてください) 

 % adk run adk_agent

Log setup complete: /var/folders/ys/8vpjq9657dnb3dvq33k6q_hm0000gp/T/agents_log/agent.20250508_213004.log
To access latest log: tail -F /var/folders/ys/8vpjq9657dnb3dvq33k6q_hm0000gp/T/agents_log/agent.latest.log
Running agent weather_time_agent, type exit to exit.

[user]: new york
21:30:14 - LiteLLM:INFO: utils.py:2827 - 
LiteLLM completion() model= gemini-2.0-flash; provider = openai
21:30:15 - LiteLLM:INFO: utils.py:2827 - 
LiteLLM completion() model= gemini-2.0-flash; provider = openai

[weather_time_agent]: OK. The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees Fahrenheit).
The current time in new york is 2025-05-08 08:30:15 EDT-0400.

ちなみに上記コマンドを入れた際、以下のようなエラーが出るかもしれません。


litellm.exceptions.AuthenticationError: litellm.AuthenticationError: AuthenticationError: OpenAIException - Authentication Error, Invalid proxy server token passed. key=******, not found in db. Create key via /key/generate call.

エラーの原因は、LiteLLM Proxy が「渡されたトークン」を自身のデータベースで認識しておらず、認証に失敗しているためです。その際には以下のようなコマンドを実行して、keyを発行してみてください。


curl --location 'http://0.0.0.0:4000/key/generate' \
  --header 'Authorization: Bearer sk-master-あなたが決めたキー' \
  --header 'Content-Type: application/json' \
  --data-raw '{
     "models": ["gpt-4o"],
     "metadata": {"user": "your-user-id"}
  }'

そうすると key を含んだJSONが返却されますので、agent.py と同じディレクトリ下に置く .env に以下のような形式でKeyを追加しておいてください。

export OPEN_AI_API_KEY="sk-***"

なお locahost: 4000 でブラウザ経由でもアクセス可能ですので、LiteLLM は UI上から操作しても問題ないでしょう。


そしてエラーがなくなれば、以下のような出力を Langfuse 上で確認できます。


Agent の挙動を確認可能
Agent の挙動を確認可能

いかがでしたでしょうか？


LiteLLM を通じて、Trace が入ることを確認いただけたかと思います。ぜひお手元のADK 環境でも試してみてください！また別の機会に LiteLLM の機能の掘り下げた記事も公開していきたいと思います。Langfuse 可視化のみならず、LLMOps のサイクルをオールインワンで解決できることが強みです。ぜひこれを機会に活用してみてください。









Comments

bottom of page