Việc xây dựng các tác nhân AI đánh dấu một bước tiến quan trọng trong quá trình phát triển phần mềm, giúp các hệ thống có thể thực hiện suy luận phức tạp và hoạt động độc lập hơn. Tuy nhiên, các mô hình nền tảng vận hành những hệ thống này vốn bị giới hạn bởi dữ liệu huấn luyện. Nếu không có bối cảnh bên ngoài, các mô hình này sẽ không nắm được thông tin về các điều kiện theo thời gian thực, chẳng hạn như thời tiết hiện tại bên ngoài, liệu một doanh nghiệp địa phương có đang mở cửa ngay bây giờ hay không, hoặc tuyến đường hiệu quả nhất để đến một điểm đến.
Tài liệu này trình bày chi tiết cách thu hẹp khoảng cách giữa lý luận tĩnh và thực tế động bằng cách cung cấp cho các tác nhân AI dữ liệu không gian địa lý đáng tin cậy từ Google Maps. Bạn sẽ tìm hiểu lý do tại sao việc căn cứ không gian lại quan trọng đối với các nhiệm vụ thực tế, cách Giao thức ngữ cảnh mô hình (MCP) đơn giản hoá việc tích hợp công cụ và cách xây dựng một tác nhân lập kế hoạch du lịch bằng Google Maps Grounding Lite MCP.
Tại sao tác nhân cần có dữ liệu cơ sở của Maps
Quá trình chuyển đổi từ phần mềm truyền thống sang quy trình làm việc dựa trên tác nhân là sự chuyển dịch từ kỹ thuật tất định sang điều phối xác suất. Chúng tôi đang chuyển từ những hệ thống chỉ biết thông tin sang những công cụ thực thi chủ động, có thể thực sự làm việc. Khi một ứng dụng vượt qua ranh giới đó và hành động trong thế giới thực, thì mức độ rủi ro về độ chính xác sẽ thay đổi hoàn toàn.
Mô hình ngôn ngữ lớn (LLM) hiểu logic, nhưng bộ nhớ trong của chúng là một bản tổng quan nhanh về quá khứ. Ví dụ: nếu một nhân viên hỗ trợ đang quản lý chuỗi cung ứng và xác nhận không chính xác tình trạng còn hàng của nhà cung cấp hoặc tuyến đường, thì bạn sẽ phải đối mặt với tình trạng lãng phí nhiên liệu, không đạt được SLA và hoạt động kinh doanh bị gián đoạn thực sự. Và trong cấu trúc đa tác nhân, bạn sẽ gặp phải vấn đề ảo tưởng xếp tầng. Nếu một tác nhân trong chuỗi bị ảo giác và truyền dữ liệu sai cho tác nhân thứ hai, thì toàn bộ hệ thống sẽ bắt đầu đưa ra các cam kết trong thế giới thực dựa trên một thông tin sai lệch. Sự tự chủ mà không có sự thật sẽ trở thành một gánh nặng lớn.
Việc dựa trên dữ liệu thực tế yêu cầu tác nhân phải vượt ra ngoài trọng số huấn luyện của mình. Bằng cách buộc AI tìm nạp các dữ kiện thực tế, có thể xác minh (như dữ liệu Địa điểm và dữ liệu định tuyến), bạn sẽ cung cấp cho tác nhân khả năng quan sát và lắng nghe theo thời gian thực, biến một phỏng đoán thống kê thành một quyết định hoạt động sáng suốt.
Lý do nên dùng MCP
Giao thức ngữ cảnh mô hình (MCP) là một tiêu chuẩn mở được thiết kế để giúp việc tích hợp công cụ và dữ liệu trở nên dễ dàng.
Trước đây, để kết nối mô hình AI với API bên ngoài, bạn phải viết các trình bao bọc cứng nhắc, tuỳ chỉnh. Bạn phải xử lý định dạng, phân tích cú pháp lỗi và dịch lệnh gọi công cụ theo cách thủ công cho từng chức năng riêng lẻ.
MCP chuẩn hoá lớp tích hợp này. Bằng cách triển khai ứng dụng MCP, ứng dụng của bạn có thể khám phá và thực thi các công cụ do máy chủ cung cấp một cách linh động thông qua một giao thức hợp nhất. Điều này giúp nhà phát triển chuyển trọng tâm từ việc viết logic tích hợp API lặp đi lặp lại sang thiết kế các mạng tác nhân cấp cao.
Google Maps Grounding Lite MCP
Google Maps Grounding Lite MCP là một máy chủ MCP do Google lưu trữ và quản lý hoàn toàn, có thể tích hợp trực tiếp vào bất kỳ khung tác nhân tương thích nào.
Hiện tại, máy chủ cung cấp 3 công cụ cốt lõi để tạo cơ sở:
- Tìm địa điểm: Yêu cầu thông tin về địa điểm và nhận thông tin tóm tắt về địa điểm do AI tạo, cũng như Mã địa điểm, toạ độ vĩ độ và kinh độ, cùng đường liên kết đến Google Maps cho từng địa điểm có trong thông tin tóm tắt. Bạn có thể sử dụng Mã địa điểm và toạ độ vĩ độ và kinh độ được trả về cùng với các API khác của Google Maps Platform để hiển thị địa điểm trên bản đồ.
- Tra cứu thời tiết: Yêu cầu thông tin về thời tiết và trả về tình hình hiện tại, thông tin dự báo hằng giờ và thông tin dự báo hằng ngày.
- Tính toán tuyến đường: Yêu cầu thông tin về tuyến đường lái xe hoặc đi bộ giữa hai vị trí và trả về thông tin về khoảng cách và thời gian của tuyến đường.
Để truy cập vào dịch vụ, bạn có thể sử dụng Khoá API hoặc OAuth. Google Maps Platform cung cấp khoá API minh hoạ miễn phí, được thiết kế riêng để giúp nhà phát triển bắt đầu tạo nguyên mẫu ngay lập tức.
Các phương pháp hay nhất để tích hợp MCP dựa trên Maps
Để tối đa hoá mức độ liên quan của dữ liệu và loại bỏ ảo tưởng về cấu trúc, hãy neo chỉ dẫn hệ thống của nhân viên hỗ trợ vào các chiến lược cốt lõi sau: * Rõ ràng và cụ thể: Hướng dẫn nhân viên hỗ trợ sử dụng vị trí chính xác. "Công viên Trung tâm, New York" mang lại kết quả tốt hơn "New York", cũng như "Paris, Pháp" giúp tránh nhầm lẫn với Paris, Texas.
Phân tích cụm từ tìm kiếm chung: Đối với những yêu cầu mơ hồ như "ý tưởng cho buổi hẹn hò", hãy yêu cầu tác nhân phân tích nhiệm vụ thành các cụm từ tìm kiếm phụ cụ thể như "nhà hàng lãng mạn", "rạp chiếu phim" hoặc "quán bar cocktail".
Khám phá trước, tìm hiểu sau: Trước tiên, hãy tìm kiếm thông tin chung (ví dụ: "Nhà hàng Nhật Bản có lối vào cho người khuyết tật mở cửa vào Chủ Nhật"). Trình bày các lựa chọn cho người dùng, sau đó chạy một truy vấn tiếp theo để tìm nạp thông tin chi tiết cụ thể như số điện thoại của địa điểm đã chọn.
Không bao giờ tự tạo Mã địa điểm: Mã địa điểm là thành phần kết nối quan trọng giữa các dịch vụ của Nền tảng Google Maps. Đảm bảo nhân viên hỗ trợ của bạn biết rằng họ chỉ được sử dụng Mã địa điểm do công cụ search_places trả về một cách rõ ràng, thay vì cố gắng tự tạo mã.
Triển khai tác nhân lập kế hoạch du lịch bằng Google ADK
Phần này trình bày cách xây dựng một tác nhân lập kế hoạch du lịch bằng khung Bộ công cụ phát triển tác nhân (ADK) của Google. Nếu bạn chưa cài đặt ADK, hãy xem tài liệu dành cho nhà phát triển về ADK của Google.
Việc tích hợp máy chủ Maps MCP vào một khung tác nhân như ADK rất đơn giản. ADK xử lý các vấn đề phức tạp trong việc quản lý bối cảnh, giúp bạn tập trung vào hành vi của tác nhân.
Dự án mẫu có cấu trúc như sau:
travel-concierge-google-maps-mcp/
├── travel_planner_agent/
├── agent.py # main agent code
├── .env # API keys
├── __init__.py
├── skills/travel-concierge/
├── SKILL.md # Agent skill
Mẫu của agent.py. Hãy chỉnh sửa mã này dựa trên trường hợp sử dụng của bạn.
import os
import pathlib
import logging
from datetime import date
from dotenv import load_dotenv
from google.adk.agents.llm_agent import Agent
from google.adk.skills import load_skill_from_dir
from google.adk.tools import skill_toolset
from google.adk.tools.mcp_tool import McpToolset
from google.adk.planners import BuiltInPlanner
from google.genai import types
from google.adk.tools.mcp_tool.mcp_session_manager
import StreamableHTTPConnectionParams
load_dotenv()
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
GOOGLE_MAPS_API_KEY = os.getenv("GOOGLE_MAPS_API_KEY")
if not GOOGLE_MAPS_API_KEY:
raise ValueError("Missing GOOGLE_MAPS_API_KEY environment variable.")
current_date = date.today().strftime("%A, %B %d, %Y")
# AGENT & TOOL SETUP
BASE_SYSTEM_INSTRUCTION = f"""
You are a Premium Travel Orchestrator. Your sole purpose is to assist users with travel planning, location discovery, route mapping, weather checks, and culinary/cultural recommendations. The current system date is {current_date}.
# 1. OUT-OF-DOMAIN PROTOCOL (Strict Refusal)
You are strictly forbidden from answering queries unrelated to travel, geography, food, hospitality, or local experiences.
If a user asks about coding (e.g., Python bugs), math, writing essays, or general non-travel trivia:
- Politely decline.
- Explicitly state that your expertise is limited to travel and local discovery.
- Pivot by asking if they need help planning a trip or finding a great local spot.
# 2. TANGENTIAL KNOWLEDGE PROTOCOL (The "Tiramisu" Rule)
If a user asks a factual question about food, a cultural item, or a historical concept that *can* be tied to a physical location (e.g., "What is tiramisu?", "What is Gothic architecture?"):
- Provide a brief, helpful 1-2 sentence explanation of the concept.
- IMMEDIATELY pivot to your primary domain. Ask the user for their current location or target city so you can search for the best places to experience or eat that item.
# 3. TOOL EXECUTION BOUNDARIES
- NEVER call `lookup_weather` for general history, trivia, or factual questions.
- ONLY call `lookup_weather` if the user explicitly asks for the forecast, OR if they have confirmed they are actively planning an itinerary/trip for a specific date and destination.
"""
travel_skill = load_skill_from_dir(
pathlib.Path(__file__).parent / "skills" / "travel-concierge"
)
maps_mcp_toolset = 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"
}
)
)
my_skill_toolset = skill_toolset.SkillToolset(
skills=[travel_skill],
additional_tools=[maps_mcp_toolset]
)
root_agent = Agent(
model='gemini-flash-latest',
name='travel_planner_agent',
description="A highly capable assistant leveraging specialized modular skills and spatial tools.",
instruction=BASE_SYSTEM_INSTRUCTION,
planner=BuiltInPlanner(
thinking_config=types.ThinkingConfig(
include_thoughts=True
)
),
tools=[my_skill_toolset]
)
Mẫu tệp SKILL.md. Hãy chỉnh sửa tệp này dựa trên trường hợp sử dụng của bạn.
name: travel-concierge
description:
Accesses real-time spatial data, weather, and traffic routing to design accurate itineraries and provide location-based information.
Use when: A user is planning a trip, creating a travel itinerary, mapping a route, asking about a city's history, discovering local foods, exploring basic geography trivia, or inquiring about the weather.
Dont use for: Tasks completely unrelated to travel, locations, geography, or weather, such as coding assistance, mathematical calculations, or personal finance.
metadata:
adk_additional_tools:
- search_places
- lookup_weather
- compute_routes
---
# Travel Concierge Workflow
You act as an elite, deeply consultative travel planner. You are responsible for designing logistically sound travel plans by strictly prioritizing your toolset over pre-trained memory.
To deliver a premium experience, you must manage the interaction in two distinct phases: Discovery and Execution.
## Phase 1: Discovery Dialogue & Briefing (First Turn)
When a user initiates a request but leaves critical logistical variables open, **do NOT generate a complete multi-stop itinerary or directions link immediately.** Instead, build a warm, conversational dialogue to lock in the baseline parameters.
1. **Conditional Weather Context Hook:** ONLY call `lookup_weather` if the user is actively planning a trip to a specific location on a specific date, OR if they explicitly ask for the weather. DO NOT check the weather for general questions about a city's history or local foods. If you do check the weather for a trip, share a brief summary of the conditions to justify your upcoming line of questioning.
2. **Targeted Consultation (Ask 2-3 Friendly Questions):**
- **Verify Arrival Point & Terminal:** Never assume an airport arrival. If they state an arrival time but no explicit location, set an internal baseline but explicitly ask them to confirm their exact station or airport terminal. **If they confirm an airport arrival, strictly verify whether it is a Domestic or International flight**, as clearing international customs and immigration requires adding a 60-to-90-minute buffer to the initial travel time before scheduling the first venue.
- **Verify User Preferences:** If food or activity interests are ambiguous or partial (e.g., "coffee and seafood"), acknowledge these directly and ask about their preferred style or pacing (e.g., casual local markets vs. seated upscale dining).
- **Anchor Point Checking:** Always ask if there is a specific bucket-list venue or seasonal sight they absolutely must visit so you can build the fixed timeline around it.
## Phase 2: Location Extraction & Validation
- Use `search_places` to verify destinations, opening hours, and location accuracy.
- **CRITICAL INPUT RULE:** You must ensure the `text_query` parameter contains explicit location keywords. If the user mentions "boutique hotels" or "seafood dinner", you must modify the query to include the city (e.g., text_query="boutique hotels in Sydney, Australia").
## Phase 3: Tool Execution & Itinerary Reveal (Subsequent Turns)
Once the user responds with their specific logistics, construct the definitive itinerary using your spatial grounding tools. When preferences remain broad, default to highly rated venues that match the verified weather conditions and current seasonality.
### 1. Location Validation (`search_places`)
- Verify all destinations, opening hours, and exact addresses.
- **CRITICAL INPUT RULE:** You must ensure the `text_query` parameter contains explicit location keywords. If the user requests "boutique hotels" or "seafood lunch", modify the query to append the target city/region (e.g., `text_query="seafood lunch in Sydney, Australia"`).
### 2. Logistical Reality (`compute_routes`)
- Ensure consecutive stops are logically possible by checking travel times and distances.
- Pass both `origin` and `destination` using verified addresses or Place IDs. If either is missing, halt and ask for clarification.
- Do NOT hallucinate Place ID. You must use the Place ID provided by `search_places`.
### 3. Itinerary Output Formatting
- **Route to Next Stop:** Between every single consecutive itinerary stop, you MUST output a dedicated sub-bullet detailing the transit path.
- This bullet must explicitly state the suggested travel mode (Walk, Transit, or Drive), the exact travel time in minutes verified by `compute_routes`, and a brief path description (e.g., *"Route to Next Stop: 12-minute walk via Market St"*).
- **Attribution:** Include inline or bracketed Google Maps URLs for recommended venues using data derived from the tool's attribution payloads. Do not guess links.
### 4. Multi-Stop Directions Link Generation
At the absolute end of your finalized itinerary response, compile all planned locations into a single, functional Google Maps Directions URL.
- **Format Constraint:** Build the URL using the base string: `https://www.google.com/maps/dir/`
- Append each venue name and full address sequentially, separated by a forward slash `/`, replacing spaces with `+` and encoding URL parameters where necessary.
- Example format: `https://www.google.com/maps/dir/Venue+One,+Address/Venue+Two,+Address/Venue+Three,+Address/`
- Present this link prominently with clear anchor text.
## Phase 4: Output Formatting & Source Attribution (CRITICAL)
- You must comply strictly with Google Maps Platform display guidelines.
- Every grounded piece of information (Places, Weather, Routes) must be immediately followed by its supporting source.
- For place details extracted via `search_places`, always map and output the exact URL provided in the `places.googleMapsLinks.placeUrl` payload. Do not invent links.
init.py
from . import agent
Chạy adk web và tương tác
Để khởi động giao diện người dùng web ADK mặc định, hãy chạy lệnh này trong thư mục dự án travel-concierge-google-maps-mcp:
adk web
Tương tác trong giao diện người dùng:
- Tải giao diện người dùng tại http://127.0.0.1:8000 trong trình duyệt
- Hãy thử những câu lệnh như:
- "Tôi sẽ ở San Francisco vào thứ Bảy. Lên kế hoạch cho chuyến đi trong ngày của tôi."
- "Tìm quán cà phê gần Công viên Cầu Giấy và cho tôi xem các món nổi bật trong thực đơn."
- "Tìm đường đi từ GooglePlex đến SFO."
Khi tác nhân nhận được câu lệnh, trình lập kế hoạch sẽ đánh giá ý định của người dùng. Tác nhân này nhận ra nhu cầu về dữ liệu không gian và thời tiết, đồng thời tự động kích hoạt các công cụ lookup_weather, search_places và compute_routes bằng máy chủ MCP. Sau đó, nhân viên hỗ trợ sẽ tổng hợp một hành trình dựa trên thông tin thực tế cho người dùng.
Kết luận
Sự chuyển dịch sang AI tác nhân đang mở ra những khả năng hoàn toàn mới trong lĩnh vực logistics, du lịch và bán lẻ. Tuy nhiên, để có được sự tự chủ thực sự, bạn cần có một nền tảng thông tin vững chắc.
Bằng cách tận dụng Giao thức ngữ cảnh mô hình cùng với Google Maps Grounding Lite, bạn sẽ loại bỏ được sự phiền toái khi tích hợp API riêng và cung cấp cho các tác nhân của mình thông tin theo thời gian thực mà họ cần. Việc neo mô hình vào dữ liệu không gian trực tiếp đảm bảo mô hình đưa ra quyết định vận hành dựa trên những gì đang diễn ra trong thế giới thực ngay lúc này, chứ không phải dựa trên ảnh chụp nhanh tĩnh từ dữ liệu huấn luyện.
Hành động tiếp theo
- Đọc tài liệu dành cho nhà phát triển về MCP Grounding của Maps.
- Lấy khoá API minh hoạ.
- Tìm hiểu cách triển khai tác nhân.
Tác giả chính:
Teresa Qin | Kỹ sư DevX của Google Maps Platform