지도 환경 에이전트 도구

지도 환경 에이전트 도구(이전 명칭: Maps Grounding Lite)는 모델 컨텍스트 프로토콜(MCP) 및 REST 지원을 통해 Google 지도의 신뢰할 수 있는 지리 공간 데이터로 AI 애플리케이션을 그라운딩하는 Google Maps Platform 서비스입니다. 이 도구를 사용하면 LLM이 장소, 날씨, 공기질, 꽃가루, 경로 데이터에 액세스할 수 있습니다. 다른 도구는 위치 이름과 Google 지도 URL을 장소 ID로 변환합니다. MCP 서버를 지원하는 모든 도구에서 MCP 서버를 사용 설정하여 지도 환경 에이전트 도구를 사용해 볼 수 있습니다. 각 도구를 REST 메서드로 호출할 수도 있습니다. 자세한 내용은 REST로 도구 호출을 참조하세요.

지도 환경 에이전트 도구는 Essentials와 Pro라는 두 가지 SKU가 있는 하나의 제품입니다. Pro 옵션을 사용하지 않는 한 모든 요청은 Essentials로 청구됩니다. Pro 옵션은 경로를 따라 장소 검색, 확장된 장소 세부정보, 검색당 더 많은 장소, 경로당 더 많은 중간 경유지, 실시간 교통정보를 사용한 경로, 꽃가루 예보, 과거 공기질을 추가합니다. 두 SKU 모두 동일한 도구, MCP 서버, REST 메서드, 사용자 인증 정보를 사용합니다. 자세한 내용은 Essentials 및 Pro를 참고하세요.

도구

지도 환경 에이전트 도구를 사용하면 LLM이 다음 Google 지도 기능에 액세스할 수 있습니다.

  • 장소 검색: 장소에 관한 정보를 요청하고 AI 생성 요약을 확인합니다. 응답에는 요약에 있는 각 장소의 장소 ID, 위도/경도 좌표, Google 지도 링크도 포함됩니다. 장소 ID와 위도/경도 좌표를 다른 Google Maps Platform API와 함께 사용하여 지도에 장소를 표시할 수 있습니다. 추가 비용 없이 장소 UI 키트를 사용하여 이러한 장소를 표시하려면 에이전트 데이터 시각화 토큰(프리뷰)을 사용하세요. Pro를 사용하면 리뷰 통계와 같은 확장된 장소 세부정보를 요청할 수 있으며 요청당 최대 10개의 장소를 요청할 수 있습니다.
  • 경로를 따라 검색: compute_routes, route_endpoints 또는 encoded_polyline의 retrieval_token를 사용하여 지정된 이동 경로를 따라 장소를 찾고 AI 생성 요약, 장소 세부정보, 우회 거리 및 이동 시간, 에이전트 데이터 시각화 토큰(미리보기)을 가져옵니다. 모든 search_along_route 요청은 Pro SKU로 청구됩니다.
  • 날씨 조회: 날씨(현재 상태, 24시간 시간별 기록, 최대 10일 시간별 및 일일 예보) 및 현재 또는 최대 4일 예보 공기질을 포함한 위치의 환경 조건을 요청합니다. Pro를 사용하면 최대 5일간의 일일 꽃가루 예보(식물 종 세부정보 포함)와 최대 30일간의 시간별 공기질 기록을 요청할 수도 있습니다.
  • 경로 계산: 출발지와 목적지 사이의 경로를 요청하고(원하는 경우 중간 경유지 포함) 경로의 거리, 소요 시간, search_along_route에 전달할 수 있는 DRIVE 경로의 retrievalToken를 반환합니다. Pro를 사용하면 경로에서 실시간 교통상황을 고려하고 더 많은 중간 경유지를 포함할 수 있습니다.

  • 이름 확인 및 지도 URL 확인: 위치 이름, 주소, Google 지도 URL을 장소 ID로 확인합니다. 자세한 내용은 Resolution API를 참조하세요.

MCP 서버를 사용 설정하면 LLM이 도구를 호출하여 이러한 데이터 유형에 대한 그라운딩 정보를 가져올 수 있습니다. LLM은 이 정보를 컨텍스트로 사용할 수 있습니다. 하지만 최종 대답에는 MCP 서버가 반환한 정확한 정보가 포함되지 않을 수 있습니다. 생성된 대답의 정확성을 확인합니다.

Essentials 및 Pro

Essentials와 Pro는 동일한 제품의 두 SKU이며 별도의 제품이나 요금제가 아닙니다. Pro 옵션을 사용하는 경우 Pro로 청구됩니다. 다른 모든 요청은 Essentials에 따라 청구됩니다. Pro 옵션은 도구 요청의 일반 필드이므로 LLM이 대신 사용할 수 있습니다. 에이전트는 동일한 대화에서 두 SKU를 모두 사용할 수도 있습니다. 예를 들어 에이전트는 Essentials를 사용하여 명소 근처의 커피숍을 찾을 수 있습니다. 그런 다음 Pro를 사용하여 시그니처 음료와 좌석에 관한 후속 질문에 답변할 수 있습니다. Pro를 위한 별도의 MCP 서버, 엔드포인트 또는 사용자 인증 정보는 없습니다.

Essentials, Pro, Google 지도 기반 그라운딩 비교

Google 지도 기반 그라운딩은 별도의 제품입니다. Gemini API, Google AI Studio, Gemini Enterprise Agent Platform의 Gemini 모델에 기본 제공됩니다. 모델은 Google 지도에 쿼리할 시점을 결정하고 인용이 포함된 그라운딩된 답변을 반환합니다. Gemini를 기반으로 빌드하고 모델이 그라운딩을 처리하도록 하려면 Google 지도 기반 그라운딩을 선택하세요. 다른 모델 또는 에이전트 프레임워크를 사용하거나 각 도구 호출을 직접 제어하려면 지도 환경 에이전트 도구를 선택하세요.

다음 표에서는 Essentials SKU, Pro SKU, Google 지도 기반 그라운딩을 비교합니다.

지도 환경 에이전트 도구 Google 지도를 사용한 그라운딩
Essentials SKU
(이전 명칭: Maps Grounding Lite)
Pro SKU
요청 청구 방식 Pro 옵션을 사용하지 않는 각 도구 요청 모든 search_along_route 요청 또는 Pro 옵션을 사용하는 다른 도구에 대한 요청 Pro SKU로 청구되는 항목을 참조하세요. 플랫폼 및 모델에 따라 각 Google 지도 쿼리 또는 그라운딩된 프롬프트
모델 및 플랫폼 MCP를 지원하거나 REST API를 호출할 수 있는 모든 모델 또는 에이전트 프레임워크 두 SKU 모두에 동일한 도구 세트와 사용자 인증 정보 사용 Gemini API, Google AI Studio, Gemini Enterprise Agent Platform의 Gemini 모델
도구가 반환하는 항목 핵심 정보: 검색당 최대 5개 장소의 장소 세부정보, 실시간 교통정보가 없는 경로 거리 및 소요 시간, 현재 날씨 및 일기예보(24시간 시간별 날씨 기록 포함), 현재 또는 예측 공기질 Essentials의 모든 기능과 더불어 우회 시간 및 거리가 포함된 경로상의 장소, 확장된 장소 세부정보(예: 리뷰에서 얻은 유용한 정보), 검색당 최대 10개의 장소, 실시간 교통정보가 포함된 경로, 최대 25개의 중간 경유지, 꽃가루 예보, 최대 30일간의 과거 공기질 정보 리뷰에서 가져온 장소 세부정보 및 통계, 실시간 교통정보가 포함된 경로 정보
요청 예 사실 및 물류 관련 질문: 매장 또는 비즈니스 찾기, 영업시간, 주소, 거리 또는 이동 시간 추정치, 현재 날씨, 10일 일기예보, 현재 또는 4일 공기질 예보 주관적이거나 광범위하거나 전문적인 질문: 경로를 따라 있는 장소, 분위기, 대표 요리, 방문자 팁, 6~10개 장소 비교, 현재 교통 상황에서의 이동 시간, 꽃가루 및 알레르기 예보, 지난 30일간의 공기질 기록 Gemini의 대화형 검색, 여행 일정 계획, 지역 탐색
장소 UI 키트 시각화 에이전트 데이터 시각화 토큰(프리뷰)에 추가 비용 없이 포함됨 별도로 청구됩니다.
월별 무료 사용량 요청 10,000개 요청 5,000개 플랫폼과 모델에 따라 다릅니다. 예를 들어 Gemini API에서 Gemini 3 이상 모델에는 월 5,000개의 검색어가 무료로 포함됩니다. 그 이후에는 검색어 1,000개당 14달러가 청구됩니다.
사용한 만큼만 지불하는 가격 요청 1,000회당 $7.00(대량 구매 할인 적용) 요청 1,000건당 $14.00(대량 할인 적용)
구독을 통한 절감 혜택 Essentials 및 Pro 요금제에 포함됨 Pro 요금제에 포함됨 사용 불가
시작하기 두 SKU 모두에 대해 하나의 설정: MCP 서버를 사용하도록 LLM 구성 또는 REST로 도구 호출을 참조하세요. Gemini API 또는 Agent Platform

이러한 옵션은 이동 수단, 출발 및 도착 시간, 대체 경로, 경로 다중선, 날씨 조회, 현재 및 예측 공기질 조회(오염 물질 농도 및 현지 AQI 척도 포함), 날씨 단위 시스템, Resolution API 등 두 SKU에서 동일한 방식으로 작동합니다. 요청이 청구되는 SKU는 변경되지 않습니다.

Pro SKU로 청구되는 항목

다음 표에는 Essentials에 포함된 기능과 Pro SKU가 필요한 기능이 요약되어 있습니다.

도구 기능 Essentials Pro
장소 검색 요청당 장소 수 최대 5개 6~10(page_size: 6~10)
검색 요약의 확장된 장소 세부정보(리뷰에서 얻은 유용한 정보, 메뉴 하이라이트, 분위기, 장소의 혼잡도, 방문자 팁, 근접성 검색어의 거리 또는 이동 시간) 사용 불가 include_extended_details에서 사용 가능
경로를 따라 검색 경로를 따라 있는 장소, 우회 거리 및 이동 시간, 선택사항인 확장된 장소 세부정보 또는 교통정보를 반영한 우회 시간 사용 불가 모든 요청
경로 계산 라우팅 환경설정 실시간 트래픽을 고려하지 않음 ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL를 사용하여 실시간 교통정보 또는 대중교통 경로의 실시간 대중교통 데이터를 고려합니다.
경로당 중간 경유지 최대 10명 11~25개(intermediate_waypoints 11개 이상)
날씨 조회 날씨 현재 날씨, 시간별 및 일별 예보(최대 10일), 최대 24시간의 시간별 기록(capabilities의 WEATHER 또는 capabilities, weather_options, air_quality_options, language_code를 생략하는 기존 요청) Pro 옵션 없음(모든 WEATHER 데이터가 Essentials에 포함됨)
공기질 현재 상태, 오늘의 하루 시간별 결과, 최대 4일의 시간별 예보(capabilities의 AIR_QUALITY) 응답에서 반환되는 경우 최대 30일 전의 과거 공기질(capabilities의 AIR_QUALITY, 오늘 이전의 date 또는 위치 시간대의 과거 hour)
꽃가루 사용 불가 응답에 반환되는 경우 최대 5일의 일일 꽃가루 예측 및 식물 종 세부정보(capabilities의 POLLEN)
Resolution API Pro 옵션 없음 모든 요청은 Places API 텍스트 검색 Essentials(ID만 해당) SKU에 따라 무료로 청구됩니다.

각 기능을 사용 설정하는 요청 옵션은 장소 검색, 경로를 따라 검색, 경로 계산, 날씨 조회를 참고하세요.

Pro 사용 제어

프로 옵션은 search_places, compute_routes, lookup_weather에서 기본적으로 사용 중지되어 있습니다. 사용자의 요청에 따라 LLM이 이를 설정하거나 search_along_route를 호출하며, 도구 설명 또는 요청 사항에서 이를 허용합니다. 도구 설명은 모델에 어떤 옵션이 더 비싸고 언제 사용해야 하는지 알려줍니다. 5를 초과하는 page_size, 확장된 장소 세부정보, 10개 이상의 중간 경유지, 교통정보를 반영한 경로, search_along_route입니다. REST를 사용하여 도구를 호출하는 경우 코드에서 모든 옵션을 설정합니다. 비용을 관리하려면 다음 안내를 따르세요.

  • 모델에 Pro 옵션이 적합한 경우를 알려줍니다. 예: '사용자가 리뷰, 메뉴 또는 분위기에 대해 질문하는 경우에만 include_extended_details를 설정합니다.' 또는 '사용자가 현재 이동 시간을 요청하는 경우에만 ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL를 사용하세요.' 또는 '사용자가 경로를 따라 장소를 요청하는 경우에만 search_along_route를 호출합니다.' 또는 '사용자가 꽃가루, 알레르기 또는 과거 공기질에 대해 문의하는 경우에만 POLLEN 또는 과거 date 또는 hour가 포함된 AIR_QUALITY를 포함합니다.'
  • 에이전트를 Essentials SKU로 유지하려면 모델에 search_along_route를 호출하거나 Pro 옵션을 사용하지 않도록 지시합니다. Pro 옵션은 include_extended_details, 5개 이상의 page_size, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, 10개 이상의 중간 경유지, capabilities의 POLLEN, capabilities의 AIR_QUALITY가 있는 이전 date 또는 hour입니다. MCP 클라이언트가 도구 또는 도구 인수를 제한할 수 있는 경우 도구 구성에서 search_along_route 및 해당 인수 값을 차단할 수도 있습니다.
  • 결제 보고서에서 Maps Grounding Pro SKU를 모니터링하고 예산 알림을 설정합니다.

Resolution API

지도 환경 에이전트 도구는 Resolution API를 제공합니다. 자유 형식의 위치 텍스트와 URL을 구조화된 Google 지도 장소 식별자로 변환합니다. Resolution API는 MCP 서버에서 REST 메서드 및 도구로 사용할 수 있습니다.

  • 이름 확인(REST, MCP): Google 지도에서 위치 이름 또는 주소 배치를 특정 장소 항목으로 확인합니다. 이 도구는 비정형 사용자 쿼리를 안정적인 장소 ID로 그라운딩하는 데 도움이 됩니다.
  • 지도 URL 확인(REST, MCP): Google 지도 URL 배치를 특정 장소 항목으로 확인합니다. 지원되는 형식에는 표준 장소 URL과 단축 URL이 포함됩니다.

반환된 장소 ID를 다른 Google Maps Platform API와 함께 사용할 수 있습니다. 각 응답에는 확인된 장소를 Google 지도에 목록으로 저장하는 링크도 포함됩니다.

자세한 내용은 Maps Tools Resolution API를 참고하세요.

샘플 앱 사용해 보기(새 탭에서 열기)

결제 및 할당량

청구 방식

Google Maps Platform 사용한 만큼만 지불 가격 책정 모델을 사용하면 지도 환경 에이전트 도구의 사용량이 요청별로 계산됩니다. 각 요청은 하나의 결제 이벤트를 나타냅니다. 사용량은 각 제품 SKU에 따라 추적됩니다. 청구서에는 총 청구 금액 외에 각 SKU의 항목이 표시됩니다. 자세한 내용은 보고 개요를 참고하세요.

MCP 서버를 통해 또는 REST를 사용하는 각 장소 검색, 경로 검색, 경로 계산 또는 날씨 조회 요청은 Maps Grounding Essentials 또는 Maps Grounding Pro라는 하나의 SKU로 청구됩니다. 모든 search_along_route 요청과 Pro 옵션을 사용하는 모든 요청은 Pro SKU로 청구됩니다. 요청은 두 SKU 모두에서 청구되지 않으며 요청의 Pro 옵션 수에 따라 요금이 변경되지 않습니다. 각 도구의 SKU를 결정하는 기능과 옵션은 Pro SKU로 청구되는 항목을 참조하세요.

지도 그라운딩 Essentials 요청은 매월 처음 10,000개의 요청 이후 요청 1,000개당 $7.00의 요금이 청구됩니다. 지도 그라운딩 프로 요청은 매월 처음 5,000개 요청 이후 요청 1,000개당 $14.00로 청구됩니다. 두 SKU 모두 월별 사용량이 많을수록 대량 구매 할인이 적용됩니다.

가격 책정 세부정보는 기본 가격 책정표 및 인도 가격 책정표를 참조하세요.

Resolution API 요청(ResolveNames 및 ResolveMapsUrls)은 Places API 텍스트 검색 Essentials(ID만 해당) SKU에 따라 무료로 청구됩니다.

장소 UI 키트를 사용하여 search_places 또는 search_along_route 응답의 장소를 표시하는 경우 에이전트 데이터 시각화 토큰(프리뷰)을 사용하면 해당 장소 UI 키트 요청에 대한 요금이 청구되지 않습니다.

Essentials SKU 사용량은 Essentials 및 Pro 정기 결제 할인 요금제에 포함됩니다. Pro SKU 사용량은 Pro 요금제에 포함됩니다.

할당량

지도 환경 에이전트 도구에서 제공하는 도구 및 API에는 다음 할당량이 적용됩니다.

  • 장소 검색: 프로젝트당 분당 쿼리 300개
  • 경로를 따라 검색: 프로젝트당 분당 쿼리 300개
  • 날씨 조회: 프로젝트당 분당 300개 쿼리
  • 경로 계산: 프로젝트당 분당 쿼리 300개
  • 이름 확인: 프로젝트당 분당 쿼리 600개
  • 지도 URL 확인: 프로젝트당 분당 600개의 쿼리

할당량은 도구별로 계산되며 Essentials 및 Pro SKU에서 공유됩니다. Pro 요청은 동일한 도구에 대한 Essentials 요청과 동일한 할당량을 사용합니다.

각 Resolution API 요청은 포함된 항목 수와 관계없이 하나의 쿼리로 계산됩니다.

정책 및 서비스 약관

지도 환경 에이전트 도구에는 서비스별 약관을 비롯한 Google Maps Platform 서비스 약관이 적용됩니다. 이 섹션에서는 호환되는 LLM 및 소스 저작자 표시를 포함하여 지도 환경 에이전트 도구의 추가 사용 요구사항을 설명합니다. 요구사항은 요청이 청구되는 SKU와 관계없이 모든 결과에 적용됩니다.

호환되는 LLM 요구사항

Google Maps Platform 서비스 약관을 준수하는 LLM에서만 지도 환경 에이전트 도구를 사용할 수 있습니다.

예를 들어 Google 지도 콘텐츠가 사용자가 선택한 LLM에 의해 캐시되거나, 저장되거나, LLM을 개선하는 데 사용되지 않도록 할 책임은 사용자에게 있습니다. 지도 환경 에이전트 도구를 사용하기 전에 지도 환경 에이전트 도구와 함께 사용하려는 모델의 서비스 약관을 검토해야 합니다. 모델에 입력된 데이터를 모델 학습 또는 개선에 사용하는 모델과 함께 지도 환경 에이전트 도구를 사용해서는 안 됩니다. 모델 사용이 서비스별 약관을 포함한 Google Maps Platform 서비스 약관의 Google 지도 콘텐츠 제한사항을 완전히 준수하는지 확인할 책임은 사용자에게 있습니다.

Google 지도 소스의 저작자 표시 요구사항

지도 환경 에이전트 도구의 각 도구 응답에는 소스가 포함됩니다. 지도 환경 에이전트 도구의 결과를 표시할 때는 연결된 Google 지도 소스를 포함하고 다음 요구사항을 충족해야 합니다.

  • Google 지도 소스는 해당 소스를 뒷받침하는 생성된 콘텐츠 직후에 따라와야 합니다. 이렇게 생성된 콘텐츠를 그라운딩 출력이라고도 합니다.
  • Google 지도 소스는 단일 사용자 상호작용 내에서 확인 가능해야 합니다.

장소 검색 및 경로 검색 도구의 소스

search_places 도구 places 필드와 search_along_route 도구 results[].place 필드는 summary를 지원하는 소스를 제공합니다. 각 장소에 대해 다음 메타데이터가 반환됩니다.

  • place(리소스 이름)
  • id
  • location
  • googleMapsLinks
  • attribution

각 장소에 대해 다음 요구사항을 충족하는 링크 미리보기를 생성해야 합니다.

이러한 요구사항은 리뷰의 통계와 같은 Pro의 확장된 장소 세부정보가 포함된 요약에도 적용됩니다. summary는 places 또는 results의 항목에 매핑되는 0 기반 색인(예: [0])을 사용하여 각 장소를 인용합니다. 각 장소에는 Google 지도에서 장소의 리뷰로 연결되는 googleMapsLinks.reviewsUrl도 포함됩니다. 사용자는 이 링크를 따라가서 통계의 기반이 되는 리뷰를 확인할 수 있습니다.

음성 중심 인터페이스

앱이 음성으로 지도 환경 에이전트 도구 결과를 표시하는 경우 음성 우선 인터페이스 요구사항도 충족해야 합니다. 요약하면 다음과 같습니다.

  • 소싱: 음성 대화의 축어적 기록을 보여주는 컴패니언 UI에 Google 지도 소스를 표시합니다.
  • 적극적인 공개: 상호작용 시 AI 생성 콘텐츠에 Google 지도의 정보가 포함될 수 있음을 사용자에게 알립니다. 또한 컴패니언 UI에서 자세한 출처를 확인할 수 있다고 알려줍니다. 화면에서 또는 음성으로 이 작업을 수행할 수 있습니다.
  • 영구 공개: AI 생성 콘텐츠에 Google 지도 콘텐츠가 포함될 수 있다는 설명을 음성 설정 메뉴 등에 영구적으로 유지합니다.
  • 사용자 문의: 콘텐츠의 출처에 관한 사용자의 질문에 정확하게 답변하고 자세한 내용은 컴패니언 UI를 안내합니다.

MCP 서버를 사용하도록 LLM 구성

지도 환경 에이전트 도구를 사용하려면 지도 환경 에이전트 도구 API 서비스가 사용 설정된 Google Cloud 프로젝트가 필요합니다. API 키 또는 OAuth 클라이언트 ID도 필요합니다. 그런 다음 MCP 서버에 액세스하도록 LLM을 구성할 수 있습니다. MCP 서버는 스트리밍 가능한 HTTP 전송을 사용합니다.

Google Cloud 프로젝트에서 지도 환경 에이전트 도구를 사용 설정합니다.

프로젝트에서 API를 사용 설정하려면 다음 안내를 따르세요.

  1. Google Cloud 콘솔에서 지도 환경 에이전트 도구에 사용할 프로젝트를 선택합니다.
  2. Google Cloud 콘솔에서 프로젝트의 결제를 설정합니다.
  3. Google Cloud 콘솔 API 라이브러리에서 지도 환경 에이전트 도구를 사용 설정합니다.

API 키를 사용하여 인증

지도 환경 에이전트 도구에서 기존 API 키를 사용하거나 새 API 키를 만들 수 있습니다. 어느 쪽이든 Google Cloud 프로젝트와 키 모두에서 지도 환경 에이전트 도구 API 서비스를 사용 설정합니다.

API 키를 사용하여 인증하려면 다음 안내를 따르세요.

  1. Google Maps Platform 시작하기의 단계에 따라 API 키를 만들거나 구성합니다.
  2. X-Goog-Api-Key 헤더를 사용하여 키를 MCP 서버에 전달합니다. 이를 LLM의 MCP 도구 구성에서 커스텀 HTTP 헤더로 지정해야 합니다.

OAuth를 사용하여 인증

OAuth 사용자 인증 정보를 만들고 MCP 호스트 또는 MCP 서버 애플리케이션에 전달하여 OAuth를 사용하여 인증할 수 있습니다.

OAuth를 사용하여 인증하려면 다음 안내를 따르세요.

  1. Google Cloud 콘솔에서 지도 환경 에이전트 도구에 사용할 프로젝트를 선택합니다.
  2. API 및 서비스 메뉴에서 사용자 인증 정보를 선택합니다.
  3. 상단 메뉴에서 사용자 인증 정보 만들기 > OAuth 클라이언트 ID를 선택합니다.
  4. 프로젝트에 구성된 동의 화면이 없으면 동의 화면 구성을 클릭하고 화면에 표시된 안내를 따릅니다.
  5. 측정항목 섹션에서 OAuth 클라이언트 만들기를 클릭합니다.
  6. OAuth 클라이언트 ID 만들기 화면에서 애플리케이션 유형을 선택하고 클라이언트 ID의 이름을 입력합니다.
  7. 애플리케이션 유형과 관련된 추가 세부정보를 지정합니다. 예를 들어 웹 애플리케이션을 만드는 경우 브라우저 및 서버 요청에 대해 승인된 URI를 추가합니다.
  8. 클라이언트가 생성되면 클라이언트 ID와 보안 비밀을 저장합니다.
  9. MCP 호스트 또는 MCP 서버 애플리케이션을 구성할 때 OAuth 클라이언트 ID와 보안 비밀번호를 전달합니다. 또한 https://www.googleapis.com/auth/maps-platform.mapstools 범위를 요청해야 합니다.

자세한 내용은 OAuth 2.0을 사용하여 Google API에 액세스하기를 참조하세요.

지도 환경 에이전트 도구 MCP 서버에 액세스하도록 LLM 구성

지도 환경 에이전트 도구 서비스를 사용 설정하고 사용자 인증 정보를 만든 후 LLM이 MCP 서버에 액세스하도록 구성할 수 있습니다. LLM의 MCP 구성 문서를 따르고 MCP 서버 URL(https://mapstools.googleapis.com/mcp)을 사용합니다.

자세한 내용은 AI 애플리케이션에서 MCP 구성을 참조하세요.

Gemini CLI로 지도 환경 에이전트 도구 구성

이 섹션에서는 Gemini CLI를 사용하여 지도 환경 에이전트 도구 MCP 서버를 구성하는 방법의 예시를 제공합니다. 자세한 내용은 Gemini CLI를 사용하는 MCP 서버를 참조하세요.

  1. Gemini CLI를 설치한 후 gemini mcp add를 실행하여 MCP 서버를 구성합니다.

    gemini mcp add -s user -t http -H 'X-Goog-Api-Key: API_KEY' maps-experience-agent-tools-mcp https://mapstools.googleapis.com/mcp
    

    구성이 성공하면 서버가 사용자 설정에 추가되었다는 확인 메시지가 표시됩니다.

  2. 서버가 작동하는지 확인하려면 /mcp list 명령어를 실행합니다.

    > /mcp list
    
    Configured MCP servers:
    
    maps-experience-agent-tools-mcp - Ready (6 tools)
    Tools:
    -   compute_routes
    -   lookup_weather
    -   resolve_maps_urls
    -   resolve_names
    -   search_along_route
    -   search_places
    
  3. CLI를 사용하여 지도에 물어보기 관련 질문을 시작합니다. 예를 들어 '마운틴뷰에 있는 레스토랑 추천해 줘'라고 입력하면 search_places 도구가 자동으로 호출됩니다.

에이전트 개발 키트(ADK)로 지도 환경 에이전트 도구 구성

이 섹션에서는 Python, Java 또는 TypeScript에서 에이전트 개발 키트(ADK)를 사용하여 MCP 서버를 구성하는 방법을 보여줍니다.

Python

이 예시의 전체 구현은 GitHub의 adk-samples 저장소에서 확인할 수 있습니다.

1단계: 지도 환경 에이전트 도구에 McpToolset를 사용하여 에이전트 정의

agent.py 파일을 수정합니다. YOUR_GOOGLE_MAPS_API_KEY를 실제 API 키로 바꿉니다.

# ./adk_agent_samples/mcp_agent/agent.py
import os
from google.adk.agents.llm_agent import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# Retrieve the API key from an environment variable or directly insert it.
GOOGLE_MAPS_API_KEY = os.getenv("GOOGLE_MAPS_API_KEY")
if not GOOGLE_MAPS_API_KEY:
    GOOGLE_MAPS_API_KEY = "YOUR_GOOGLE_MAPS_API_KEY_HERE"

if GOOGLE_MAPS_API_KEY == "YOUR_GOOGLE_MAPS_API_KEY_HERE":
    print("WARNING: GOOGLE_MAPS_API_KEY is not set.")

root_agent = Agent(
    model='gemini-flash-latest',
    name='travel_planner_agent',
    description='A helpful assistant for planning travel routes.',
    tools=[
        McpToolset(
            connection_params=StreamableHTTPConnectionParams(
                url="https://mapstools.googleapis.com/mcp",
                headers={
                    "X-Goog-Api-Key": GOOGLE_MAPS_API_KEY,
                    "Content-Type": "application/json",
                    "Accept": "application/json, text/event-stream"
                }
            )
        )
    ]
)
    
2단계: __init__.py가 있는지 확인하기

agent.py와 동일한 디렉터리에 __init__.py가 있는지 확인합니다.

from . import agent
    
3단계: adk web 실행 및 상호작용
  1. 환경 변수 설정:
    터미널에서 Google 지도 API 키를 환경 변수로 설정합니다.
    export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
            
  2. adk web 실행:
    다음 명령어를 실행하여 ADK 웹 인터페이스를 시작합니다.
    adk web
            
  3. UI에서 상호작용:
    • travel_planner_agent을 선택합니다.
    • 다음과 같은 프롬프트를 사용해 보세요.
      • "내일 샌프란시스코에 있을 예정입니다. 날씨가 어때?"
      • "골든 게이트 공원 근처 커피숍 찾아 줘."
      • "GooglePlex에서 SFO까지 가는 길 알려 줘."

자바

Java에서 McpToolset를 초기화하는 에이전트를 정의합니다. 환경 변수를 사용하지 않는 경우 YOUR_GOOGLE_MAPS_API_KEY_HERE를 가져온 실제 API 키로 바꿉니다.

package agents;

import com.google.adk.agents.LlmAgent;
import com.google.adk.runner.InMemoryRunner;
import com.google.adk.sessions.SessionKey;
import com.google.adk.tools.mcp.McpToolset;
import com.google.adk.tools.mcp.StreamableHttpServerParameters;
import com.google.genai.types.Content;
import com.google.genai.types.Part;
import java.util.HashMap;
import java.util.Map;

public class MapsAgentCreator {
    public static void main(String[] args) {
        String googleMapsApiKey = System.getenv("GOOGLE_MAPS_API_KEY");
        if (googleMapsApiKey == null || googleMapsApiKey.trim().isEmpty()) {
            googleMapsApiKey = "YOUR_GOOGLE_MAPS_API_KEY_HERE";
            if ("YOUR_GOOGLE_MAPS_API_KEY_HERE".equals(googleMapsApiKey)) {
                System.out.println("WARNING: GOOGLE_MAPS_API_KEY is not set.");
            }
        }

        Map<String, String> headers = new HashMap<>();
        headers.put("X-Goog-Api-Key", googleMapsApiKey);
        headers.put("Content-Type", "application/json");
        headers.put("Accept", "application/json, text/event-stream");

        StreamableHttpServerParameters serverParams =
                StreamableHttpServerParameters.builder("https://mapstools.googleapis.com/mcp")
                        .headers(headers)
                        .build();

        try (McpToolset toolset = new McpToolset(serverParams)) {
            LlmAgent agent = LlmAgent.builder()
                    .model("gemini-flash-latest")
                    .name("travel_planner_agent")
                    .description("A helpful assistant for planning travel routes.")
                    .tools(toolset)
                    .build();

            System.out.println("Agent created: " + agent.name());

            InMemoryRunner runner = new InMemoryRunner(agent);
            String userId = "maps-user-" + System.currentTimeMillis();
            String sessionId = "maps-session-" + System.currentTimeMillis();
            String promptText =
                    "Please give me directions to the nearest pharmacy to Madison Square Garden.";

            SessionKey sessionKey = runner.sessionService()
                    .createSession(runner.appName(), userId, null, sessionId)
                    .blockingGet()
                    .sessionKey();
            System.out.println("Session created: " + sessionId + " for user: " + userId);

            Content promptContent = Content.fromParts(Part.fromText(promptText));
            System.out.println("\nSending prompt: \"" + promptText + "\" to agent...\n");

            runner.runAsync(sessionKey, promptContent)
                    .blockingForEach(event -> {
                        System.out.println("Event received: " + event.toJson());
                    });
        } catch (Exception e) {
            System.err.println("An error occurred: " + e.getMessage());
            e.printStackTrace();
        }
    }
}
    

TypeScript

TypeScript에서 MCPToolset를 초기화하는 에이전트를 정의합니다.

import 'dotenv/config';
import {LlmAgent, MCPToolset} from "@google/adk";

const googleMapsApiKey = process.env.GOOGLE_MAPS_API_KEY;
if (!googleMapsApiKey) {
    console.warn("WARNING: GOOGLE_MAPS_API_KEY is not set.");
    throw new Error(
        'GOOGLE_MAPS_API_KEY is not provided, please run "export GOOGLE_MAPS_API_KEY=YOUR_ACTUAL_KEY" to add that.'
    );
}

export const rootAgent = new LlmAgent({
    model: "gemini-flash-latest",
    name: "travel_planner_agent",
    description: "A helpful assistant for planning travel.",
    tools: [
        new MCPToolset({
            type: "StreamableHTTPConnectionParams",
            url: "https://mapstools.googleapis.com/mcp",
            transportOptions: {
                requestInit: {
                    headers: {
                        "X-Goog-Api-Key": googleMapsApiKey,
                        "Content-Type": "application/json",
                        "Accept": "application/json, text/event-stream"
                    }
                }
            }
        })
    ],
});
    

REST를 사용하여 도구 호출

지도 환경 에이전트 도구의 각 도구는 REST 메서드로도 사용할 수 있습니다. 모델의 자체 함수를 선언하거나, 모델이 설정할 수 있는 옵션을 선택하거나, 코드에서 기본값을 설정하는 등 도구를 자체 에이전트 또는 애플리케이션에 연결하려면 REST 메서드를 직접 호출합니다.

다음 표에는 각 도구의 REST 메서드가 나와 있습니다.

도구 REST 메서드
search_places POST https://mapstools.googleapis.com/v1:searchText
search_along_route POST https://mapstools.googleapis.com/v1:searchAlongRoute
lookup_weather POST https://mapstools.googleapis.com/v1:lookupWeather
compute_routes POST https://mapstools.googleapis.com/v1:computeRoutes
resolve_names POST https://mapstools.googleapis.com/v1:resolveNames
resolve_maps_urls POST https://mapstools.googleapis.com/v1:resolveMapsUrls

REST 요청은 해당 도구와 동일한 옵션을 사용하고 동일한 응답을 반환합니다. REST 요청 및 응답 본문에서 필드 이름은 카멜 표기법(lower camel case)을 사용합니다(예: text_query 대신 textQuery). REST 요청은 동일한 SKU로 청구되고, Pro 옵션에 동일한 규칙을 따르며, MCP 도구 호출과 동일한 할당량에 반영됩니다.

인증하려면 MCP 서버와 동일한 Google Cloud 프로젝트 및 사용자 인증 정보를 사용합니다. 설정 단계는 MCP 서버를 사용하도록 LLM 구성을 참고하세요. X-Goog-Api-Key 헤더에 API 키를 전달하거나 Authorization 헤더에 https://www.googleapis.com/auth/maps-platform.mapstools 범위가 있는 OAuth 액세스 토큰을 전달합니다.

다음 예시에서는 searchText 메서드를 호출합니다.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "coffee shops near Golden Gate Park"
}' \
"https://mapstools.googleapis.com/v1:searchText"

API_KEY를 내 API 키로 바꿉니다.

응답에는 search_places 도구 결과와 동일한 summary, places, contentToken 필드가 포함됩니다. 각 도구의 가이드에는 예시의 REST 버전이 표시됩니다.

의견 공유

지도 환경 상담사 도구에 관한 의견을 공유하려면 다음 양식을 사용하세요.