Instana + Google ADK (Traceloop) でAIエージェントのトレース取得の検証

背景と目的

Google ADK (Agent Development Kit) は、インテリジェントなエージェントを構築するための新しいフレームワークです。
この記事では、Google ADK で構築されたエージェントの動作（思考プロセスやツール呼び出し）を、Traceloop SDK を使用して可視化し、OpenTelemetry プロトコル経由で Instana に送信・監視する手順を解説します。

これにより、エージェントの「なぜその回答をしたのか？」「どのツールを使用したのか？」といった実行の透明性を確保し、デバッグや運用監視を効率化できます。

システム構成

• Google ADK (google-adk >=1.23.0)
• Traceloop SDK (traceloop-sdk)
• Instana Agent (Localhost で OTLP を受信)
• Python 3.13

Google ADKサンプルインストール手順

まず、Google ADK サンプル（今回は昨年Google ADKを利用したAromaというサンプルを利用する）リポジトリをクローンし、必要な依存関係をインストールします。

1.サンプルのWorkFlow：

2.Architecture

3.インストールコマンド：

git clone https://github.com/GSSJacky/Aroma_Agents_ADK_Project_Github.git
cd Aroma_Agents_ADK_Project_Github
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

requirements.txt には以下が含まれていることを確認してください（traceloop-sdk が必要です）。

google-adk>=1.23.0
google-generativeai>=0.3.2,<1.0.0
pydantic>=2.10.6,<3.0.0
python-dotenv>=1.0.1,<2.0.0
traceloop-sdk

コードの計装

エージェントの初期化部分（Aroma_Agents/agent.py など）に Traceloop の初期化コードを追加します。
ローカル開発環境で即座にトレースを確認するため、disable_batch=True を設定することをお勧めします。

from traceloop.sdk import Traceloop

# ローカルエージェントへの即時送信のために disable_batch=True を設定
Traceloop.init(app_name="aroma_agents", disable_batch=True)

from google.adk.agents import SequentialAgent
# ... (以降のエージェント定義)

環境変数の設定（Instana Local Agent 用）

ローカルの Instana Agent にトレースを送信するための環境変数を設定します。
Google Gemini API を使用するためのキーもここで設定します。

# Google Gemini API Key
export GOOGLE_API_KEY=AIzaSy...

# Instana (OTLP/gRPC to Local Agent)
export TRACELOOP_BASE_URL=http://localhost:4317
export OTEL_EXPORTER_OTLP_INSECURE=true
export OTEL_RESOURCE_ATTRIBUTES="INSTANA_PLUGIN=genai"

# Optional: Traceloop のロギングとメトリクスを有効化
export TRACELOOP_LOGGING_ENABLED=true
export TRACELOOP_METRICS_ENABLED=true

# Optional: Suno API Key (音楽生成機能を使用する場合)
export SUNO_API_KEY="XXXXXXXXXXXXXX"

注意:

• TRACELOOP_BASE_URL は Instana Agent が稼働しているホストに向けてください。上記は同一マシン上で Agent が動いている場合の例です。
• SUNO_API_KEY は https://sunoapi.org/api-key から無料で取得できます。

Optional: モデルの変更

デフォルトでは gemini-2.0-flash が使用されますが、Aroma_Agents/utils/config.py でモデルを変更できます。

# Aroma_Agents/utils/config.py
DEFAULT_MODEL = "gemini-2.0-flash"  # または "gemini-1.5-pro" など

実行

設定が完了したら、Google ADK CLI を使用してエージェントを実行します。

adk run Aroma_Agents

正常に起動すると、以下のようなログが出力され、トレースがローカルエンドポイントに送信されていることが確認できます。

Traceloop exporting traces to http://localhost:4317 authenticating with bearer token

エージェントと対話を行うと、そのやり取りが自動的にトレースされます。

実行結果の例

(venv) % adk run Aroma_Agents
Log setup complete: /var/folders/.../agents_log/agent.20260206_125044.log
Running agent Aroma_Agents, type exit to exit.

[user]: 試験は終わったので、大変うれしいです。興奮で、なかなか眠れない

[intent_parser_agent]: {
  "mood": "happy",
  "context": "the exam is over",
  "preferences": "difficulty sleeping"
}

[compound_searcher_agent]: {
  "compound_candidates": [
    "Linalool",
    "Lavandulol",
    "Geraniol",
    "alpha-Pinene",
    "Myrcene"
  ]
}

[plant_mapper_agent]: {
  "matching_plants_or_products": [
    {
      "plant_name": "Lavender",
      "part_used": "Flowering Tops",
      "additional_info": "Lavender contains Linalool and Lavandulol..."
    },
    ...
  ]
}

[recommender_agent]: {
  "recommended_use": "To help you relax and sleep after your exams, consider using Lavender or Hops...",
  "scent_profile": "floral, herbal",
  "explanation": "The compounds Linalool, Lavandulol, and Myrcene..."
}

[mental_support_agent]: It's completely understandable that you're finding it hard to sleep...
✅ Saved audio to: audio_outputs/happy_exam_sleep_0.wav

[music_agent]: It sounds like you're feeling a mix of happiness and excitement...
🎵 Submitting music generation task for title: 'exam_success_sleep'...
✅ Task submitted successfully. Use this Task ID for status checks: 0131ea772a185b471bd5738e8df42cb9
...
✅ Music saved to: music_outputs/exam_success_sleep_1.mp3
✅ Music saved to: music_outputs/exam_success_sleep_2.mp3
🎉 Download task finished!

📈 Instana 側での確認

1. Instana の UI にアクセスします。

2. 「GenAI の可観測性」に移動します。
   

3. Traceloop.init で指定した app_name (例: aroma_agents) がサービスとして表示されていることを確認します。

4. サービス名（aroma_agents）をクリックします。

5. 「分析」タブに移動します。
   

6. 「Call の詳細」から、エージェントの思考プロセスやツール実行のウォーターフォールチャート（タイムライン）を確認できます。
   
   
   

各トレースをクリックすると、以下の情報が確認できます：

• エージェント間の呼び出しフロー
• 各エージェントの実行時間
• LLM モデルの呼び出し（例: gemini-2.0-flash）
• ツールの実行（音楽生成、TTS など）

📚 参考

• IBM Instana Documentation: Traceloop instrumentation
• Traceloop Documentation
• Google ADK Documentation
• Suno API Documentation
• Aroma Agents GitHub Repository