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

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

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

통합 패턴 개요

이 가이드는 시작점을 기준으로 다음과 같은 기본 트랙으로 구성되어 있습니다.

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

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

통합 패턴 설명 데이터 소스
Looker iframe 삽입 최소한의 코드가 필요한 애플리케이션에 표준 채팅 인터페이스를 추가합니다. Looker
Looker API 및 SDK 인증을 위해 Looker API를 사용하는 맞춤 채팅 인터페이스를 빌드합니다. Looker
대화형 분석 API (Looker 소스) 여러 플랫폼과 멀티 에이전트 시스템에서 작동하는 Looker 데이터 에이전트를 Google Cloud 리소스로 관리합니다. Looker
직접 API (단일 에이전트) 텍스트-답변 흐름에 직접 API 통합을 사용합니다. BigQuery, 데이터베이스, Looker
Direct 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
A2A 프로토콜 서로 다른 시스템에서 작동하는 전문 에이전트 간의 안전한 공동작업을 지원합니다. 프레임워크 종속

Looker 통합 옵션

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

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

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 서비스로 이동할 수 없습니다.
Conversational Analytics API 사용: API와 직접 통합하여 에이전트를 클라우드 수준 리소스로 관리합니다. 데이터 에이전트의 크로스 플랫폼 이동성이 필요한 Looker 고객
  • 데이터 에이전트가 모든 Google Cloud 표면에서 이식 가능하도록 합니다.
  • Identity and Access Management에 의해 중앙에서 관리됩니다.
  • 데이터 에이전트를 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 계정으로 로그인합니다. 이 메서드는 추가 Identity and Access Management 구성이나 토큰 매핑 없이 액세스 필터 또는 액세스 권한 부여와 같은 기존 역할, 콘텐츠 액세스, 데이터 수준 권한을 자동으로 적용합니다.
  • 서명된 삽입: 싱글 사인온 (SSO)을 사용하여 애플리케이션을 통해 사용자를 인증합니다. 대화형 분석 콘텐츠 경로가 포함된 서명된 URL을 구성하여 부여할 권한을 정확하게 동적으로 지정할 수 있습니다.

Looker API 및 SDK로 빌드

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

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

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

참조 구현은 GitHub의 대화형 분석 Looker API 가이드를 참고하세요.

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

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

  • 맞춤 웹 애플리케이션, Google Chat, Gemini Enterprise와 같은 여러 Google Cloud 표면에서 동일한 데이터 에이전트 공유
  • 단일 다중 에이전트 시스템에서 Looker 데이터 소스를 BigQuery 또는 운영 데이터베이스 소스와 결합
  • Looker 권한 모델이 아닌 Identity and Access Management에 의거하여 관리되는 클라우드 수준 리소스로 데이터 에이전트 관리

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

BigQuery 및 데이터베이스 통합 옵션

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

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

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

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

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

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

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

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

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

BigQueryToolset과의 스키마 기반 통합

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

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

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

DataAgentToolset와의 관리형 통합

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

대화형 분석 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 모델이 사용하는 도구 간의 인터페이스를 표준화합니다.

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

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

전용 대화형 분석 API 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: 터미널 기반 데이터 대화를 위한 MCP 클라이언트로 CLI를 사용합니다.
ADK 내 MCP

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

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

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

애플리케이션의 구체적인 아키텍처 요구사항에 따라 통합 패턴을 선택합니다.

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

수평 오케스트레이션 (A2A)

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

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

중앙 오케스트레이터 또는 피어 에이전트가 분석 데이터를 필요로 하는 경우 구조화된 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 예 예 크로스 플랫폼

다음 단계