1. 소개
이 Codelab에서는 Gemini 3.1 Pro 기반의 ADK를 사용하여 에이전트를 빌드합니다. 에이전트에는 두 개의 원격 (Google 호스팅) MCP 서버의 도구가 장착되어 인구통계, 가격 책정, 판매 데이터를 위해 BigQuery에 안전하게 액세스하고 실제 위치 분석 및 검증을 위해 Google 지도에 액세스합니다.
에이전트는 사용자와 Google Cloud 서비스 간의 요청을 오케스트레이션하여 가상의 제과점 데이터 세트와 관련된 비즈니스 문제를 해결합니다.
실습할 내용
- 데이터 설정: BigQuery에서 기본 제과점 데이터 세트를 만듭니다.
- 에이전트 개발: 에이전트 개발 키트 (ADK)를 사용하여 지능형 에이전트를 빌드합니다.
- 도구 통합: MCP 서버를 통해 에이전트에 BigQuery 및 지도 기능을 제공합니다.
- 시장 분석: 에이전트와 상호작용하여 시장 동향과 포화도를 평가합니다.
필요한 항목
- 웹브라우저(예: Chrome)
- 결제가 사용 설정된 Google Cloud 프로젝트 또는 Gmail 계정.
이 Codelab은 초보자를 포함한 모든 수준의 개발자를 대상으로 합니다. ADK 개발을 위해 Google Cloud Shell의 명령줄 인터페이스와 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 지도 API를 사용 설정하고 프로젝트 ID 및 지도 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==1.28.0
- 에이전트 디렉터리로 이동합니다.
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.1 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 전달자 토큰을 생성하고, 이를 승인 헤더에 삽입합니다.
2. 에이전트 정의:
이제 편집기에서 adk_agent/mcp_bakery_app/agent.py를 열어 에이전트가 정의되는 방식을 확인합니다.
LlmAgent는 gemini-3.1-pro-preview 모델로 초기화됩니다.
maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()
root_agent = LlmAgent(
model='gemini-3.1-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 --allow_origins 'regex:https://.*\.cloudshell\.dev'
서버가 시작되면 Cloud Shell에 다음이 표시됩니다.
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://127.0.0.1:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
ADK UI에 액세스하는 방법에는 두 가지가 있습니다.
옵션 1: 로컬 링크 클릭 Cloud Shell 터미널에 표시되는 http://127.0.0.1:8000 링크를 클릭합니다.
옵션 2: 웹 미리보기 사용
- Cloud Shell의 오른쪽 상단에 있는 웹 미리보기 버튼을 클릭합니다.
- 포트 변경 을 선택합니다.
- 포트 번호로 8000 을 입력하고 변경 및 미리보기 를 클릭합니다.
웹 UI에서 다음 질문을 하여 에이전트와 상호작용 합니다. 관련 도구가 호출되는 것을 확인할 수 있습니다.
- 이웃 찾기 (매크로): '로스앤젤레스에 제과점을 열고 싶습니다. 아침 도보 이동 점수가 가장 높은 우편번호를 찾아 주세요.'
에이전트는 get_table_info 및 execute_sql과 같은 도구를 사용하여 BigQuery의 foot_traffic 테이블을 쿼리해야 합니다.
- 위치 검증 (마이크로): '해당 우편번호에서 '제과점'을 검색하여 포화 상태인지 확인할 수 있나요?'
에이전트는 지도 도구 모음의 search places 도구를 사용하여 이 질문에 답변해야 합니다.
시도해 보기 다음 샘플 질문을 확인하여 ADK 에이전트의 작동 방식을 알아보세요.
- '로스앤젤레스에 네 번째 제과점을 열고 싶습니다. 아침에 활동이 많은 동네가 필요합니다. '아침' 도보 이동 점수가 가장 높은 우편번호를 찾아 주세요.'
- '해당 우편번호에서 '제과점'을 검색하여 포화 상태인지 확인할 수 있나요? 너무 많으면 '스페셜티 커피' 매장을 확인하여 도보 이동을 포착할 수 있도록 근처에 위치할 수 있습니다.'
- '알겠습니다. 프리미엄 브랜드로 포지셔닝하고 싶습니다. LA 메트로 지역에서 '사워도우 빵'에 부과되는 최대 가격은 얼마인가요?'
- '이제 2025년 12월의 수익 예측을 원합니다. 판매 내역을 살펴보고 '사워도우 빵'의 실적이 가장 좋은 매장의 데이터를 가져옵니다. 2025년 12월의 예측을 실행하여 판매할 수량을 추정합니다. 그런 다음 찾은 프리미엄 가격보다 약간 낮은 가격 (18달러 사용)을 사용하여 예상 총수익을 계산합니다.'
- '임대료를 충당할 수 있습니다. 마지막으로 물류를 확인해 보겠습니다. 제안된 지역에서 가장 가까운 'Restaurant Depot'을 찾고 매일 재고 보충을 위한 운전 시간이 30분 미만인지 확인합니다.'
에이전트 테스트를 완료하면 Cloud Shell 터미널에서 Ctrl+C를 눌러 ADK 웹 인터페이스를 종료할 수 있습니다.
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 및 지도)에 연결했습니다.
- 통합 추론: 두 개의 서로 다른 도메인의 통계를 전략적으로 결합하여 비즈니스 문제를 해결할 수 있는 단일 에이전트를 빌드했습니다.