Google ADK 추적을 에이전트 분석으로 전송
Python Google ADK는 OpenTelemetry GenAI 스팬을 방출합니다. TypeScript @google/adk 2.3.0 및 Java com.google.adk:google-adk 1.4.0은 기존 call_llm 속성을 작성하며, 가이드의 내보내기 도구는 내보내기 전에 이를 gen_ai.*에 복사합니다. Go google.golang.org/adk v1.6.1은 generate_content 및 execute_tool을(를) 스팬에 기록하며 OpenTelemetry 로그에 메시지 텍스트를 유지합니다. Exporter를 Amplitude로 가리킵니다. 에이전트 프로세스에서 Amplitude AI SDK는 필요하지 않습니다.
이 페이지에서는 Java의 google-adk2.13.0, @google/adk 2.3.0, google.golang.org/adk v1.6.1 및 com.google.adk:google-adk 1.4.0과 Kotlin 2.1.21에 대해 설명합니다. 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를 가리키도록 설정하십시오. Collector는 선택 사항입니다. 이미 gRPC 스팬을 수집하고 있거나 해당 스팬에서 속성을 스크러빙할 때 이를 사용하십시오.
- 필요한 사항은
google-adk==2.13.0, Amplitude 프로젝트 API 키, 그리고 매 턴에 안정적인 ADK 세션 ID 및 product-analytics 사용자 ID입니다. - 프로토콜: HTTP 기반 OTLP. 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 |
도구 루프 연속은 gen_ai.input.messages 내부의 이전 사용자 텍스트를 반복합니다. Amplitude는 이전 사용자 메시지를 다시 표시하지 않습니다. 도구 출력은 [Agent] Tool Output입니다.
타입스크립트
@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을(를) 스팬에 기록합니다. Message text는 OpenTelemetry 로그이며, Amplitude는 로그를 읽지 않으므로 user-message 텍스트 및 reply 텍스트가 도착하지 않습니다. 모든 스팬에 user.id, gen_ai.agent.id 및 gen_ai.conversation.id을(를) 설정하고 Exporter에서 gcp.vertex.agent.tool_call_args을(를) gen_ai.tool.call.arguments에 복사하십시오. 단계는 Google ADK 연동 가이드에 나와 있습니다.
자바 프로그래밍 언어
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 연동 가이드에 나와 있습니다. 이 exporter를 사용하면 user-message 텍스트, tool 호출 및 reply 텍스트가 도착합니다. ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false는 세션, 사용자, 에이전트, 모델 이름, 두 토큰 수 및 도구 이름을 유지합니다. 메시지 텍스트와 도구 인수가 도착하지 않습니다. 내보내기는 빈 요청을 다시 작성하지 않으므로 모델 스팬이 그대로 call_llm 유지되고 Amplitude는 이를 [Agent] Span로 기록합니다.
Kotlin
Kotlin은 동일한 com.google.adk:google-adk 1.4.0 라이브러리와 동일한 익스포터를 사용합니다. Kotlin 2.1.21 호출자는 user-message 텍스트, tool 호출, reply 텍스트를 포함하여 Java와 동일한 스팬을 생성했습니다.
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false은(는) 세션, 사용자, 에이전트, 모델 이름, 두 토큰 수 및 도구 이름을 유지합니다. 메시지 텍스트와 도구 인수가 도착하지 않습니다. 모델 스팬은 call_llm로 유지되므로 Amplitude는 [Agent] Span로 기록합니다.
세션 닫기
[Agent] Session End 는 선택 사항이며 권장됩니다. 네이티브 ADK 익스포트는 이를 전송하지 않습니다. Amplitude는 기본적으로 적합한 에이전트 이벤트 없이 30분 후에 세션을 닫으며, 세션별 재정의가 설정되지 않은 경우 세션 시작 후 24시간 내에 세션을 닫습니다. 첫 번째 닫기가 유효한 닫기입니다. 세션 레코드와 콘텐츠 기반 신호를 포함한 Enrichment는 해당 닫기 이후 한 번 실행됩니다. OpenTelemetry 변환기는 스팬에서 idle-timeout 속성을 읽지 않습니다. 세션 닫기 방법을 참조하십시오.
시작하기
Google ADK 연동 가이드를 따르십시오. 동일한 ADK 세션 ID로 두 턴을 전송한 다음 라이브 이벤트에서 확인하십시오:
- 세션 ID는 ADK 세션 ID이며 추적 ID가 아닙니다.
- User ID는 product-analytics 사용자가 아니라
unknown입니다. - 에이전트 ID는
gen_ai.agent.id입니다. - Python, TypeScript, Java 및 Kotlin에서 turn은 사용자 메시지 텍스트, 도구 호출, AI 응답 텍스트와 함께 모델 이름 및 두 토큰 카운트를 표시합니다. Go에서 turn은 도구 호출, 모델 이름 및 두 토큰 카운트를 표시합니다. Go가 해당 텍스트를 OpenTelemetry 로그에 유지하기 때문에 사용자 메시지 텍스트와 회신 텍스트는 도착하지 않습니다.
- 두 번째 턴은 첫 번째 사용자 메시지를 복제하지 않습니다.
이 가이드는 2026년 10월 28일, Java의 google-adk 2.13.0, @google/adk 2.3.0, google.golang.org/adk v1.6.1, com.google.adk:google-adk 1.4.0 및 Kotlin 2.1.21을 기준으로 마지막으로 확인되었습니다. 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.