BigQuery 및 Google 지도의 MCP 서버를 사용하여 위치 인텔리전스 ADK 에이전트 빌드

1. 소개

이 Codelab에서는 Gemini 3.0 Pro로 구동되는 ADK를 사용하여 에이전트를 빌드합니다. 에이전트는 인구통계, 가격, 판매 데이터를 위해 BigQuery에 안전하게 액세스하고 실제 위치 분석 및 검증을 위해 Google 지도에 액세스할 수 있도록 두 개의 원격 (Google 호스팅) MCP 서버의 도구를 갖추게 됩니다.

상담사는 사용자와 Google Cloud 서비스 간의 요청을 오케스트레이션하여 가상의 빵집 데이터 세트와 관련된 비즈니스 문제를 해결합니다.

실습할 내용

데이터 설정: BigQuery에서 기본 빵집 데이터 세트를 만듭니다.
에이전트 개발: 에이전트 개발 키트 (ADK)를 사용하여 지능형 에이전트를 빌드합니다.
도구 통합: MCP 서버를 통해 BigQuery 및 지도 기능을 에이전트에 제공합니다.
시장 분석: 에이전트와 상호작용하여 시장 동향과 포화도를 평가합니다.

필요한 항목

웹브라우저(예: Chrome)
결제가 사용 설정된 Google Cloud 프로젝트 또는 Gmail 계정

이 Codelab은 초보자를 포함한 모든 수준의 개발자를 대상으로 합니다. Google Cloud Shell의 명령줄 인터페이스와 ADK 개발용 Python 코드를 사용합니다. Python 전문가가 아니어도 되지만 코드를 읽는 방법을 기본적으로 이해하면 개념을 이해하는 데 도움이 됩니다.

2. 시작하기 전에

Google Cloud 프로젝트 만들기

Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.

Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다. 프로젝트에 결제가 사용 설정되어 있는지 확인하는 방법을 알아보세요.

Cloud Shell 시작

Cloud Shell은 Google Cloud에서 실행되는 명령줄 환경으로, 필요한 도구가 미리 로드되어 제공됩니다.

Google Cloud 콘솔 상단에서 Cloud Shell 활성화를 클릭합니다.

Cloud Shell에 연결되면 다음 명령어를 실행하여 Cloud Shell에서 인증을 확인합니다.

gcloud auth list

다음 명령어를 실행하여 프로젝트가 gcloud와 함께 사용하도록 구성되어 있는지 확인합니다.

gcloud config get project

프로젝트가 예상대로인지 확인한 후 아래 명령어를 실행하여 프로젝트 ID를 설정합니다.

export PROJECT_ID=$(gcloud config get project)

3. 코드 가져오기

저장소 클론

저장소를 Cloud Shell 환경에 클론합니다.

git clone https://github.com/google/mcp.git

데모 디렉터리로 이동합니다.

cd mcp/examples/launchmybakery

인증

다음 명령어를 실행하여 Google Cloud 계정으로 인증합니다. ADK가 BigQuery에 액세스하려면 이 권한이 필요합니다.

gcloud auth application-default login

표시되는 메시지에 따라 인증 절차를 완료합니다.

4. 환경 및 BigQuery 구성

설정 스크립트 실행

환경 설정 스크립트를 실행합니다. 이 스크립트는 BigQuery 및 Google Maps API를 사용 설정하고 프로젝트 ID와 Maps API 키가 포함된 .env 파일을 만듭니다.

chmod +x setup/setup_env.sh
./setup/setup_env.sh

BigQuery 설정 스크립트를 실행합니다. 이 스크립트는 Cloud Storage 버킷 생성, 데이터 업로드, BigQuery 데이터 세트 및 테이블 프로비저닝을 자동화합니다.

chmod +x ./setup/setup_bigquery.sh
./setup/setup_bigquery.sh

스크립트가 완료되면 mcp_bakery 데이터 세트가 생성되고 다음 테이블로 채워집니다.

인구통계 - 우편번호별 인구조사 데이터 및 인구 특성입니다.
bakery_prices - 다양한 구운 식품의 경쟁업체 가격 및 제품 세부정보
sales_history_weekly - 스토어 및 제품별 주간 판매 실적 (수량 및 수익)입니다.
foot_traffic - 우편번호 및 시간대별 예상 오프라인 매장 방문수 점수입니다.

Google Cloud 프로젝트에서 BigQuery 콘솔을 방문하여 데이터 세트와 테이블이 생성되었는지 확인합니다.

5. ADK 설치

이제 인프라가 준비되었으므로 가상 Python 환경을 만들고 ADK에 필요한 패키지를 설치해 보겠습니다.

가상 환경을 만듭니다.

python3 -m venv .venv

가상 환경을 활성화합니다.

source .venv/bin/activate

ADK를 설치합니다.

pip install google-adk

에이전트 디렉터리로 이동합니다.

cd adk_agent/

6. ADK 애플리케이션 검사

Cloud Shell에서 편집기 열기 버튼을 클릭하여 Cloud Shell 편집기를 열고 mcp/examples/launchmybakery 디렉터리에서 클론된 저장소를 확인합니다.

에이전트 코드는 adk_agent/ 디렉터리에 이미 제공되어 있습니다. 솔루션 구조를 살펴보겠습니다.

launchmybakery/
├── data/                        # Pre-generated CSV files for BigQuery
├── adk_agent/                   # AI Agent Application (ADK)
│   └── mcp_bakery_app/          # App directory
│       ├── agent.py             # Agent definition
│       ├── tools.py             # Custom tools for the agent
│       └── .env                 # Project configuration (created by setup script)
├── setup/                       # Infrastructure setup scripts
└── cleanup/                     # Infrastructure cleanup scripts

mcp_bakery_app의 키 파일:

agent.py: 에이전트, 도구, 모델 (Gemini 3.0 Pro 미리보기)을 정의하는 핵심 로직입니다.
tools.py: 맞춤 도구 정의를 포함합니다.
.env: 설정 스크립트로 생성된 프로젝트 구성 및 보안 비밀 (예: API 키)이 포함됩니다.

1. MCP 도구 모음 초기화:

이제 편집기에서 adk_agent/mcp_bakery_app/tools.py를 열어 MCP 도구 모음이 초기화되는 방식을 이해합니다.

에이전트가 BigQuery 및 Google 지도와 통신할 수 있도록 모델 컨텍스트 프로토콜 (MCP) 클라이언트를 구성해야 합니다.

이 코드는 StreamableHTTPConnectionParams를 사용하여 Google의 원격 MCP 서버에 보안 연결을 설정합니다.

def get_maps_mcp_toolset():
    dotenv.load_dotenv()
    maps_api_key = os.getenv('MAPS_API_KEY', 'no_api_found')
    
    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=MAPS_MCP_URL,
            headers={    
                "X-Goog-Api-Key": maps_api_key
            }
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools


def get_bigquery_mcp_toolset():   
        
    credentials, project_id = google.auth.default(
            scopes=["https://www.googleapis.com/auth/bigquery"]
    )

    credentials.refresh(google.auth.transport.requests.Request())
    oauth_token = credentials.token
        
    HEADERS_WITH_OAUTH = {
        "Authorization": f"Bearer {oauth_token}",
        "x-goog-user-project": project_id
    }

    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=BIGQUERY_MCP_URL,
            headers=HEADERS_WITH_OAUTH
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools

지도 도구 모음: API 키를 사용하여 지도 MCP 서버에 대한 연결을 구성합니다.
BigQuery 도구 모음: 이 함수는 BigQuery MCP 서버에 대한 연결을 구성합니다. google.auth를 사용하여 Cloud 사용자 인증 정보를 자동으로 가져오고, OAuth Bearer 토큰을 생성하고, Authorization 헤더에 삽입합니다.

2. 에이전트 정의:

이제 편집기에서 adk_agent/mcp_bakery_app/agent.py을 열어 에이전트가 어떻게 정의되어 있는지 확인합니다.

LlmAgent는 gemini-3-pro-preview 모델로 초기화됩니다.

maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()

root_agent = LlmAgent(
    model='gemini-3-pro-preview',
    name='root_agent',
    instruction=f"""
                Help the user answer questions by strategically combining insights from two sources:
                
                1.  **BigQuery toolset:** Access demographic (inc. foot traffic index), product pricing, and historical sales data in the  mcp_bakery dataset. Do not use any other dataset.
                Run all query jobs from project id: {project_id}. 

                2.  **Maps Toolset:** Use this for real-world location analysis, finding competition/places and calculating necessary travel routes.
                    Include a hyperlink to an interactive map in your response where appropriate.
            """,
    tools=[maps_toolset, bigquery_toolset]
)

시스템 요청 사항: 에이전트에게 BigQuery (데이터용)와 지도 (위치 분석용)의 통계를 결합하라는 구체적인 요청 사항이 제공됩니다.
도구: maps_toolset와 bigquery_toolset가 모두 에이전트에 할당되어 두 서비스의 기능에 액세스할 수 있습니다.

에이전트는 저장소에 정의된 안내와 도구를 준수합니다. 요청 사항을 변경하여 에이전트의 동작에 미치는 영향을 확인해 보세요.

7. 상담사와 채팅하세요.

Cloud Shell의 터미널로 돌아가서 다음 명령어를 실행하여 adk_agent 디렉터리로 이동합니다.

cd adk_agent

다음 명령어를 실행하여 ADK 웹 인터페이스를 시작합니다. 이 명령어는 채팅 애플리케이션을 호스팅하기 위해 경량 웹 서버를 실행합니다.

adk web

서버가 시작되면 제공된 URL을 클릭하여 ADK 웹 인터페이스를 실행하고 에이전트와 채팅할 수 있습니다.

다음 질문을 통해 에이전트와 상호작용합니다. 관련 도구가 호출되는 것을 확인할 수 있습니다.

동네 찾기 (매크로): '로스앤젤레스에 제과점을 열고 싶어. 아침 유동인구 점수가 가장 높은 우편번호를 찾아 줘."

에이전트는 get_table_info 및 execute_sql과 같은 도구를 사용하여 BigQuery의 foot_traffic 테이블을 쿼리해야 합니다.

위치 확인 (마이크로): '해당 우편번호에서'빵집'을 검색하여 포화 상태인지 확인할 수 있어?'

상담사는 지도 도구 세트의 search places 도구를 사용하여 이 질문에 답변해야 합니다.

지금 사용해 보세요. 다음 샘플 질문을 통해 ADK 에이전트의 작동 방식을 확인하세요.

'로스앤젤레스에 네 번째 베이커리 매장을 열고 싶어. 아침 일찍 활동하는 동네가 필요해. '아침' 도보 트래픽 점수가 가장 높은 우편번호를 찾아 줘.'
'해당 우편번호에서'빵집'을 검색하여 포화 상태인지 확인할 수 있어? 너무 많으면 '스페셜티 커피' 매장을 확인해 줘. 내가 그 근처에 자리 잡고 유동인구를 확보할 수 있도록."
'좋아. 이걸 프리미엄 브랜드로 포지셔닝하고 싶어. LA 메트로 지역에서 '사워도우 로프'에 부과되는 최대 가격은 얼마야?'
'이제 2025년 12월의 수익 예측을 알려 줘. 판매 기록을 확인하고 실적이 가장 좋은 매장의 '사워도우 로프' 데이터를 가져와 줘. 2025년 12월의 판매량을 추정하기 위해 예측을 실행해 줘. 그런 다음, 찾은 프리미엄 가격보다 약간 낮은 가격 (예: 18달러)을 사용하여 예상 총수입을 계산해 줘'
"월세를 낼 수 있겠네. 마지막으로 물류를 확인해 보겠습니다. 제안된 지역에서 가장 가까운 'Restaurant Depot'을 찾아 일일 재고 보충을 위한 운전 시간이 30분 미만인지 확인해 줘.'

8. 삭제

Google Cloud 계정에 지속적으로 요금이 청구되지 않도록 하려면 이 Codelab 중에 만든 리소스를 삭제하세요.

정리 스크립트를 실행합니다. 이 스크립트는 설정 중에 생성된 BigQuery 데이터 세트, Cloud Storage 버킷, API 키를 삭제합니다.

chmod +x ../cleanup/cleanup_env.sh
./../cleanup/cleanup_env.sh

9. 축하합니다

미션 완료! 에이전트 개발 키트 (ADK)를 사용하여 위치 인텔리전스 에이전트를 빌드했습니다.

BigQuery의 '엔터프라이즈' 데이터와 Google 지도의 실제 위치 컨텍스트 간의 격차를 해소하여 모델 컨텍스트 프로토콜 (MCP)과 Gemini로 구동되는 복잡한 비즈니스 추론이 가능한 강력한 도구를 만들었습니다.

달성한 내용:

코드형 인프라: Google Cloud CLI 도구를 사용하여 데이터 스택을 프로비저닝했습니다.
MCP 통합: 복잡한 API 래퍼를 작성하지 않고 AI 에이전트를 두 개의 서로 다른 원격 MCP 서버 (BigQuery 및 지도)에 연결했습니다.
통합 추론: 두 도메인의 통찰력을 전략적으로 결합하여 비즈니스 문제를 해결할 수 있는 단일 에이전트를 빌드했습니다.