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, cho phép các hệ thống thực hiện suy luận phức tạp và hoạt động tự chủ hơn. Tuy nhiên, các mô hình cơ bản thúc đẩy những hệ thống này đương nhiên bị hạn chế bởi dữ liệu huấn luyện của chúng. Nếu không có bối cảnh bên ngoài, các mô hình này sẽ không nhận biết được 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 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 suy luận tĩnh và thực tế năng động bằng cách neo bám các tác nhân AI của bạn với 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 liên kết không gian lại rất quan trọng đối với các tác vụ trong thế giới thực, 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 tạo một tác nhân lập kế hoạch du lịch bằng MCP Liên kết của Google Maps Lite.
Tại sao các trợ lý ảo cần có dữ liệu bản đồ làm cơ sở
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à một bước chuyển từ kỹ thuật xác định sang điều phối xác suất. Chúng ta đang chuyển từ những hệ thống chỉ biết mọi thứ sang những công cụ thực thi chủ động thực sự làm mọi việc. Khi một ứng dụng vượt qua ranh giới đó và thực hiện hành động trong thế giới thực, mức độ chính xác sẽ thay đổi hoàn toàn.
Mô hình ngôn ngữ lớn (LLM) hiểu được logic, nhưng bộ nhớ trong của chúng là một bản chụp nhanh về lịch sử. Ví dụ: nếu một nhân viên đang quản lý chuỗi cung ứng và xác nhận sai tình trạng còn hàng của nhà cung cấp hoặc tuyến đường, thì bạn sẽ thấy tình trạng lãng phí nhiên liệu, không đáp ứng được SLA và gián đoạn hoạt động kinh doanh thực sự. Trong kiến trúc đa tác nhân, bạn sẽ gặp phải vấn đề ảo giác theo tầng. Nếu một tác nhân trong chuỗi ảo tưởng 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 thông tin sai lệch. Quyền tự chủ mà không có sự thật sẽ trở thành một trách nhiệm pháp lý lớn.
Cơ sở yêu cầu tác nhân bước ra ngoài các trọng số huấn luyện. Bằng cách buộc AI tìm nạp các thông tin thực tế có thể xác minh và đang diễn ra (chẳng hạn như dữ liệu về Địa điểm và dữ liệu định tuyến), bạn sẽ cung cấp cho tác nhân thông tin theo thời gian thực, biến một phỏng đoán dựa trên số liệu thống kê thành một quyết định vận hành 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, việc kết nối một mô hình AI với các API bên ngoài đòi hỏi phải viết các trình bao bọc tuỳ chỉnh, cứng nhắc. Bạn phải xử lý thủ công việc định dạng, phân tích cú pháp lỗi và bản dịch lệnh gọi công cụ cho từng khả năng riêng lẻ.
MCP chuẩn hoá lớp tích hợp này. Bằng cách triển khai một ứ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 sự tập trung 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 lưới tác nhân cấp cao.
MCP Google Maps Grounding Lite
Google Maps Grounding Lite MCP là một máy chủ MCP do Google lưu trữ và được quản lý hoàn toàn. Máy chủ này có thể được 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ủ này cung cấp 3 công cụ cốt lõi để thiết lập cơ sở:
- Tìm kiế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ề dữ liệu địa điểm do AI tạo, cũng như mã địa điểm, toạ độ vĩ độ và kinh độ, và đườ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ị các đị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, dự báo theo giờ và 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 lượng của tuyến đường.
Để truy cập vào dịch vụ này, bạn có thể sử dụng Khoá API hoặc OAuth. Google Maps Platform cung cấp khoá API dùng cho bản minh hoạ miễn phí được thiết kế riêng để giúp các 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 bản đồ
Để tối đa hoá mức độ phù hợp của dữ liệu và loại bỏ ảo giác về cấu trúc, hãy cố định chỉ dẫn hệ thống của tác nhân xoay quanh những chiến lược cốt lõi sau: * Rõ ràng và cụ thể: Hướng dẫn tác nhân sử dụng vị trí chính xác. "Công viên Trung tâm, New York" sẽ cho kết quả chính xác hơn so với "New York", tương tự như "Paris, Pháp" sẽ tránh nhầm lẫn với Paris, Texas.
Chia nhỏ các cụm từ tìm kiếm chung chung: Đối với những yêu cầu mơ hồ như "ý tưởng cho buổi hẹn hò," hãy nhắc trợ lý chia nhỏ nhiệm vụ thành các cụm từ tìm kiếm cụ thể như "nhà hàng lãng mạn", "rạp chiếu phim" hoặc "quán cocktail".
Khám phá trước, khám phá sâu hơn sau: Trước tiên, hãy thực hiện một lượt tìm kiếm khám phá trên diện rộng (ví dụ: "Nhà hàng Nhật Bản có lối vào cho xe lăn mở cửa vào Chủ Nhật"). Đưa ra 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ạo thông tin sai lệch về 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 rằng tác nhân của bạn biết rằng tác nhân 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 một 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 tạo 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 Google ADK.
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 về việc quản lý ngữ cảnh, cho phé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 agent.py. Chỉnh sửa theo 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 SKILL.md. Chỉnh sửa tệp này dựa trên các 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ử các 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 cho tôi."
- "Tìm quán cà phê gần Công viên Cổng Vàng và cho tôi xem những điểm nổi bật trong thực đơn."
- "Tìm đường đi từ GooglePlex đến SFO".
Khi nhận được câu lệnh, lập kế hoạch sẽ đánh giá ý định của người dùng. Ứng dụng 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 đó, tác nhân 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 đổi 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 hậu cần, du lịch và bán lẻ. Tuy nhiên, sự tự chủ thực sự đòi hỏi một nền tảng vững chắc về sự thật.
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 những khó khăn khi tích hợp API theo yêu cầu và cung cấp cho các tác nhân của mình những thông tin cần thiết theo thời gian thực. Việc cố định các mô hình của bạn trong dữ liệu không gian thực đảm bảo rằng các mô hình này đưa ra quyết định vận hành dựa trên những gì đang xảy ra trong thế giới thực ngay bây giờ, chứ không phải dựa trên ảnh chụp nhanh cố định từ dữ liệu huấn luyện của chúng.
Các hành động tiếp theo
- Đọc tài liệu dành cho nhà phát triển MCP (Nền tảng nội dung tuỳ chỉnh) 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 Nền tảng Google Maps