Google Gemini Enterprise 에이전트 플랫폼

Google Gemini Enterprise 에이전트 플랫폼

호스팅 에이전트 트레이스를 OpenTelemetry로 Confident AI에 내보내요.

출처: 문서

본문

개요

Gemini Enterprise Agent Platform은 Google Cloud의 에이전트 구축·배포 플랫폼이에요. 관리형 Agent Runtime(이전의 Vertex AI Agent Engine)이 Google ADK와 다른 프레임워크로 만든 에이전트를 호스팅해요.

에이전트 프로세스에서 OTLP 트레이스 exporter를 구성해서 호스팅 애플리케이션이 생성한 OpenTelemetry 스팬을 Confident AI로 보내요. 이 가이드는 인스트루먼테이션과 exporter를 여러분이 제어하는 커스텀 에이전트를 다뤄요.

Gemini Enterprise Agent Platform은 개발자 플랫폼이에요. Gemini Enterprise 앱은 별개의 직원 대상 제품이에요. 이 가이드는 Gemini Enterprise 앱의 모든 에이전트·워크플로에 트레이싱을 구성하지 않아요. Google 제품 FAQ를 보세요.

시작 전에

  • 시작과 종속성을 제어할 수 있는 Agent Runtime에 배포된 에이전트.
  • OpenTelemetry 인스트루먼테이션과 OTLP/HTTP protobuf 트레이스 exporter.
  • Confident AI의 프로젝트 API 키.
  • 해당하는 VPC나 Agent Gateway egress 구성을 포함해 Confident AI로의 아웃바운드 HTTPS 접근.

트레이스 내보내기 구성하기

애플리케이션 트레이싱 구성하기

애플리케이션 시작 중에 에이전트의 인스트루먼테이션과 OTLP 트레이스 exporter를 초기화해요. 커스텀 에이전트 객체에서는 활성 exporter를 직렬화하는 대신 배포의 설정 수명 주기에서 런타임 전용 텔레메트리 객체를 초기화하세요. 컨테이너 배포는 애플리케이션 엔트리 포인트에서 트레이싱을 초기화할 수 있어요.

Google ADK를 쓰고 인스트루먼테이션이 필요하다면 Google ADK 통합을 따르세요. 애플리케이션이 이미 OpenTelemetry 스팬을 내보낸다면 프로바이더를 재사용하고 OpenTelemetry 설정으로 exporter를 구성하세요.

Google의 GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY 설정은 Cloud Trace로 가는 내장 텔레메트리 경로를 켜요. 트레이스를 Confident AI로 보내는 스위치는 아니에요. 이 가이드는 애플리케이션 구성 exporter를 써요. Google의 관리형 텔레메트리 설정에 엔드포인트 변수만 추가하는 것은 그 설정을 대체하는 검증된 방법이 아니에요.

Confident AI 목적지 설정하기

애플리케이션의 OTLP 트레이스 exporter에 다음 값을 구성해요:

Setting Value
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT https://otel.confident-ai.com/v1/traces
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL http/protobuf
OTEL_EXPORTER_OTLP_TRACES_HEADERS x-confident-api-key=YOUR_CONFIDENT_PROJECT_KEY
OTEL_SERVICE_NAME A stable name for your agent

EU 프로젝트라면 https://eu.otel.confident-ai.com/v1/traces를 써요. 셀프호스팅 배포라면 전체 OTLP/HTTP 트레이스 URL을 써요. 키는 배포의 시크릿 구성에 저장하세요.

exporter를 초기화하기 전에 배포된 에이전트의 환경에 이 값을 설정하세요. 프레임워크가 exporter 엔드포인트나 인증을 명시적으로 제공한다면 그 구성을 직접 업데이트해요. Cloud Trace용 Google Cloud 인증이 Confident AI 프로젝트 키 헤더를 대체하지는 않아요.

배포하고 검증하기

업데이트된 에이전트를 배포하고 한 번 호출해요. Confident AI 프로젝트에서 Observatory를 열고 들어온 트레이스, 스팬 계층, 모델 호출, 툴 연산을 확인하세요. 배치 내보내기가 완료되게 하고 정상 종료 중 대기 중인 스팬을 플러시하세요.

무엇이 캡처되나요

Confident AI는 애플리케이션의 인스트루먼테이션이 내보내는 스팬을 받아요. 에이전트 실행, 모델 호출, 툴, 커스텀 연산이 포함될 수 있어요. 이 설정은 Google 관리형 플랫폼 텔레메트리를 전부 내보내거나 과거 Cloud Trace 데이터를 가져오지는 않아요.

최종 사용자와 그 계정을 식별하려면 트레이스 수준 confident.trace.user.id와 confident.trace.customer.id 속성을 설정하세요. 표시 이름과 레거시 *_id 별칭은 수동 인스트루먼테이션을 보세요.

프롬프트·응답 캡처는 인스트루먼테이션이 제어해요. Google의 내장 트레이싱 문서에는 콘텐츠를 로그 이벤트로 기록하는 모드가 포함되어 있는데, 트레이스 전용 exporter는 그 별도 로그를 전달하지 않아요. 인스트루먼테이션이 지원하는 곳에는 스팬에 콘텐츠를 구성하고, 지원되는 속성을 확인하세요.

문제 해결

  • 트레이스가 Cloud Trace에만 나타남: 애플리케이션 exporter가 Confident AI를 가리키고 Google 기본 텔레메트리 초기화로 대체되지 않았는지 확인하세요.
  • 트레이스 없음: 에이전트가 스팬을 내보내고 exporter가 로컬 노트북이 아니라 배포된 프로세스에서 초기화됐는지 확인하세요.
  • 내보내기 연결 오류: 선택한 US, EU, 셀프호스팅 엔드포인트로의 런타임 egress 접근을 확인하세요.
  • 메시지 누락: 콘텐츠 캡처가 비활성화됐거나 스팬 속성이 아닌 별도 로그로 내보내지지 않는지 확인하세요.

내장 텔레메트리와 제품 이름은 Google의 Agent Runtime 트레이싱 문서와 릴리스 노트를 보세요.

더 알아보기