데이터 에이전트의 통합 패턴

이 페이지에서는 데이터 에이전트 환경을 애플리케이션에 삽입하기 위한 통합 패턴을 설명합니다. 이러한 패턴은 내장된 채팅 구성요소부터 조정된 멀티 에이전트 시스템에 이르기까지 복잡성이 다양합니다.

이 가이드는 생성형 AI 애플리케이션을 설계하는 클라우드 설계자와 데이터 엔지니어를 대상으로 합니다. Google Cloud 개념, Identity and Access Management(IAM), REST API에 대한 기본적인 이해가 필요합니다. 또한 애플리케이션에서 사용하는 데이터 소스의 아키텍처를 잘 알고 있어야 합니다.

통합 패턴 개요

이 가이드는 다음과 같은 기본 트랙으로 구성되어 있으며, 각 트랙은 시작점을 기반으로 합니다.

  • Looker 트랙: Looker 임베딩, Looker API 또는 대화형 분석 API를 통해 채팅 기능을 제공하려면 이 트랙을 선택합니다.
  • BigQuery 및 데이터베이스 트랙: BigQuery, 데이터 스튜디오 또는 지원되는 운영 데이터베이스를 사용하는 커스텀 애플리케이션을 빌드하는 경우 이 트랙을 선택합니다.

다음 표에는 사용 가능한 통합 패턴이 요약되어 있습니다.

통합 패턴 설명 데이터 소스
Looker iframe 삽입 최소한의 코드가 필요한 애플리케이션에 표준 채팅 인터페이스를 추가합니다. Looker
Looker API 및 SDK 인증에 Looker API를 사용하는 커스텀 채팅 인터페이스를 빌드합니다. Looker
대화형 분석 API(Looker 소스) 여러 플랫폼과 멀티 에이전트 시스템에서 작동하는 Google Cloud 리소스로 Looker 데이터 에이전트를 관리합니다. Looker
Direct API(단일 에이전트) 텍스트-답변 흐름에 직접 API 통합을 사용합니다. BigQuery, 데이터베이스, Looker
직접 API(오케스트레이터) 함수 호출을 사용하여 API와 다른 도구 간에 쿼리를 라우팅합니다. BigQuery, 데이터베이스, Looker
BigQueryToolset를 사용하는 ADK(스키마 기반) ask_data_insights 도구를 사용하여 테이블 참조에서 유용한 정보를 빠르게 생성합니다. BigQuery
DataAgentToolset를 사용하는 ADK(관리형) ask_data_agent 도구를 사용하여 일관된 동작을 보장하는 사전 구성된 데이터 에이전트를 쿼리합니다. BigQuery, 데이터베이스, Looker
ADK(맞춤 스트리밍) 커스텀 에이전트 클래스를 사용하여 차트 및 SQL의 실시간 스트리밍을 지원합니다. BigQuery, 데이터베이스, Looker
McpToolset 또는 ToolboxToolset를 사용하는 MCP 모델 컨텍스트 프로토콜(MCP)을 사용하는 데이터 도구에 애플리케이션을 연결합니다. BigQuery, Looker
대화형 분석 API 원격 MCP 서버 서드 파티 AI 플랫폼 및 Google 관리 플랫폼(예: Gemini Enterprise)의 루트 에이전트가 Google Cloud전반에서 전문 데이터 에이전트를 검색하고 이들과 통신할 수 있는 통합된 보안 게이트웨이를 제공합니다. BigQuery, 데이터베이스, Looker
A2A 프로토콜 서로 다른 시스템에서 작동하는 전문 에이전트 간의 안전한 공동작업을 지원합니다. 프레임워크 종속 항목

Looker 통합 옵션

Looker를 사용하는 경우 다음 패턴을 통해 사용자에게 Looker 대화형 분석을 제공할 수 있습니다.

  • iframe으로 삽입: 표준 채팅 인터페이스를 기존 애플리케이션에 추가하는 로우 코드 패턴입니다.
  • Looker API 및 SDK로 빌드: Looker 인증 및 에이전트 관리를 통해 커스텀 프런트엔드를 빌드할 수 있는 유연한 접근 방식입니다.
  • 대화형 분석 API 사용: API와 직접 통합하여 여러 Google Cloud 표시 경로에서 데이터 에이전트를 사용할 수 있습니다.

Looker 통합 패턴 요약

다음 표에는 Looker의 기본 통합 패턴이 요약되어 있습니다.

패턴 용도 장점 고려사항
iframe으로 삽입: 표준 Looker 채팅 환경을 애플리케이션에 빠르게 추가할 수 있는 로우 코드 방식입니다. 최소한의 커스텀 개발로 프로덕션에 즉시 사용 가능한 대화형 분석 환경이 필요한 팀
  • 구현하는 데 필요한 코드가 최소화됩니다.
  • 기존 Looker 보안 모델을 자동으로 시행합니다.
  • 별도의 Google Cloud 인증이 필요하지 않습니다.
  • iframe 수명 주기 및 이벤트 전달을 관리하여 개발을 가속화하는 Looker Embed SDK를 지원합니다.
  • 제한된 UI 맞춤설정을 제공하며 표준 Looker 채팅 사용자 인터페이스에 따라 달라집니다.
  • Looker 인스턴스는 Looker에서 호스팅되어야 합니다.
Looker API 및 SDK로 빌드: Looker 내에서 인증 및 에이전트 관리를 유지하면서 커스텀 채팅 인터페이스를 빌드하는 유연한 접근 방식입니다. 커스텀 채팅 사용자 환경이 필요하지만 Looker 생태계 내에서 사용자 인증 및 에이전트 관리를 유지하려는 팀 이 패턴은 이미 Looker 임베딩 또는 API를 사용하는 애플리케이션에 적합합니다.
  • 단일 인증 레이어와 사용자 인터페이스에 대한 완전한 제어 기능을 제공합니다.
  • 기존 Looker 고객의 아키텍처를 간소화합니다.
  • Looker 시맨틱 레이어를 사용하여 쿼리 정확도를 개선합니다.
  • 별도의 Google Cloud 인증이 필요하지 않습니다.
  • Looker API 개발 전문 지식이 필요합니다.
  • Looker 데이터 소스로 제한됩니다.
  • 에이전트는 Looker 내에서 관리되며 다른 Google Cloud 서비스로 이식할 수 없습니다.
대화형 분석 API 사용: API와 직접 통합하여 에이전트를 클라우드 수준 리소스로 관리합니다. 데이터 에이전트에 크로스 플랫폼 이동성이 필요한 Looker 고객
  • 데이터 에이전트를 모든 Google Cloud 표시 경로에서 이식할 수 있도록 합니다.
  • IAM에서 중앙 집중식으로 관리됩니다.
  • 데이터 에이전트를 ADK 또는 MCP 워크플로에 통합할 수 있습니다.
  • Google Cloud 및 Looker 인증을 포함한 전체 통합 스택을 관리해야 합니다.
  • 데이터 에이전트는 Looker 사용자 인터페이스와 별개로 관리됩니다.

iframe으로 삽입

대화형 분석을 iframe으로 삽입하여 Looker UI 외부에서 채팅 환경을 제공할 수 있습니다. 이 패턴은 커스텀 UI 개발, 백엔드 조정, API 상태 관리가 필요 없는 대화형 분석을 제공하는 직접적인 방법입니다. 이 패턴을 사용하려면 애플리케이션에 사전 형식화된 URL을 추가합니다.

Looker Embed SDK는 보안 URL 생성, iframe 수명 주기 관리, 호스트 애플리케이션과 iframe 간의 JavaScript 이벤트 전달과 같은 작업을 관리하는 도구를 제공합니다. 미리 형식이 지정된 URL을 애플리케이션에 추가하여 에이전트 페이지, 대화 페이지 또는 특정 대화를 삽입할 수 있습니다.

삽입된 콘텐츠에 다음 인증 방법을 사용할 수 있습니다.

  • 비공개 삽입: 기존 Looker 사용자 인증 정보로 사용자를 인증합니다. 삽입 URL을 iframe 소스로 설정하면 사용자가 Looker 계정으로 로그인합니다. 이 메서드는 추가 IAM 구성이나 토큰 매핑 없이 기존 역할, 콘텐츠 액세스, 데이터 수준 권한(예: 액세스 필터 또는 액세스 권한 부여)을 자동으로 적용합니다.
  • 서명된 삽입: 싱글 사인온(SSO)을 사용하여 애플리케이션을 통해 사용자를 인증합니다. 대화형 분석 콘텐츠 경로가 포함된 서명된 URL을 구성하여 부여할 권한을 동적으로 정확하게 지정할 수 있습니다.

Looker API 및 SDK로 빌드

채팅 환경을 더 유연하게 사용하려면 Looker API의 ConversationalAnalytics 메서드를 사용하거나 Looker SDK를 사용하여 커스텀 애플리케이션을 빌드하면 됩니다. 이 접근 방식을 사용하면 Looker 엔드포인트와 직접 통신하는 커스텀 프런트엔드를 빌드할 수 있습니다.

Looker API와 통합하면 다음과 같은 이점이 있습니다.

  • Looker로 인증만 관리합니다. 대화형 분석 API로 별도로 인증할 필요가 없습니다.
  • 이미 Looker 임베딩 또는 API를 사용하는 애플리케이션의 경우 이 패턴은 보조 인증 메커니즘을 피하고 외부 데이터 에이전트를 관리할 필요가 없으므로 프로젝트 아키텍처를 간소화합니다.
  • 채팅 인터페이스, 대화 흐름, 애플리케이션이 결과(예: 차트, 표)를 렌더링하는 방식을 완전히 제어할 수 있습니다.

참조 구현은 GitHub의 ConversationalAnalytics 메서드를 사용하는 Looker API 가이드를 참고하세요.

Looker 데이터와 함께 대화형 분석 API 사용

다음 작업을 수행해야 하는 경우 geminidataanalytics.googleapis.com에서 대화형 분석 API와 직접 통합할 수 있습니다.

  • 커스텀 웹 애플리케이션, Google Chat, Gemini Enterprise와 같은 여러 Google Cloud 표시 경로에서 동일한 데이터 에이전트를 공유합니다.
  • 단일 멀티 에이전트 시스템에서 Looker 데이터 소스를 BigQuery 또는 운영 데이터베이스 소스와 결합합니다.
  • Looker 권한 모델이 아닌 IAM에 의거하여 제어되는 클라우드 수준 리소스로 데이터 에이전트를 관리합니다.

Conversational Analytics API의 일반적인 아키텍처 패턴에 대한 자세한 내용은 BigQuery 및 데이터베이스 통합 옵션을 참조하세요.

BigQuery, 데이터 스튜디오, 데이터베이스 통합 옵션

이 섹션에서는 BigQuery, 데이터 스튜디오 또는 지원되는 Google Cloud 운영 데이터베이스를 사용하여 Conversational Analytics API로 커스텀 환경을 빌드하는 애플리케이션의 아키텍처 패턴을 설명합니다.

Looker 데이터 소스와 함께 대화형 분석 API를 사용하는 경우 이 섹션에 설명된 패턴이 통합에도 적용됩니다.

대화형 분석 API는 데이터와 상호작용하기 위한 다음과 같은 기본 메서드를 제공합니다.

  • chat 메서드: BigQuery, Looker, 데이터 스튜디오, 운영 데이터베이스를 지원합니다.
  • queryData 메서드: AlloyDB, Spanner용 GoogleSQL, MySQL용 Cloud SQL, PostgreSQL용 Cloud SQL과 같은 운영 데이터베이스를 지원합니다.

커스텀 애플리케이션을 빌드할 때 다음 통합 패턴 중 하나 이상을 사용할 수 있습니다.

  • 직접 API 통합: 가장 유연하지만 인증, 대화 관리, 대답 파싱을 위한 인프라를 빌드해야 하는 커스텀 접근 방식입니다.
  • 프레임워크 기반 조정(ADK): 멀티 에이전트 라우팅, 도구 실행, 상태 관리에 에이전트 개발 키트(ADK)를 사용하는 접근 방식입니다.
  • 수직 통합(MCP): 모델 컨텍스트 프로토콜(MCP)을 사용하여 다양한 환경에서 AI 애플리케이션을 도구 및 데이터 소스에 연결하는 일관된 방법을 제공하는 접근 방식입니다.
  • 수평 조정(A2A): Agent-to-Agent(A2A) 프로토콜을 사용하여 서로 다른 시스템의 전문 에이전트가 커스텀 통합 코드 없이 안전하게 공동작업할 수 있도록 하는 접근 방식입니다.

BigQuery 및 데이터베이스 통합 패턴 요약

다음 표에는 BigQuery 및 운영 데이터베이스의 특정 구현 패턴이 요약되어 있습니다.

패턴 용도 장점 고려사항
단일 에이전트 통합(직접 API): 애플리케이션이 API를 직접 호출하여 데이터 소스에서 인사이트를 반환하는 패턴입니다. 모든 API 호출을 직접 제어해야 하는 단일 에이전트 애플리케이션, 프로토타입 또는 마이크로서비스
  • 프레임워크 종속 항목 없이 세밀한 제어를 제공합니다.
  • 단일 에이전트 사용 사례에 가장 간단한 아키텍처를 제공합니다.
  • 스테이트풀(Stateful) 모드와 스테이트리스(Stateless) 모드를 모두 지원합니다.
  • 인증, 상태 관리, 응답 파싱, 오류 처리, 스트리밍, 배포를 위한 모든 인프라를 빌드해야 합니다.
  • 멀티 에이전트 시나리오에 적합하지 않습니다.
커스텀 조정자(직접 API): 루트 에이전트와 함수 호출을 사용하여 대화형 분석 API와 다른 도구 또는 서비스 간에 쿼리를 라우팅하는 패턴입니다. 단일 대화 흐름에서 데이터 쿼리를 이메일이나 문서와 같은 다른 작업과 결합하는 애플리케이션
  • 프레임워크 종속 항목 없이 최대 수준의 조정 제어 기능을 제공합니다.
  • 모델이 도구 간에 라우팅하는 방식을 정확하게 정의할 수 있습니다.
  • 모든 Gemini 모델에서 작동합니다.
  • 도구 정의, 대화 루프, 멀티턴 상태, 오류 처리, 배포를 수동으로 관리해야 합니다.
  • ADK와 같은 프레임워크를 사용하는 것에 비해 개발 오버헤드가 부담스러울 수 있습니다.
BigQueryToolset(ADK)를 사용한 스키마 기반 통합: 테이블 참조를 사용하여 데이터 인사이트를 빠르게 반환하는 패턴입니다. 신속한 프로토타입 제작, 데이터 거버넌스가 덜 중요한 내부 도구, 데이터 인사이트가 ADK 에이전트의 여러 기능 중 하나인 시나리오
  • ADK 프레임워크 내에서 가장 빠른 통합 경로를 제공합니다.
  • 데이터 에이전트 사전 구성이 필요하지 않습니다.
  • 데이터베이스 테이블 이름으로 직접 작업합니다.
  • 시맨틱 거버넌스가 부족하고 스키마 추론에서만 SQL을 생성합니다.
  • API 수준에서 스테이트리스(Stateless) 모드로 작동합니다.
  • 텍스트 전용 답변을 제공하며 차트는 지원하지 않습니다.
DataAgentToolset(ADK)를 사용한 제어된 통합: 에이전트 ID를 참조하여 사전 구성된 데이터 에이전트를 쿼리하는 패턴입니다. 일관된 데이터 액세스가 필요한 프로덕션 애플리케이션 또는 데이터 에이전트가 신뢰할 수 있고 재사용 가능한 구성요소인 멀티 에이전트 시스템
  • 모든 소비자에게 시맨틱 거버넌스와 일관된 동작을 제공합니다.
  • 확인된 쿼리와 비즈니스 용어집을 사용하여 정확성을 개선합니다.
  • 데이터 에이전트를 ADK, MCP, 직접 API 통합 전반에서 재사용할 수 있습니다.
  • 데이터 에이전트 리소스를 사전 구성해야 합니다.
  • API 수준에서 스테이트리스(Stateless) 모드로 작동합니다.
  • 텍스트 전용 답변을 반환하며 차트는 지원하지 않습니다.
커스텀 하위 에이전트(ADK): 커스텀 에이전트 클래스를 사용하여 API에 직접 연결하고 데이터 청크를 사용자에게 다시 스트리밍하는 패턴입니다. 짧은 응답 지연 시간이 우선순위인 사용자 대상 애플리케이션 또는 데이터 검색이 다운스트림 에이전트에 피드를 제공하는 멀티 에이전트 파이프라인
  • 실시간 스트리밍 피드백을 제공합니다.
  • 차트, 표, SQL과 같은 모든 대답 유형에 액세스합니다.
  • 세션 상태를 통해 다른 ADK 에이전트와 구성 가능
  • 커스텀 ADK 에이전트 클래스를 빌드하려면 더 많은 개발 노력이 필요합니다.
  • 스트리밍 연결 및 응답 파싱을 직접 관리해야 합니다.
모델 컨텍스트 프로토콜(MCP): 개방형 표준을 사용하여 다양한 환경의 데이터 소스 및 도구에 AI 애플리케이션을 연결하는 패턴입니다. 여러 AI 클라이언트와 IDE에서 도구 상호 운용성이 필요한 조직 또는 ADK 프레임워크, IDE, 커스텀 애플리케이션에서 동일한 데이터 도구에 액세스해야 하는 팀
  • 모든 MCP 호환 클라이언트와 작동하는 범용 도구 표준을 사용합니다.
  • 소비자 애플리케이션에서 도구 구현을 분리합니다.
  • Google Cloud MCP 서버와 같은 관리형 서버 옵션을 제공합니다.
  • 도구 상자 서버에 추가 인프라 레이어가 필요합니다.
  • ADK 도구 모음보다 느슨한 통합을 제공합니다.
  • MCP 도구 상자의 진화하는 생태계에 따라 다릅니다.
  • 멀티턴 상태를 외부에서 관리해야 하는 스테이트리스(Stateless) 모드에서 작동합니다.
에이전트 간(A2A): 커스텀 통합 코드 없이도 서로 다른 시스템의 전문 에이전트가 안전하게 협업할 수 있도록 지원하는 개방형 표준인 A2A 프로토콜을 사용하는 패턴입니다. 중앙 라우팅 에이전트가 서로 다른 시스템 또는 네트워크에서 작동하는 데이터 에이전트에 작업을 위임해야 하는 고도로 분산된 엔터프라이즈 환경
  • 서로 다른 프레임워크 간에 커스텀 통합 코드를 작성할 필요성이 줄어듭니다.
  • 원활한 크로스 플랫폼 상호 운용성을 보장합니다.
  • 안전하고 표준화된 기능 검색을 제공합니다.
  • 내부 하위 에이전트에 비해 약간의 네트워크 지연 시간이 발생합니다.
  • A2A 서버 설정을 구성해야 합니다.

API 직접 통합

직접 API 통합을 사용하면 애플리케이션의 로직과 아키텍처를 세부적으로 제어할 수 있지만 지원 인프라를 빌드해야 합니다. 이 접근 방식을 사용하면 인증, 대화 관리, 응답 파싱, 배포와 같은 작업을 직접 처리해야 합니다.

이 섹션에서는 다음 내용에 대해 설명합니다.

  • 단일 에이전트 통합: 애플리케이션이 대화형 분석 API를 직접 호출하여 데이터 소스에서 인사이트를 반환하는 패턴입니다.
  • 맞춤 조정자 통합: 루트 에이전트와 함수 호출을 사용하여 대화형 분석 API 간에 쿼리를 라우팅하는 고급 패턴입니다.

단일 에이전트 통합

단일 에이전트 통합을 사용하면 백엔드가 REST 또는 클라이언트 라이브러리를 사용하여 대화형 분석 API를 직접 호출하고 사용자의 쿼리와 컨텍스트를 전달합니다. 이 패턴은 간단한 텍스트-답변 흐름을 사용하는 웹 앱, 내부 채팅 도구, 마이크로서비스와 같이 복잡성이 낮은 애플리케이션에 적합합니다. 이 접근 방식은 프로토타입 제작 및 개념 증명 작업에도 사용할 수 있습니다.

이 패턴은 Google에서 대화 기록을 관리하는 스테이트풀(Stateful) 채팅과 애플리케이션에서 기록을 관리하는 스테이트리스(Stateless) 채팅을 모두 지원합니다.

참조 구현은 GitHub의 대화형 분석 API 빠른 시작 또는 대화형 분석 API 핵심 데모를 참고하세요.

커스텀 조정자 통합

이 접근 방식에서는 애플리케이션의 기본 진입점 및 조정자 역할을 하는 루트 에이전트를 빌드합니다. 루트 에이전트는 함수 호출을 통해 도구가 장착된 표준 Gemini 모델을 사용합니다. 사용자가 데이터 관련 질문을 하면 루트 에이전트가 대화형 분석 API에 도구 호출을 전송하고 결과를 수신한 후 추론을 계속하거나 다른 도구를 다운스트림으로 호출할 수 있습니다.

함수 호출에는 다음 단계가 포함됩니다.

  1. 선언: 파라미터 정의를 포함하는 FunctionDeclaration 객체로 도구 스키마를 정의합니다.
  2. 호출: 모델은 함수 이름과 인수가 포함된 구조화된 functionCall 메시지를 반환합니다.
  3. 실행: 애플리케이션이 API 호출을 실행하고 FunctionResponse 메시지로 결과를 반환합니다.
  4. 합성: Gemini 모델은 결과를 사용하여 최종 답변을 생성하거나 다음 작업을 결정합니다.

이 접근 방식은 사용자가 다른 작업과 함께 데이터 인사이트를 요청할 수 있는 애플리케이션에 적합합니다. 예를 들어 사용자가 에이전트에게 '판매를 보여주고 영업팀에 이메일 초안을 작성해 줘'라고 요청할 수 있습니다. 루트 에이전트는 데이터 질문을 대화형 분석 API로 라우팅하고 데이터가 아닌 작업에는 다른 도구를 사용할 수 있습니다.

참조 구현은 GitHub의 대화형 분석 API 핵심 데모에서 orchestrate 또는 multimodal 페이지를 참고하세요.

프레임워크 기반 조정(ADK)

에이전트 개발 키트(ADK)는 멀티 에이전트 라우팅, 도구 실행, 상태 관리의 복잡성을 관리하는 AI 에이전트를 빌드하기 위한 코드 중심 프레임워크입니다. ADK 프레임워크는 Gemini Enterprise를 구동하는 프레임워크와 동일합니다.

ADK를 사용하면 대화형 분석 API를 다른 도구 및 에이전트와 연결하여 복잡한 작업을 수행할 수 있습니다.

이 섹션에서는 다음 내용에 대해 설명합니다.

  • 스키마 기반 통합: BigQueryToolset 도구 모음의 ask_data_insights 도구를 사용하여 BigQuery 테이블 참조에서 데이터 인사이트를 반환하는 패턴입니다.
  • 관리형 통합: DataAgentToolset 도구 모음의 ask_data_agent 도구를 사용하여 에이전트 ID를 참조하여 사전 구성된 데이터 에이전트를 쿼리하는 패턴입니다.
  • 커스텀 하위 에이전트를 사용한 고급 UX 통합: 커스텀 하위 에이전트 구성요소를 사용하여 Conversational Analytics API에 직접 연결하고 데이터 청크를 사용자에게 비동기식으로 다시 스트리밍하는 패턴입니다.

BigQueryToolset를 사용한 스키마 기반 통합

ADK 프레임워크의 BigQueryToolset 도구 모음에는 사전 빌드된 ask_data_insights 도구가 포함되어 있습니다. 이 도구를 사용하려면 테이블 이름과 사용자의 질문을 도구에 전달합니다. 그러면 도구는 인라인 컨텍스트를 사용하여 대화형 분석 API를 호출합니다.

도구를 호출하면 지정된 BigQuery 테이블 참조가 포함된 스테이트리스(Stateless) 요청이 대화형 분석 API로 전송됩니다. API는 데이터베이스 스키마를 추론하고, SQL 쿼리를 생성 및 실행하고, 텍스트 답변을 반환합니다. 그런 다음 결과가 도구 응답으로 ADK 에이전트에 다시 전달됩니다.

이 패턴은 에이전트에 대화형 분석을 빠르게 추가하는 효과적인 방법입니다. 하지만 API 호출은 스테이트리스(Stateless)이고 거버넌스가 없기 때문에 API는 시맨틱 가드레일 없이 테이블 스키마에 전적으로 기반한 SQL을 생성합니다. 이 패턴은 배포 속도가 빠르지만 이름 지정 규칙, 비즈니스 로직 또는 액세스 제어가 적용되는 프로덕션 비즈니스 로직에는 더 위험합니다.

DataAgentToolset와의 관리형 통합

ADK 프레임워크의 DataAgentToolset 도구 모음은 사전 구성된 데이터 에이전트를 ID로 참조하는 사전 빌드된 통합을 제공합니다. ADK 에이전트는 사용자의 질문을 ask_data_agent 도구에 전달하고, 이 도구는 지정된 데이터 에이전트 컨텍스트를 사용하여 대화형 분석 API를 호출합니다.

Conversational Analytics API를 사용하거나 Google Cloud 콘솔의 에이전트 카탈로그를 통해 프로그래매틱 방식으로 데이터 에이전트를 만들 수 있습니다. 데이터 에이전트에는 다음 구성요소가 포함되어 있습니다.

  • 지식 소스: 에이전트가 쿼리할 수 있는 테이블, 뷰 또는 사용자 정의 함수(UDF)
  • 구조화된 컨텍스트: 에이전트가 기본 데이터를 이해하는 데 도움이 되는 테이블 및 열에 대한 설명
  • 요청 사항: 에이전트가 데이터 소스를 해석하고 쿼리하는 데 도움이 되는 추가 안내입니다.
  • 검증된 쿼리: 일반적인 질문의 예시로 사용되는 사전 검증된 SQL 쿼리
  • 용어집: 에이전트가 분야별 언어를 이해하는 데 도움이 되는 비즈니스 용어 정의

에이전트 카탈로그를 통해 에이전트를 만드는 방법에 관한 자세한 가이드는 BigQuery의 대화형 분석 Codelab을 참조하세요.

에이전트는 관리되는 단위로 정의되므로 이를 호출하는 애플리케이션이나 하위 에이전트에 관계없이 동일한 신뢰할 수 있는 로직, 컨텍스트, 가드레일을 사용합니다.

커스텀 하위 에이전트를 사용한 고급 UX 통합

BigQueryToolset 및 DataAgentToolset 도구 모음은 API 요청 처리가 완료될 때까지 사용자에게 결과를 반환하지 않습니다. ADK 프레임워크는 API를 완료될 때까지 응답을 차단하는 도구로 취급하므로, 실행 시간이 긴 쿼리는 사용자에게 피드백을 제공하지 않을 수 있습니다.

응답 지연 시간이 짧은 것이 우선순위이거나 데이터 검색이 다운스트림 에이전트에 피드를 제공하는 애플리케이션의 대안으로, 대화형 분석 API에 직접 연결하고 데이터를 청크 단위로 사용자에게 비동기식으로 스트리밍하는 커스텀 ADK 에이전트 클래스를 빌드할 수 있습니다. 이 패턴은 생성되는 다음 응답 유형을 지원합니다.

  • 사고 메시지: 질문을 해석하는 데이터 에이전트의 추론 프로세스입니다.
  • 진행 상황 메시지: 데이터 소스의 데이터 검색 중 상태 업데이트입니다.
  • 쿼리 생성: 생성된 SQL 또는 Looker 쿼리로, 생성되는 대로 스트리밍됩니다.
  • 데이터: JSON 형식의 데이터 결과입니다.
  • 시각화: Vega-Lite 차트 사양입니다.
  • 요약: 최종 텍스트 기반 답변입니다.

반환되는 데이터 유형의 전체 목록은 API 참고 문서의 SystemMessage 유형을 참고하세요.

이러한 비동기식 접근 방식은 사용자가 복잡한 데이터 검색 프로세스가 완전히 완료될 때까지 기다릴 필요가 없도록 합니다. 데이터 에이전트는 쿼리 프로세스를 진행하면서 텍스트 요약, 원시 데이터, 차트 구성과 같은 증분 업데이트를 임시 공유 작업공간에 지속적으로 공유합니다. 이 데이터는 실시간으로 사용자에게 렌더링되고 전문 하위 에이전트와 공유되어 추가 작업을 수행할 수 있습니다.

루트 에이전트, 데이터 하위 에이전트, 시각화 에이전트를 포함하는 참조 구현은 GitHub의 ADK 스트리밍 데모를 참고하세요.

수직 통합(MCP)

모델 컨텍스트 프로토콜(MCP)은 AI 애플리케이션이 외부 도구 및 데이터 소스에 연결하는 균일한 방법을 제공하는 개방형 표준입니다. MCP는 AI 모델과 AI 모델이 사용하는 도구 간의 인터페이스를 표준화합니다.

이 섹션에서는 다음 내용에 대해 설명합니다.

대화형 분석 API 원격 MCP 서버

대화형 분석 API는 Google의 관리형 MCP 서버를 기반으로 https://geminidataanalytics.googleapis.com/mcp에서 원격 MCP 서버를 제공합니다. 이 게이트웨이는 서드 파티 AI 플랫폼 및 Google 관리 플랫폼(예: Gemini Enterprise)의 루트 에이전트가 Google Cloud전반에서 전문 데이터 에이전트를 검색하고 통신할 수 있도록 통합된 보안 HTTP 및 서버 전송 이벤트(SSE) 인터페이스를 제공합니다.

루트 에이전트 통신 개요

외부 또는 Google 관리 루트 에이전트와 대화형 분석 API 간의 통신에는 세 가지 고유한 역할이 포함됩니다.

  1. 데이터 운영자는 대화형 분석 표면에서 범위가 지정된 데이터 에이전트를 만들고 구성하며, 각 에이전트가 액세스할 수 있는 데이터 소스와 답변할 수 있는 질문에 대한 명확한 설명을 작성하고, 이러한 에이전트를 비즈니스 사용자와 공유합니다.
  2. 플랫폼 관리자는 https://geminidataanalytics.googleapis.com/mcp 엔드포인트를 가리키는 에이전트형 플랫폼에 커스텀 MCP 연결을 등록합니다. 관리자는 Google 승인 엔드포인트(https://accounts.google.com/o/oauth2/v2/auth), 토큰 엔드포인트(https://oauth2.googleapis.com/token), 필수 승인 범위(https://www.googleapis.com/auth/geminidataanalytics 및 https://www.googleapis.com/auth/bigquery.readonly)를 사용하여 OAuth 2.0 클라이언트 사용자 인증 정보(클라이언트 ID 및 클라이언트 보안 비밀번호)를 구성합니다.
  3. 비즈니스 사용자는 에이전트 플랫폼에서 자연어로 질문합니다. 플랫폼의 루트 에이전트(오케스트레이터 LLM)는 원시 데이터베이스를 직접 쿼리하는 대신 대화형 분석 API 원격 MCP 서버와 통신하여 관련 데이터 에이전트를 검색하고, 사용자의 질문을 적절한 범위의 데이터 에이전트로 라우팅하고, 합성된 답변을 반환합니다.
ID 전파

서드 파티 또는 외부 루트 에이전트에서 요청이 시작될 때 엔터프라이즈 데이터 거버넌스를 유지하기 위해 원격 MCP 서버는 엔드 투 엔드 ID 전파를 시행합니다.

  • 사용자 위임 인증: 비즈니스 사용자가 루트 에이전트와 상호작용할 때 에이전트형 플랫폼은 3-legged OAuth 2.0 플로우를 통해 사용자를 인증하고 MCP 게이트웨이로 전송되는 요청의 HTTP 헤더에 사용자 위임 OAuth 액세스 토큰을 포함합니다.
  • 최종 사용자 인증 정보(EUC) 전달: 원격 MCP 서버는 토큰을 검증하고 Conversational Analytics API 레이어를 통해 BigQuery, Spanner, AlloyDB, Cloud SQL과 같은 기본 데이터 엔진에 최종 사용자 인증 정보를 전파합니다.
  • 관리형 데이터 액세스: 쿼리는 공유 서비스 계정이 아닌 인증된 사용자의 ID를 사용하여 실행되므로 기본 데이터 소스는 기존 IAM 권한, 행 수준 및 열 수준 보안 정책, 관리형 데이터 액세스 경계를 자동으로 적용합니다. 사용자는 이미 액세스 권한이 있는 데이터 에이전트만 검색하고 데이터 세트를 쿼리할 수 있습니다.
  • Looker 2중 ID 모델: BigQuery 및 운영 데이터베이스의 경우 개별 사용자의 전달된 Google OAuth 사용자 인증 정보로 쿼리가 실행됩니다. Looker 지원 데이터 에이전트의 경우 인증에 이중 ID 모델이 사용됩니다. 사용자의 Google OAuth 토큰은 Google IAM에서 데이터 에이전트에 대한 액세스를 승인하지만, 쿼리는 Looker API 사용자에 대해 제공된 사용자 인증 정보(채팅 도구의 사용자 인증 정보 블록에 전달됨)를 사용하여 Looker에서 실행됩니다. Looker 모델 액세스, 권한, 행 수준 규칙은 개별 최종 사용자의 Looker ID가 아닌 구성된 API 사용자를 반영합니다.
루트 에이전트가 API 메서드에 액세스하는 방법

MCP 클라이언트가 https://geminidataanalytics.googleapis.com/mcp에 연결되면 표준 MCP tools/list 메서드를 호출하여 대화형 분석 API에서 노출하는 도구 스키마를 동적으로 가져옵니다. 그런 다음 루트 에이전트는 기본 REST API 메서드에 직접 매핑되는 이러한 MCP 도구와 리소스를 호출하여 대화형 분석 API와 상호작용합니다.

MCP 도구 또는 리소스 매핑된 대화형 분석 API 메서드 루트 에이전트가 사용하는 방식
list_data_agents projects.locations.dataAgents.list

사용 가능한 데이터 에이전트를 검색합니다. 루트 에이전트는 대상 PROJECT_ID(및 LOCATION)를 전달하고 사용자가 액세스할 수 있는 활성 데이터 에이전트 목록(각 에이전트의 ID 및 설명 포함)을 수신합니다. 루트 에이전트는 이러한 설명을 평가하여 사용자의 질문에 답변할 수 있는 데이터 에이전트를 결정합니다.

도움말: 루트 에이전트가 비즈니스 사용자에게 프로젝트 ID를 제공하라는 메시지를 표시하지 않도록 루트 에이전트의 커스텀 시스템 안내에 대상 PROJECT_ID를 포함합니다.

get_data_agent

(또는 gda://agents/AGENT_ID MCP 리소스)

 projects.locations.dataAgents.get

특정 데이터 에이전트의 메타데이터와 컨텍스트를 검사합니다. 루트 에이전트는 에이전트 설명만으로는 복잡한 프롬프트를 라우팅하기에 충분하지 않은 경우 대상 AGENT_ID를 전달하여 연결된 BigQuery 테이블, 시스템 요청 사항, 용어집, 검증된 쿼리와 같은 구성 세부정보를 검색합니다.
chat projects.locations.chat

대화형 쿼리의 실행 프록시 역할을 합니다. 검색된 데이터 에이전트를 쿼리하기 위해 루트 에이전트는 에이전트의 전체 리소스 이름(projects/PROJECT_ID/locations/LOCATION/dataAgents/AGENT_ID)과 사용자의 자연어 메시지가 포함된 data_agent_context를 messages에 전달합니다. 스테이트리스(Stateless) 임시 쿼리의 경우 루트 에이전트가 대신 inline_context를 전달할 수 있습니다. 이 도구는 자연어 답변, 생성된 SQL 쿼리, 결과 행, Vega-Lite 차트 사양, 에이전트 추론을 반환합니다.

데이터베이스용 MCP 도구 상자

오픈소스 데이터베이스용 MCP 도구 상자 서버를 통해 대화형 분석 API에 액세스할 수도 있습니다. 이 서버는 대화형 분석 API에서 chat 메서드를 노출하는 사전 빌드된 MCP 호환 도구를 제공합니다.

MCP는 Conversational Analytics API의 별도 실행 모델이 아닌 MCP 호환 클라이언트에 분석 기능을 도구로 노출하는 상호 운용성 레이어입니다.

독립형 및 ADK 아키텍처의 MCP 구현 패턴

다음 패턴을 통해 MCP를 구현할 수 있습니다.

패턴 세부정보
독립형 MCP(ADK 없음)

데이터베이스용 MCP 도구 상자 서버를 독립형 서버로 사용하여 MCP 호환 클라이언트에 연결합니다. 이 패턴은 일반적으로 다음 작업에 사용됩니다.

  • IDE 통합: Antigravity, Cursor, VS Code와 같은 IDE를 서버에 연결하여 편집기에서 대화형으로 데이터를 쿼리합니다.
  • 커스텀 MCP 클라이언트: 서버를 사용하여 여러 AI 제공업체에 걸쳐 균일한 도구 인터페이스를 제공하는 애플리케이션을 빌드합니다.
  • Gemini CLI: CLI를 터미널 기반 데이터 대화를 위한 MCP 클라이언트로 사용합니다.
ADK 내 MCP

ADK 프레임워크는 MCP 서버를 에이전트 워크플로에 통합하기 위한 다음과 같은 메커니즘을 제공합니다.

  • ToolboxToolset: 여러 인증 방법을 지원하는 데이터베이스용 MCP 도구 상자 서버의 특수 변형입니다.
  • McpToolset: 로컬 또는 원격 MCP 서버 연결을 사용하여 ADK 에이전트를 MCP 서버에 연결합니다. 서버의 도구를 자동으로 검색하여 에이전트에 노출합니다.

FastMCP 프레임워크를 사용하여 MCP 서버를 빌드하면 ADK 프레임워크로 빌드된 도구를 모든 MCP 호환 클라이언트에 노출할 수 있습니다. 이 접근 방식을 사용하면 ADK 에이전트를 다른 생태계에서 도구로 사용할 수 있습니다.

애플리케이션의 특정 아키텍처 요구사항을 충족하는 통합 패턴을 선택합니다.

  • BigQueryToolset 또는 DataAgentToolset와 같은 기본 제공 에이전트 개발 키트(ADK) 도구 모음을 사용하면 외부 서버 종속 항목 없이 더 긴밀하게 통합할 수 있습니다. 이 접근 방식은 ADK 프레임워크 내에 완전히 존재하는 시스템에 적합합니다.
  • MCP 도구 상자의 도구를 사용하면 MCP 호환 클라이언트 간에 상호 운용성이 제공됩니다. 이 접근 방식은 여러 소비자 애플리케이션 또는 서드 파티 IDE를 지원해야 하는 데이터 도구에 적합합니다.

수평 조정(A2A)

에이전트 간(A2A) 프로토콜은 커스텀 통합 코드 없이도 서로 다른 시스템의 전문 에이전트가 안전하게 통신하고 협업할 수 있도록 지원하는 개방형 표준입니다.

시스템이 확장됨에 따라 조직에서는 다양한 프레임워크나 클라우드 인프라를 기반으로 빌드된 여러 전문 에이전트를 배포하는 경우가 많습니다. A2A는 이러한 자율 에이전트를 위한 범용 메시징 계층을 설정합니다. 각 에이전트는 커스텀 API를 사용하는 대신 에이전트의 기능, 지원되는 데이터 형식, 보안 요구사항을 자세히 설명하는 검색 가능한 프로필인 에이전트 카드를 게시합니다.

중앙 조정자 또는 피어 에이전트가 분석 데이터를 필요로 하는 경우 구조화된 A2A 메시지를 통해 데이터 에이전트에 작업을 안전하게 위임합니다. 데이터 에이전트는 요청을 자율적으로 처리하고 결과를 반환하므로 요청자로부터 실행 로직이 분리됩니다.

A2A 프로토콜을 사용하여 에이전트 카드를 검색하고, 메시지를 전송하고, 구조화된 아티팩트를 스트리밍하는 방법을 알아보려면 A2A로 데이터 에이전트 조정을 참조하세요.

통합 패턴 선택

다음 표를 사용하여 각 통합 패턴의 복잡성, 거버넌스, 기능을 비교하세요.

복잡성 수준은 다음과 같이 정의됩니다.

  • 낮음: 커스텀 코드가 최소한으로 필요하고 사전 빌드된 사용자 인터페이스나 도구를 사용하는 패턴입니다.
  • 중간: 커스텀 프런트엔드 개발과 API 또는 SDK 통합이 필요하지만 복잡한 백엔드 조정 인프라가 필요하지 않은 패턴입니다.
  • 높음: 풀 스택 애플리케이션 개발, 대화 상태 관리, 여러 인증 레이어 또는 중간 조정자 인프라가 필요한 패턴입니다.
  • 다양함: 선택한 기본 통합 방법에 따라 복잡성이 달라지는 패턴입니다.
통합 패턴 복잡성 맞춤설정 에이전트 거버넌스 액세스 제어 멀티 에이전트 스트리밍 이식성
Looker iframe 삽입 낮음 낮음 Looker를 통해 관리됨 Looker 아니요 기본 제공 Looker만 해당
Looker API 및 SDK 보통 높음 Looker를 통해 관리됨 Looker 아니요 기본 제공 Looker만 해당
Looker 소스를 사용하는 대화형 분석 API 다양한 가격 높음 API를 통해 관리됨 Looker 및 IAM 예 예 모든 Google Cloud 표시 경로
단일 에이전트(직접 API) 보통 높음 API를 통해 관리됨 IAM 아니요 예(지원됨) 모든 Google Cloud 표시 경로
커스텀 조정자 높음 매우 높음 API를 통해 관리됨 IAM 수동 수동 모든 Google Cloud 표시 경로
BigQueryToolset(ADK)를 사용한 스키마 기반 낮음 보통 없음(스키마 추론) IAM 예(ADK) 아니요(차단) ADK 생태계
DataAgentToolset(ADK)로 관리 낮음 보통 API를 통해 관리됨 IAM 예(ADK) 아니요(차단) ADK 생태계
커스텀 스트리밍 하위 에이전트(ADK) 높음 매우 높음 API를 통해 관리됨 IAM 예(ADK) 예(맞춤) ADK 생태계
독립형 MCP 보통 보통 없음(스키마 추론) IAM 아니요 아니요 모든 MCP 클라이언트
ADK 내 MCP 보통 높음 없음(스키마 추론) IAM 예(ADK) 아니요 ADK 및 MCP 클라이언트
A2A 프로토콜 높음 높음 프레임워크 종속 항목 IAM 예 예 크로스 플랫폼

다음 단계