1. 소개
이 Codelab에서는 에이전트 개발 키트 (ADK)를 사용하여 여행 계획 에이전트를 빌드하고 Google 지도로 그라운딩합니다. Google 지도의 실제 데이터를 활용하여 에이전트에게 경치 좋은 경로와 레스토랑 추천을 생성하도록 프롬프트합니다.
실습할 내용
- 에이전트 시작 패키지 를 사용하여 에이전트 프로젝트를 초기화합니다.
- Google 지도 그라운딩 도구를 사용하도록 에이전트를 구성합니다.
- 웹 인터페이스를 사용하여 로컬에서 결과 에이전트를 테스트합니다.
필요한 항목
- 웹브라우저(예: Chrome)
- 결제가 사용 설정된 Google Cloud 프로젝트
이 Codelab은 Python 및 Google Cloud에 어느 정도 익숙하지만 전문가 수준은 아닌 중급 개발자를 대상으로 합니다.
2. 시작하기 전에
Google Cloud 프로젝트 만들기
- Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
- Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다. 프로젝트에 결제가 사용 설정되어 있는지 확인하는 방법을 알아보세요.
Cloud Shell 시작
- 인증 확인
gcloud auth list
- 프로젝트 확인하기
gcloud config get project
- 필요한 경우 설정합니다.
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
API 사용 설정
이 명령어를 실행하여 필요한 모든 API를 사용 설정합니다.
gcloud services enable \
aiplatform.googleapis.com
3. 에이전트 시작 패키지 설치
ADK 프로젝트를 시작하는 가장 쉬운 방법은 에이전트 시작 패키지를 사용하는 것입니다. Google Cloud 에이전트 시작 패키지는 Google Cloud에서 프로덕션 준비가 완료된 생성형 AI 에이전트의 개발 및 배포를 가속화하도록 설계된 오픈소스 명령줄 인터페이스 (CLI) 도구입니다.
uv가 설치되어 있는지 확인한 후 create 명령어를 실행하여 새 에이전트 프로젝트를 초기화합니다.
uvx agent-starter-pack create
- 메시지가 표시되면 다음 옵션을 제공하여 React 프런트엔드로 로컬 개발을 위한 프로젝트를 구성합니다.
- 에이전트 템플릿:
adk(간단한 React 에이전트) - 배포:
none(현재 클라우드 배포 사용 중지됨) - 리전:
us-central1
그러면 기본 에이전트 로직, 테스트, GEMINI.md 가이드가 포함된 프로젝트 디렉터리 구조가 생성됩니다. 새 디렉터리로 이동합니다.
cd my-agent
4. 그라운딩 구성
에이전트 시작 패키지는 AI 지원 코딩 도구에 프로젝트 관리 방법을 안내하는 GEMINI.md 파일을 생성합니다. Google 지도 그라운딩 문서를 포함하도록 업데이트할 예정입니다.
- 편집기에서
GEMINI.md를 엽니다. ## Reference Documentation섹션 아래에 다음 참조 링크를 추가합니다.
- **Google Maps Grounding**: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-maps
이 컨텍스트는 AI 코딩 어시스턴트가 그라운딩 기능을 이해하는 데 도움이 됩니다.
5. 에이전트 업데이트
이제 Google 지도 그라운딩 도구가 포함된 여행 계획 도구 역할을 하도록 에이전트를 구성합니다.
app/agent.py파일을 엽니다.app/agent.py의 전체 콘텐츠를 다음 코드로 바꿉니다.
"""Agent application for the itinerary planner codelab."""
import os
import google.auth
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.adk.tools import google_maps_grounding
from google.genai import types
# Authenticate and set environment variables
_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
# Define the root agent
root_agent = Agent(
name="itinerary_planner_agent",
model=Gemini(
model="gemini-2.5-flash",
retry_options=types.HttpRetryOptions(attempts=3),
),
instruction=(
"You are an itinerary planner agent. Help users plan their trips by"
" recommending restaurants and scenic routes. Use the"
" google_maps_grounding tool to get both restaurant recommendations and"
" route recommendations based on user preferences. When calling for"
" restaurant recommendation, prompt the tool to tell you about the vibe"
" of the place. When calling for routes with multiple legs, describe"
" each of those legs with a brief sentence. Always describe the key"
" landmarks along the route in one brief sentence."
),
# Add the Google Maps Grounding tool to the agent
tools=[google_maps_grounding],
)
app = App(
root_agent=root_agent,
name="app",
)
이 코드는 google_maps_grounding 도구를 사용하여 장소 및 경로에 관한 최신 정보를 가져오는 gemini-2.5-flash 기반 에이전트를 구성합니다.
사용 가능한 모든 모델을 보려면 Vertex AI 문서를 참고하세요.
6. 에이전트 실행
에이전트 로직이 준비되면 로컬 웹 인터페이스에서 테스트해 보세요.
my-agent디렉터리의 루트에서 다음 명령어를 실행하여 웹 앱을 시작합니다.
uv run adk web
또는 가상 환경을 사용하는 경우:
adk web
- 브라우저에서 터미널 출력에 제공된 URL을 엽니다.
- 에이전트에게 질문하여 테스트합니다. 예를 들면 다음과 같습니다.
- "좋은 이탈리아 레스토랑을 포함하여 샌프란시스코에서 1일 여행 계획을 세워 주세요."
- "도쿄를 방문할 예정인데, 아늑한 분위기의 평점이 높은 라멘 맛집과 흥미로운 역사적 랜드마크가 포함된 여행 계획을 세워 주시겠어요?"
Google 지도에서 직접 가져온 실제 리뷰와 경로 설명으로 보강된 상세한 여행 계획과 유사한 출력이 표시됩니다.
7. 코드에서 그라운딩 확인
에이전트가 지도 그라운딩을 성공적으로 사용하고 있는지 프로그래매틱 방식으로 확인하려면 지도 관련 메타데이터의 응답 이벤트를 검사하면 됩니다.
테스트 스크립트에서와 같이 에이전트를 실행하면 에이전트가 grounding_metadata가 포함된 이벤트를 생성합니다. 이 메타데이터 내에서 grounding_chunks를 반복하고 maps 속성을 확인할 수 있습니다.
다음은 자동 테스트에서 사용할 수 있는 것과 유사하게 maps 속성을 확인하는 방법을 보여주는 예입니다.
async for event in runner.run_async(
user_id="test_user",
session_id=session.id,
new_message=content,
):
if event.grounding_metadata:
if event.grounding_metadata.grounding_chunks:
for chunk in event.grounding_metadata.grounding_chunks:
# Check for the maps attribute to confirm maps grounding
if hasattr(chunk, "maps") and chunk.maps:
print("SUCCESS: Maps grounding chunks detected in the response!")
8. 인코딩된 다중선 추출
그라운딩이 발생했는지 확인하는 것 외에도 경로와 같은 특정 데이터를 추출할 수 있습니다. 지도 그라운딩 도구는 경로 정보를 반환할 때 지도 프런트엔드에서 경로를 렌더링하는 데 사용할 수 있는 '인코딩된 다중선'을 포함하는 경우가 많습니다.
grounding_chunks의 maps 속성 내에서 텍스트를 확인하여 이 다중선을 찾을 수 있습니다. 다음은 이를 감지하는 방법의 예입니다.
async for event in runner.run_async(
user_id="test_user",
session_id=session.id,
new_message=content,
):
if event.grounding_metadata:
if event.grounding_metadata.grounding_chunks:
for chunk in event.grounding_metadata.grounding_chunks:
# Extract the encoded polyline from the maps chunk text
if (
hasattr(chunk, "maps")
and chunk.maps
and hasattr(chunk.maps, "text")
and chunk.maps.text
and "Encoded Polyline" in chunk.maps.text
):
print("SUCCESS: Encoded Polyline detected in the response!")
9. 삭제
Google Cloud 계정에 지속적으로 비용이 청구되지 않도록 하려면 이 Codelab 중에 생성된 리소스를 삭제합니다.
- 이 Codelab을 위해 전용 프로젝트를 만든 경우 전체 프로젝트를 삭제합니다.
gcloud projects delete $PROJECT_ID
기존 프로젝트를 사용하고 유지하려는 경우 에이전트가 로컬에서 실행되고 사용된 API가 서버리스이므로 삭제할 특정 리소스가 없습니다.
10. 축하합니다
축하합니다. 여행 계획 에이전트를 성공적으로 빌드하고 Google 지도 통계를 사용하여 그라운딩했습니다.
학습한 내용
- 에이전트 시작 패키지를 사용하여 새 에이전트를 스캐폴딩하는 방법
- ADK 에이전트 정의에 그라운딩 도구를 추가하는 방법
- 기본 제공 웹 실행기를 사용하여 ADK 에이전트를 테스트하는 방법
다음 단계
- 다른 ADK 도구 및 통합 패턴 살펴보기