Google ADKトレースをAgent Analyticsに送信する
Python Google ADKはOpenTelemetry GenAIスパンを発行します。TypeScript @google/adk2.3.0およびJava com.google.adk:google-adk1.4.0がレガシーcall_llm属性を作成し、ガイドのエクスポータがそれらをエクスポートする前にgen_ai.*にコピーします。Go版のgoogle.golang.org/adkv1.6.1はスパンにgenerate_contentおよびexecute_toolを書き込み、OpenTelemetryログにメッセージテキストを保持します。エクスポータをAmplitudeに向けます。エージェントプロセスではAmplitude AI SDKは必要ありません。
このページでは、google-adk 2.13.0、@google/adk 2.3.0、google.golang.org/adk v1.6.1、およびJavaとKotlin 2.1.21からのcom.google.adk:google-adk 1.4.0について説明します。Gemini Developer API の呼び出しは、別のインストルメンテーションでスパンを作成できます。そのパスはOpenInferenceページです。 Amplitudeは、エクスポートしたスパンを保存します。 個人データがインフラストラクチャを離れる前に、そのデータを削除してください。エージェント分析のプライバシーモードを参照してください。
AIコーディングエージェントを使用した設定(推奨)
このプロンプトを、Cursor、Claude Code、Windsurf、GitHub Copilot、CodexなどのAIコーディングエージェントに貼り付けます。
Connect this Python Google ADK agent to Amplitude Agent Analytics with native OpenTelemetry.
Fetch https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/docs/integrations/google-adk.md
and follow "Part 2: Coding agent procedure".
If @amplitude/ai is installed, the same file is under node_modules/@amplitude/ai/docs/integrations/.
Also follow https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/docs/integrations/privacy.md
and scrub content before export.
Follow links in the guide. If your source isn't listed, start at https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/docs/integrations/README.md
変更を確認し、開始方法の手順に従って確認します。
必要な対応
- ADKプロセスを実行し、OpenTelemetryエクスポータをAmplitudeに向けます。コレクタはオプションです。 gRPCスパンをすでに収集している場合や、そこで属性をスクラブする場合は、それを使用してください。
- 必要なもの:
google-adk==2.13.0、AmplitudeプロジェクトのAPIキー、およびすべてのターンで変わらないADKセッションIDとプロダクト分析ユーザーID。 - プロトコル:OTLP over HTTP。 AmplitudeはprotobufとJSONを受け入れます。AmplitudeはgRPCを受け入れません。
- プライバシー:Amplitudeは、受信後にコンテンツを削除しません。エクスポートする前に、コンテンツ属性をマスクまたはドロップします。
エクスポート
プロセスがADKをインポートする前に、これらの変数を設定します。Pythonでは、ヘッダー値内のスペースは%20としてエンコードします。Authorization=の記述は変更しないでください。
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.amplitude.com/otlp/v1/traces
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20<project API key>"
OTEL_SERVICE_NAME=order-support
OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLY
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=true
EU地域のデータレジデンシーの場合はhttps://api.eu.amplitude.com/otlp/v1/tracesを使用します。
ADKのテレメトリスキーマをデフォルトのままにしておきます。 レガシーcall_llmスキーマはマップされません。SPAN_ONLYは、プロンプトと補完値をスパン属性に設定します。Amplitudeはスパンイベントを読み取ることはありません。 ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=falseおよびOTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=NO_CONTENT を使用した場合でも、セッション、ユーザー、エージェント、モデル、両方のトークン数、およびツール名は引き続き届きます。メッセージテキストとツール引数は届きません。
アイデンティティ
ADKは、モデルとエージェントのスパン上のセッションIDからgen_ai.conversation.idを書き込みます。ツールのスパンはこの値を取得しません。 スパンプロセッサは、ツールスパンを含むすべてのスパンで、user.id、gen_ai.agent.id、およびgen_ai.conversation.idを設定します。これがなければ、Amplitudeはツール呼び出しをtrace idの下に保存します。 nameエージェントはPythonの識別子である必要があります。プロダクトエージェントIDはgen_ai.agent.idです。
| 属性 | 値 |
|---|---|
gen_ai.conversation.id | ADKセッションID。 すべてのターンで同じ値を使用します。 |
user.id | プロダクト分析で既に使用されているユーザーID。Amplitudeは、欠落しているユーザーをunknownとして保存します。 |
gen_ai.agent.id | このエージェントの安定した名前。 Amplitudeはgen_ai.agent.nameを読み取りません。 |
引き継がれるもの
| ADKのスパン | Amplitudeイベント |
|---|---|
モデル呼び出し(generate_content) | [Agent] AI Response、さらに最後のアシスタントメッセージの後に続く新しいユーザーメッセージごとに[Agent] User Message |
ツール(execute_tool) | [Agent] Tool Call |
| エージェントとワークフローのスパン | [Agent] Span |
tool-loop の継続は、gen_ai.input.messages内の前のユーザーテキストを繰り返します。Amplitudeは、以前のユーザーメッセージを再度送信しません。 ツール出力は [Agent] Tool Outputです。
TypeScript
@google/adk 2.3.0はモデルスパンにcall_llmと名前を付け、プロンプトをgcp.vertex.agent.llm_requestに格納します。すべてのスパンで、user.id、gen_ai.agent.id、gen_ai.conversation.idを設定し、エクスポーターにおいて、レガシーblobをgen_ai.operation.name、gen_ai.input.messages、gen_ai.output.messages、およびgen_ai.tool.call.argumentsにコピーします。手順は、Google ADK連携ガイドに記載されています。
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=falseはセッション、ユーザー、エージェント、モデル名、両方のトークン数、およびツール名を保持します。メッセージテキストとツール引数は到着しません。モデルのスパンはcall_llmのままであるため、Amplitudeはそれを[Agent] Spanとして記録します。
Go
google.golang.org/adk v1.6.1は、モデル名と両方のトークン数を指定して、スパンにgenerate_contentとexecute_toolを書き込みます。メッセージテキストはOpenTelemetryログであり、Amplitudeはログを読み取らないため、ユーザーメッセージテキストと返信テキストは届きません。 すべてのスパンで、user.id、gen_ai.agent.id、gen_ai.conversation.idを設定し、エクスポータでgen_ai.tool.call.argumentsにgcp.vertex.agent.tool_call_argsをコピーします。手順は、Google ADK連携ガイドに記載されています。
Java
com.google.adk:google-adk 1.4.0はモデルスパンcall_llmに名前を付けます。ADKがロードされる前にOpenTelemetryを登録します。 すべてのスパンで、user.id、gen_ai.agent.id、gen_ai.conversation.idを設定し、call_llmをgenerate_contentに書き換え、gcp.vertex.agent.llm_request、gcp.vertex.agent.llm_response、gcp.vertex.agent.tool_call_argsをgen_ai.*キーにコピーします。手順は、Google ADK連携ガイドに記載されています。 そのエクスポータを使用すると、ユーザーメッセージのテキスト、ツール呼び出し、返信テキストが届きます。ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=falseは、セッション、ユーザー、エージェント、モデル名、両方のトークン数、およびツール名を保持します。メッセージテキストとツール引数は到着しません。エクスポータは空のリクエストを書き換えないため、モデルスパンはcall_llmのままとなり、Amplitudeはそれを[Agent] Spanとして記録します。
Kotlin
Kotlinは同じcom.google.adk:google-adk1.4.0ライブラリと同じエクスポータを使用しています。 Kotlin 2.1.21 の呼び出し元は、ユーザーメッセージテキスト、ツール呼び出し、返信テキストなど、Javaと同じスパンを生成しました。
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=falseはセッション、ユーザー、エージェント、モデル名、両方のトークン数、およびツール名を保持します。メッセージテキストとツール引数は到着しません。モデルのスパンはcall_llmのままであるため、Amplitudeはそれを[Agent] Spanとして記録します。
セッションを閉じる
[Agent] Session Endはオプションであり、推奨されます。ネイティブのADKエクスポートはこれを送信しません。 Amplitudeは、デフォルトで条件を満たすエージェントイベントなしで30分後にセッションを終了し、セッションごとのオーバーライドが設定されていない場合は、セッション開始から24時間後にセッションを終了します。最初の終了がカウントされます。セッションレコードとコンテンツベースのシグナルを含むエンリッチメントは、その終了後に一度実行されます。OpenTelemetryトランスレータは、スパンからidle-timeout属性を読み取ることはありません。セッションの終了方法を参照してください。
今すぐ始める
Google ADK連携ガイドに従ってください。 同じADKセッションIDを使用して2つのターンを送信し、ライブイベントで確認します。
- セッションIDはADKセッションIDであり、トレースIDではありません。
- ユーザーIDはプロダクト分析ユーザーであり、
unknownではありません。 - エージェントIDは
gen_ai.agent.idです。 - Python、TypeScript、Java、Kotlinでは、ターンには、ユーザーメッセージテキスト、ツール呼び出し、AIレスポンステキストが表示されます。また、モデル名と両方のトークン数も含まれます。Goでは、ターンにツール呼び出し、モデル名、および両方のトークン数が表示されます。ユーザーメッセージテキストと返信テキストは到着しません。これは、GoがOpenTelemetryログにそのテキストを保持しているためです。
- 2番目のターンでは、最初のユーザーメッセージは複製されません。
このガイドは、google-adk 2.13.0、@google/adk 2.3.0、google.golang.org/adk v1.6.1、1.4.0、およびJavaとKotlin 2.1.21から使用したcom.google.adk:google-adkに対して、2026年10月28日に最後検証されました。Google ADKは、その所有者の商標です。Amplitudeは、その所有者と提携していません。また、その所有者によって承認されていません。
これは役に立ちましたか?
For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.