BigQuery MCP로 Google 트렌드 분석가 에이전트 빌드

1. 개요

이 Codelab에서는 Google ADK를 사용하여 Google 트렌드 분석가 에이전트를 빌드합니다. 이 에이전트는 BigQuery MCP 서버를 활용하여 Google 트렌드 공개 데이터 세트를 쿼리하는 도구를 동적으로 검색하고 실행합니다 (bigquery-public-data.google_trends).

학습할 내용

  • ADK 개발을 위한 프로젝트를 설정하는 방법
  • BigQuery용 관리형 MCP 서버를 사용 설정하고 사용하는 방법
  • MCP 도구를 사용하는 에이전트를 빌드하는 방법
  • 테스트를 위해 에이전트를 로컬에서 실행하는 방법
  • Google Cloud Run에 에이전트를 배포하는 방법

필요한 항목

  • 결제가 사용 설정된 Google Cloud 프로젝트
  • 웹브라우저(예: Chrome)
  • Python 3.11 이상

이 Codelab은 Python 및 Google Cloud에 익숙한 중급 개발자를 대상으로 합니다.

이 Codelab을 완료하는 데 약 15~20분이 소요됩니다.

이 Codelab에서 만든 리소스의 비용은 5달러 미만이어야 합니다.

2. 환경 설정

Google Cloud 프로젝트 만들기

  1. Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
  2. Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다. 프로젝트에 결제가 사용 설정되어 있는지 확인하는 방법을 알아보세요.

환경 변수 설정

다음 환경 변수를 설정합니다.

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_GENAI_USE_VERTEXAI=1

참고: GOOGLE_GENAI_USE_VERTEXAI=1를 설정하면 ADK가 GEMINI_API_KEY 대신 인증에 Cloud IAM을 활용하여 Vertex AI를 사용하도록 지시합니다.

gcloud 인증 및 구성

Google 계정에 로그인하고, 활성 프로젝트를 설정하고, 애플리케이션 기본 사용자 인증 정보를 구성합니다.

gcloud auth login
gcloud auth application-default login

참고: gcloud auth login는 gcloud CLI 명령어를 인증하고 gcloud auth application-default login는 로컬 애플리케이션 코드를 인증합니다.

Google Cloud 프로젝트를 설정합니다.

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

필요한 API 사용 설정

Cloud Run, Artifact Registry, BigQuery, Vertex AI에 필요한 Google Cloud API를 사용 설정합니다.

gcloud services enable run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       bigquery.googleapis.com \
                       aiplatform.googleapis.com

BigQuery용 MCP 사용 설정

관리형 MCP 서버는 프로젝트에 대해 명시적으로 사용 설정해야 합니다.

gcloud beta services mcp enable bigquery.googleapis.com

프로젝트 폴더 만들기

먼저 에이전트의 루트 폴더와 에이전트 구현을 위한 내부 폴더를 만듭니다.

mkdir google-trends-agent
cd google-trends-agent
mkdir google_trends

3. 에이전트 코드 만들기

이름이 google_trends/__init__.py인 빈 파일을 만듭니다.

touch google_trends/__init__.py

그런 다음 google_trends/agent.py라는 파일을 만들고 다음 코드를 붙여넣습니다.

import os
import textwrap
import warnings
from datetime import date

import google.auth
from google.adk.agents import LlmAgent
from google.adk.apps import App
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.auth.transport.requests import Request

# Suppress experimental ADK credential warnings
warnings.filterwarnings("ignore")

def get_agent_instruction(project_id: str) -> str:
    """Generates a clear and formatted prompt for the data analyst."""
    instruction = f"""
    # ROLE
    You are a Google Search Trends Analyst. Your mission is to provide clear answers using SQL data.

    # DATA CONSTRAINTS
    - BigQuery tool `execute_sql` requires explicit billing project mapping. Use: '{project_id}'.
    - Target dataset strictly: `bigquery-public-data.google_trends`

    # SCHEMA DISCOVERY (CRITICAL)
    1. DO NOT call `get_table_info` or `list_table_ids` (Triggers Permission Errors).
    2. Run `SELECT * FROM table LIMIT 0` via `execute_sql` for field definition mapping.

    # OUTPUT PRESENTATION
    - Render purely as a cleanly aligned Markdown table.
    - Use clear and descriptive headers for each column.
    - Remove conversational preambles. Output only the results.
    """
    return textwrap.dedent(instruction).strip()

def get_auth_headers() -> dict[str, str]:
    """Fetch auth headers for the project using Google Cloud Platform scopes."""
    credentials, _ = google.auth.default(
        scopes=["https://www.googleapis.com/auth/cloud-platform"]
    )
    request = Request()
    credentials.refresh(request)

    return {"Authorization": f"Bearer {credentials.token}"}

def get_todays_date() -> str:
    """Returns today's date in YYYY-MM-DD format."""
    return date.today().isoformat()

# --- Application Initialization ---
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable is not set")

mcp_headers = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
} | get_auth_headers()

# Configure BigQuery Tools via MCP
bq_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://bigquery.googleapis.com/mcp",
        headers=mcp_headers,
    )
)

# Initialize the LLM Agent
root_agent = LlmAgent(
    name="google_trends",
    model="gemini-3-flash-preview",
    tools=[get_todays_date, bq_tools],
    instruction=get_agent_instruction(project_id),
)

# Create the ADK App
app = App(name=root_agent.name, root_agent=root_agent)

4. 에이전트 실행

이 단계에서는 로컬 Python 가상 환경을 설정하고, 종속 항목을 설치하고, 에이전트를 실행하여 머신 (또는 Google Cloud Shell)에서 에이전트의 동작을 확인합니다.

  • 애플리케이션 루트 디렉터리 (google-trends-agent)로 이동합니다.
  • 가상 환경을 만듭니다.
python -m venv mcp_demo_env
source mcp_demo_env/bin/activate
  • 필수 Python 패키지를 설치합니다.
pip install google-auth google-adk

ADK 웹을 사용하여 새 에이전트를 테스트합니다.

로컬 개발 및 테스트의 경우 다음 명령어를 실행합니다.

adk web

Google Cloud Shell 내에서 개발 및 테스트하려면 다음 명령어를 실행합니다.

adk web --allow_origins="*"

그러면 ADK 웹 서버가 시작됩니다. 로컬 웹 인터페이스 (일반적으로 http://localhost:8000)를 사용하여 에이전트와 상호작용할 수 있습니다.

참고: 더 간단한 adk run google_trends 명령어를 사용하여 에이전트를 테스트할 수도 있습니다.

5. Cloud Run에 배포

다음 단계에 따라 에이전트를 Google Cloud Run에 안전하게 배포하세요.

권한 부여

Cloud Run에서 Vertex AI에 액세스하고 BigQuery MCP 도구를 사용하려면 권한이 필요합니다.

# Get your project number automatically
PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format='value(projectNumber)')

# Vertex AI Access: To talk to the Gemini model
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/aiplatform.user"

# MCP & BigQuery: To execute tools and run SQL jobs
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/mcp.toolUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/bigquery.jobUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/bigquery.dataViewer"

Dockerfile 만들기

프로젝트 루트 (google-trends-agent)에서 Dockerfile이라는 파일을 만들고 다음 콘텐츠를 붙여넣습니다.

FROM python:3.11-slim
WORKDIR /app

# Create a non-root user
RUN adduser --disabled-password --gecos "" myuser
USER myuser
ENV PATH="/home/myuser/.local/bin:$PATH"

# Copy the agent folder into the container
COPY --chown=myuser:myuser google_trends/ /app/agents/google_trends/

# Install the python packages
RUN pip install google-auth google-adk

# Set environment variables
ENV GOOGLE_GENAI_USE_VERTEXAI=1

# Expose port
EXPOSE 8080

# Run ADK web server
CMD ["adk", "web", "--port=8080", "--host=0.0.0.0", "/app/agents"]

에이전트 배포

루트 디렉터리에서 다음 명령어를 실행합니다. 이렇게 하면 에이전트가 컨테이너화되어 Cloud Run에 배포됩니다.

gcloud run deploy google-trends-agent \
  --source . \
  --region us-west1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}"

빠른 인증

배포가 완료되면 콘솔에 서비스 URL이 출력됩니다. 브라우저에서 이 URL을 엽니다. 로컬에서 본 것과 동일한 대화형 UI가 표시되지만 이제 클라우드에서 실행됩니다.

로그를 모니터링하여 모든 것이 원활하게 실행되는지 확인할 수도 있습니다.

gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=google-trends-agent" --limit 10

6. 삭제

요금이 계속 청구되지 않도록 이 Codelab에서 만든 리소스를 삭제합니다.

Cloud Run 서비스를 삭제합니다.

gcloud run services delete google-trends-agent --region us-west1

이 Codelab을 위해 특별히 프로젝트를 만든 경우 전체 프로젝트를 삭제할 수 있습니다.

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

이 Codelab과 관련된 모든 파일을 삭제할 수도 있습니다.

deactivate
cd ..
rm -rf google-trends-agent

7. 축하합니다

축하합니다. Google 트렌드 분석가 에이전트를 빌드하고 배포했습니다.

학습한 내용

  • MCP를 사용하여 에이전트 기능을 동적으로 확장하는 방법
  • Google ADK로 LLM 에이전트를 빌드하고 제공하는 방법
  • Cloud Run에서 에이전트를 배포하고 확장하는 방법

다음 단계

  • 에이전트를 수정하여 다른 BigQuery 데이터 세트를 쿼리해 보세요.
  • MCP 도구를 추가하여 에이전트 기능 확장

참조 문서