콘텐츠로 이동

ADK용 Google Cloud Data Agents 도구

ADK 지원Python v1.23.0

이 도구는 Conversational Analytics API로 구동되는 데이터 에이전트와의 통합을 제공하는 도구 세트입니다. 데이터 에이전트는 자연어를 사용하여 데이터를 분석하는 데 도움을 주는 AI 기반 에이전트입니다. 데이터 에이전트를 구성할 때 BigQuery, Looker, Looker Studio 등 지원되는 데이터 소스 중에서 선택할 수 있습니다. DataAgentToolset에는 기본적으로 다음과 같은 읽기 전용 도구가 포함되어 있습니다.

  • list_accessible_data_agents: 지정된 Google Cloud 프로젝트에서 액세스 권한이 있는 데이터 에이전트를 나열합니다. 선택적 location 재정의는 물론 자동 또는 수동 페이지네이션(page_size 및 page_token)을 지원합니다.
  • get_data_agent_info: 전체 리소스 이름(projects/{project}/locations/{location}/dataAgents/{agent})을 기반으로 특정 데이터 에이전트에 대한 세부정보와 게시된 컨텍스트를 가져옵니다.
  • ask_data_agent: 특정 데이터 에이전트에 자연어 질문을 보내고 응답을 반환합니다.

DataAgentToolConfig에서 enable_data_agent_modification=True로 설정하면 도구 세트에 다음 도구도 포함됩니다.

  • create_data_agent: DataAgent 리소스 스키마를 따르는 JSON agent_config에서 Google Cloud 프로젝트에 지정된 data_agent_id로 새 데이터 에이전트를 생성합니다. location 인수는 선택사항입니다.
  • update_data_agent: JSON agent_config와 카멜 케이스(camelCase) 필드 이름의 쉼표로 구분된 update_mask(예: displayName,description)를 사용하여 기존 데이터 에이전트를 업데이트합니다. update_mask에 나열된 모든 필드는 agent_config에도 존재해야 합니다.
  • delete_data_agent: 전체 리소스 이름을 기반으로 기존 데이터 에이전트를 삭제합니다.

이러한 수정 도구는 기본 장기 실행 작업이 완료될 때까지 최대 data_agent_modification_timeout_seconds 동안 대기합니다.

사전 요구사항

이 도구를 사용하기 전에 Google Cloud에서 다음 단계를 완료하세요.

인증

DataAgentToolset에는 DataAgentCredentialsConfig가 필요하며 여러 인증 메커니즘을 지원합니다. credentials, external_access_token_key 또는 client_id와 client_secret 쌍 중 하나를 제공해야 합니다. 기본적으로 DataAgentCredentialsConfig는 https://www.googleapis.com/auth/bigquery OAuth 범위를 사용하며, OAuth 클라이언트 사용자 인증 정보를 구성할 때 scopes를 사용하여 이를 재정의할 수 있습니다.

실험적 기능

DataAgentCredentialsConfig 클래스는 실험적 기능인 BaseGoogleCredentialsConfig를 확장하므로 프로덕션 프로젝트에는 사용하지 않아야 합니다.

애플리케이션 기본 사용자 인증 정보 (ADC)

로컬 개발과 Cloud Run 및 GKE와 같은 Google Cloud 서비스에서 실행할 때 이 접근 방식을 사용해야 합니다.

import google.auth
from google.adk.tools.data_agent import DataAgentToolset, DataAgentCredentialsConfig

# 애플리케이션 기본 사용자 인증 정보 로드
credentials, project_id = google.auth.default()

# 도구 세트 구성
credentials_config = DataAgentCredentialsConfig(credentials=credentials)
data_agent_toolset = DataAgentToolset(credentials_config=credentials_config)

서비스 계정

서비스 계정 파일이나 정보를 명시적으로 제공할 수 있습니다.

from google.oauth2 import service_account
from google.adk.tools.data_agent import DataAgentToolset, DataAgentCredentialsConfig

# 서비스 계정 사용자 인증 정보 로드
credentials = service_account.Credentials.from_service_account_file('path/to/key.json')

# 도구 세트 구성
credentials_config = DataAgentCredentialsConfig(credentials=credentials)
data_agent_toolset = DataAgentToolset(credentials_config=credentials_config)

외부 액세스 토큰

최종 사용자를 대신하여 작동해야 하는 애플리케이션의 경우 OAuth2 흐름이나 외부 IDP 등에서 얻은 액세스 토큰으로 직접 인스턴스화된 사용자 인증 정보를 전달할 수 있습니다.

from google.oauth2.credentials import Credentials
from google.adk.tools.data_agent import DataAgentToolset, DataAgentCredentialsConfig

# 외부 OAuth 흐름을 통해 'user_token'을 얻었다고 가정
credentials = Credentials(token=user_token)

# 도구 세트 구성
credentials_config = DataAgentCredentialsConfig(credentials=credentials)
data_agent_toolset = DataAgentToolset(credentials_config=credentials_config)

외부 인증 제공자

Gemini Enterprise와 같이 플랫폼에서 토큰을 관리하는 외부 인증 제공자와 통합하는 경우 external_access_token_key를 사용하세요.

from google.adk.tools.data_agent import DataAgentToolset, DataAgentCredentialsConfig

# 세션 상태에서 액세스 토큰을 조회하는 데 사용되는 키
credentials_config = DataAgentCredentialsConfig(
    external_access_token_key="YOUR_AUTH_ID"
)
data_agent_toolset = DataAgentToolset(credentials_config=credentials_config)

대화형 인증 (ADK Web)

대화형 세션을 위해 adk web 인터페이스를 사용할 때 OAuth 2.0 클라이언트 사용자 인증 정보를 제공하여 로그인 흐름을 트리거할 수 있습니다. 이 메커니즘은 로컬 개발 환경과 ADK 에이전트가 Cloud Run과 같은 환경에 배포된 경우 모두에서 작동합니다.

from google.adk.tools.data_agent import DataAgentToolset, DataAgentCredentialsConfig

# OAuth 2.0 클라이언트 ID 및 보안 비밀 제공
credentials_config = DataAgentCredentialsConfig(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET"
)
data_agent_toolset = DataAgentToolset(credentials_config=credentials_config)

구성

DataAgentToolConfig를 사용하여 도구 동작을 맞춤설정할 수 있습니다.

  • max_query_result_rows (int, 기본값: 50): ask_data_agent가 각 데이터 결과에 대해 반환하는 최대 행 수입니다.
  • location (str | None, 기본값: None): API 엔드포인트를 선택하는 데 사용되는 기본 Google Cloud 위치(예: global, us 또는 eu)입니다. location 인수를 받는 도구는 인수가 설정되지 않은 경우 이 값을 사용하며, 기본값으로 global로 대체됩니다. 다른 도구는 데이터 에이전트의 리소스 이름에서 위치를 사용하지만, ask_data_agent는 이 값이 설정된 경우 이 값을 사용합니다.
  • api_endpoint (str | None, 기본값: None): Conversational Analytics API 요청을 위한 선택적 맞춤 API 엔드포인트입니다. 제공된 경우 기본 또는 위치 기반 API 엔드포인트를 재정의합니다.
  • enable_data_agent_modification (bool, 기본값: False): True인 경우 도구 세트에 create_data_agent, update_data_agent, delete_data_agent도 포함됩니다. False인 경우 도구 세트는 읽기 전용입니다.
  • data_agent_modification_timeout_seconds (int, 기본값: 60): 장기 실행 생성, 업데이트 또는 삭제 작업을 폴링할 때의 총 타임아웃(초)입니다. 0보다 커야 합니다.
  • data_agent_modification_poll_interval_seconds (int, 기본값: 2): 생성, 업데이트 또는 삭제 작업이 완료될 때까지 대기하는 동안의 폴링 간격(초)입니다. 0보다 커야 합니다.

주의해서 사용

enable_data_agent_modification=True로 설정하면 에이전트가 Google Cloud 프로젝트에서 데이터 에이전트를 생성, 업데이트 및 삭제할 수 있습니다. 도구 세트에서 사용하는 사용자 인증 정보가 최소한의 필수 IAM 권한만 가진 승인된 프로젝트로 제한되어 있는지 확인하세요. 또한 DataAgentToolset에 tool_filter를 전달하여 특정 도구만 노출할 수도 있습니다(예: delete_data_agent 제외).

import google.auth
from google.adk.tools.data_agent import DataAgentToolset, DataAgentCredentialsConfig
from google.adk.tools.data_agent.config import DataAgentToolConfig

credentials, _ = google.auth.default()
credentials_config = DataAgentCredentialsConfig(credentials=credentials)

tool_config = DataAgentToolConfig(
    max_query_result_rows=100,
    enable_data_agent_modification=True,
    data_agent_modification_timeout_seconds=120,
)
data_agent_toolset = DataAgentToolset(
    credentials_config=credentials_config,
    data_agent_tool_config=tool_config,
)

샘플 코드

다음 샘플 코드는 애플리케이션 기본 사용자 인증 정보(ADC)를 사용하여 ADK 에이전트에서 DataAgentToolset을 사용하는 방법을 보여줍니다.

import asyncio

from google.adk.agents import Agent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.adk.tools.data_agent import DataAgentCredentialsConfig
from google.adk.tools.data_agent import DataAgentToolset
from google.adk.tools.data_agent.config import DataAgentToolConfig
from google.genai import types
import google.auth

# Define constants for this example agent
AGENT_NAME = "data_agent_example"
APP_NAME = "data_agent_app"
USER_ID = "user1234"
SESSION_ID = "1234"
GEMINI_MODEL = "gemini-flash-latest"

# Define tool configuration
# Set `enable_data_agent_modification=True` to also expose `create_data_agent`,
# `update_data_agent`, and `delete_data_agent`.
tool_config = DataAgentToolConfig(
    max_query_result_rows=100,
    enable_data_agent_modification=False,
)

# Use Application Default Credentials (ADC)
# https://cloud.google.com/docs/authentication/provide-credentials-adc
application_default_credentials, _ = google.auth.default()
credentials_config = DataAgentCredentialsConfig(
    credentials=application_default_credentials
)

# Instantiate a Data Agent toolset
da_toolset = DataAgentToolset(
    credentials_config=credentials_config,
    data_agent_tool_config=tool_config,
)

# Agent Definition
data_agent = Agent(
    name=AGENT_NAME,
    model=GEMINI_MODEL,
    description="Agent to answer user questions using data agents.",
    instruction=(
        "## Persona\nYou are a helpful assistant that uses data agents"
        " to answer user questions about their data.\n\n"
    ),
    tools=[da_toolset],
)


# Session and Runner
async def setup_session_and_runner():
    session_service = InMemorySessionService()
    await session_service.create_session(
        app_name=APP_NAME, user_id=USER_ID, session_id=SESSION_ID
    )
    return Runner(
        agent=data_agent, app_name=APP_NAME, session_service=session_service
    )


# Agent Interaction
async def call_agent_async(runner, query):
    """
    Helper function to call the agent with a query.
    """
    content = types.Content(role="user", parts=[types.Part(text=query)])
    events = runner.run_async(
        user_id=USER_ID, session_id=SESSION_ID, new_message=content
    )

    print("USER:", query)
    async for event in events:
        if event.is_final_response():
            final_response = event.content.parts[0].text
            print("AGENT:", final_response)


async def main():
    runner = await setup_session_and_runner()
    # Replace `<PROJECT_ID>` with your Google Cloud project ID, and replace
    # `<DATA_AGENT_NAME>` with a full resource name in the format:
    # `projects/{project}/locations/{location}/dataAgents/{agent}`
    await call_agent_async(
        runner, "List accessible data agents in project <PROJECT_ID>."
    )
    await call_agent_async(runner, "Get information about <DATA_AGENT_NAME>.")
    # The data agent in this example is configured with the BigQuery table:
    # `bigquery-public-data.san_francisco.street_trees`
    await call_agent_async(
        runner, "Ask <DATA_AGENT_NAME> to count the rows in the table."
    )
    await call_agent_async(runner, "What are the columns in the table?")
    await call_agent_async(runner, "What are the top 5 tree species?")
    await call_agent_async(
        runner, "For those species, what is the distribution of legal status?"
    )

참고: BigQuery 테이블과 데이터 세트를 도구로 직접 쿼리하려면 ADK용 BigQuery 도구를 참조하세요.