Google ADK

Google ADK

Google ADK(Agent Development Kit)로 AI 에이전트를 만들고 있다면, 그 실행도 추적하고 싶겠죠. 통합은 OpenTelemetry를 통해 동작합니다. ADK가 이미 호출·에이전트·모델·도구에 대한 자체 OpenTelemetry 스팬을 만들어 내기 때문에, confident-trace가 그 스팬을 받아 프레임워크를 감싸지 않고도 Confident AI로 내보내 줘요.

출처: 문서

본문

개요

Google ADK(Agent Development Kit)는 AI 에이전트를 빌드·평가·배포하기 위한 Google의 오픈소스 프레임워크입니다.

이 통합은 OpenTelemetry로 동작해요. ADK는 이미 호출·에이전트·모델·도구에 대한 자체 OpenTelemetry 스팬을 만듭니다. Confident AI의 OpenTelemetry 네이티브 추적 SDK인 confident-trace가 그 스팬을 받아, 프레임워크를 감싸지 않고도 Confident AI로 내보내요.

ADK는 스팬을 공유 전역 OpenTelemetry tracer 프로바이더에 쓰는데, init()이 Confident AI exporter를 설치하는 곳이 바로 그 프로바이더예요. 앱이 자체 프로바이더를 구성한다면, ADK가 초기화되기 전에 그 프로바이더를 전역으로 등록하세요 — 기존 OpenTelemetry 프로바이더를 참고하세요.

ADK 밖에서(또는 도구 함수 안에서) google-genai를 직접 호출하고 있나요? 그 호출은 Google GenAI 프로바이더 통합이 추적해 Confident AI LLM 스팬으로 보여줘요. ADK를 통해 한 호출은 ADK 자체의 모델 스팬에 한 번만 기록되므로, 중복은 볼 수 없어요.

Runtime Requirements Setup
Python Python 3.10+, google-adk (tested with 2.8.0) Call init() before running the runner
TypeScript Not supported —

자동 계측

EU 리전 사용자는 OTEL 엔드포인트를 EU 버전으로 설정하세요. 그렇지 않으면 트레이스가 우리 US 서버로 보내집니다.

export CONFIDENT_OTEL_ENDPOINT="https://eu.otel.confident-ai.com/v1/traces"

의존성 설치

필요한 패키지를 설치하는 명령을 실행하세요.

pip install confident-trace google-adk

Confident AI 키 설정

Confident AI Project API key를 받아 환경 변수로 설정하거나, init()에 직접 전달하세요.

export CONFIDENT_API_KEY="<your-confident-api-key>"
export GOOGLE_API_KEY="<your-google-key>"

from confident_trace import init

init(api_key="<your-confident-api-key>")

Google ADK 계측

시작 시, 러너가 실행되기 전에 init()을 한 번 호출하세요. ADK 에이전트, 러너, 세션은 평소처럼 만들면 돼요.

import asyncio

from confident_trace import init, shutdown
from google.adk.agents import LlmAgent
from google.adk.runners import InMemoryRunner
from google.genai import types


async def main():
    init()
    runner = InMemoryRunner(
        app_name="my_app",
        agent=LlmAgent(
            name="my_agent",
            model="gemini-2.5-flash",
            description="A helpful assistant.",
            instruction="Answer questions concisely.",
        ),
    )
    session = await runner.session_service.create_session(
        app_name="my_app", user_id="user-42"
    )
    try:
        async for event in runner.run_async(
            user_id="user-42",
            session_id=session.id,
            new_message=types.Content(
                role="user", parts=[types.Part(text="What is OpenTelemetry?")]
            ),
        ):
            if event.content and event.content.parts:
                print(event.content.parts[0].text or "", end="")
        print()
    finally:
        shutdown()


asyncio.run(main())

한 번 초기화하고, 한 번 종료하세요. 장기 실행 서버에서는 시작 시 init()을, 정상 종료 시 활성 호출이 끝난 뒤 shutdown()을 호출하세요 — 요청마다 하지 마세요. 한 번 초기화를 참고하세요.

에이전트 실행

스크립트를 실행해 에이전트를 호출하세요.

python main.py

완료 ✅. Confident AI 프로젝트에서 Observatory를 열어 트레이스를 확인하세요.

트레이스가 안 보이면, 거의 항상 프로그램이 트레이스를 보낼 기회가 생기기 전에 종료됐기 때문이에요. 종료 전에 반드시 shutdown()(장기 실행 프로세스에선 flush())을 호출하세요 — 트러블슈팅 페이지를 참고하세요.

무엇이 포착되나

Google ADK 실행은 계층이 그대로 보존된 채 내보내져서, 각 호출을 에이전트·모델 호출·도구를 따라갈 수 있어요.

  • 호출 수명 주기 — 각 실행의 작업 이름, 타이밍, 상태, 세션 컨텍스트
  • 에이전트 실행 — 어떤 에이전트가 참여했고 어떤 순서로 실행됐는지
  • 모델 호출 — 요청·응답 콘텐츠, 모델 상세, 완료 사유, 토큰 사용량
  • 도구 호출 — 도구 이름과 그 입출력
  • 오류 — 실패한 작업이 트레이스에 오류 상태를 유지

ADK는 일부 메시지 콘텐츠를 스팬이 아니라 OpenTelemetry 로그 에 넣어요. confident-trace는 트레이스만 내보내므로, 콘텐츠가 예상보다 빈약해 보이면 ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS가 false로 설정되지 않았는지 확인하세요 — 그 변수(와 ADK 자체 텔레메트리 구성)가 ADK가 스팬에 무엇을 넣을지 제어하거든요.

트레이스 스팬 속성 설정

호출이 시작되기 전에 아는 속성을 추가하려면 트레이스 컨텍스트를 사용하세요. 추가 스팬은 만들지 않아요. runner.run_async()이 시작한 트레이스가 태그, 메타데이터, 사용자 ID, 고객 ID를 상속받습니다.

from confident_trace import init, trace_context
from google.genai import types

init()

message = types.Content(role="user", parts=[types.Part(text="Explain OpenTelemetry.")])

async with trace_context(
    tags=["support"],
    metadata={"release": "2026-09"},
    user_id="user-42",
    customer_id="customer-7",
):
    async for event in runner.run_async(
        user_id="user-42", session_id=session.id, new_message=message
    ):
        pass

각 ID와 함께 선택적 표시 이름을 설정하려면 사용자와 고객을, 지원되는 모든 트레이스 속성과 갱신 동작은 트레이스 컨텍스트를 참고하세요.

다중 턴 계측

Google ADK 엔트리포인트 호출 하나가 이미 하나의 대화 턴일 때는 turn()이 필요 없어요 — 통합이 그 턴의 트레이스를 자동으로 만들어 주거든요. 경계를 직접 정의하고 싶을 때, 예를 들어 두 번의 연속 Google ADK 호출을 하나의 턴으로 묶고 싶을 때 turn()을 사용하세요. 이후 턴에서 같은 스레드 ID를 재사용해 하나의 대화로 묶으면 돼요.

from confident_trace import init, turn
from google.genai import types

init()

async with turn("support-turn", thread_id="chat-42"):
    for prompt in ("Find the relevant account details.", "Summarize those details."):
        message = types.Content(role="user", parts=[types.Part(text=prompt)])
        async for event in runner.run_async(
            user_id="user-42", session_id=session.id, new_message=message
        ):
            pass

스레드 입출력, 턴 ID, 사용자 ID는 스레드를 참고하세요.

Google ADK 계측 비활성화

특정 통합만 활성화하려면 init()에 통합 식별자 목록을 전달하세요. Google ADK의 식별자는 Python에서 "google_adk"이고, 이를 빼면 이 통합이 비활성화돼요. 빈 목록은 모든 자동 계측을 비활성화합니다.

from confident_trace import init
init(instrumentations=())
# Use ("google_adk",) to opt in; omit "google_adk" to disable it.

이렇게 하면 Confident AI의 자동 instrumentor가 꺼져요. Google ADK는 여전히 자체 네이티브 OpenTelemetry 스팬을 만들 수 있습니다.

다음 단계

에이전트를 추적했으니, 더 깊이 들어가 볼까요.

Online Evals

트레이스와 스팬이 Confident AI로 수집되는 실시간으로 평가를 돌려 에이전트 품질을 모니터링하세요.

Threads

같은 ADK 세션의 호출을 스레드로 묶고, 전체 대화를 하나의 단위로 평가하세요.

더 알아보기

  • OpenInference — OpenInference 계측기로 스팬 만들기
  • Online Evals — 수집되는 트레이스·스팬을 실시간으로 평가