Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Xây dựng một tác nhân lập kế hoạch hành trình bằng ADK và tính năng liên kết thực tế với Google Maps

1. Giới thiệu

Trong lớp học lập trình này, bạn sẽ xây dựng một tác nhân lập kế hoạch chuyến đi bằng Bộ công cụ phát triển tác nhân (ADK) và liên kết tác nhân đó với Google Maps. Bạn sẽ yêu cầu trợ lý tạo tuyến đường ngắm cảnh và đề xuất nhà hàng, tận dụng dữ liệu thực tế từ Google Maps.

Bạn sẽ thực hiện

Khởi động một dự án tác nhân bằng Gói khởi động dành cho tác nhân
Định cấu hình tác nhân để sử dụng công cụ Căn cứ địa lý trên Google Maps
Kiểm thử tác nhân kết quả cục bộ bằng giao diện web

Bạn cần có

Một trình duyệt web như Chrome
Một dự án trên Google Cloud đã bật tính năng thanh toán

Lớp học lập trình này dành cho các nhà phát triển có trình độ trung cấp, những người đã quen thuộc với Python và Google Cloud, nhưng không nhất thiết phải là chuyên gia.

2. Trước khi bắt đầu

Tạo một dự án trên Google Cloud

Trong Google Cloud Console, trên trang chọn dự án, hãy chọn hoặc tạo một dự án trên đám mây của Google Cloud.
Đảm bảo bạn đã bật tính năng thanh toán cho dự án trên Cloud. Tìm hiểu cách kiểm tra xem tính năng thanh toán có được bật trong một dự án hay không.

Khởi động Cloud Shell

Xác minh quy trình xác thực:

gcloud auth list

Xác nhận dự án của bạn:

gcloud config get project

Đặt nếu cần:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Bật API

Chạy lệnh này để bật tất cả các API bắt buộc:

gcloud services enable \
  aiplatform.googleapis.com

3. Cài đặt Gói khởi động dành cho tác nhân

Cách dễ nhất để bắt đầu một dự án ADK là sử dụng Gói khởi động dành cho tác nhân. Gói khởi động Google Cloud Agent là một công cụ giao diện dòng lệnh (CLI) mã nguồn mở được thiết kế để tăng tốc quá trình phát triển và triển khai các tác nhân AI tạo sinh sẵn sàng cho hoạt động sản xuất trên Google Cloud.

Đảm bảo bạn đã cài đặt uv, sau đó chạy lệnh tạo để khởi chạy một dự án tác nhân mới:

uvx agent-starter-pack create

Nếu chưa cài đặt uv, bạn có thể sử dụng pip:

# Create and activate a Python virtual environment
python -m venv .venv && source .venv/bin/activate

# Install the agent starter pack
pip install --upgrade agent-starter-pack

# Create a new agent project
agent-starter-pack create

Hãy xem kho lưu trữ agent-starter-pack để biết thêm thông tin.

Khi được nhắc, hãy cung cấp các lựa chọn sau để định cấu hình dự án cho quá trình phát triển cục bộ bằng giao diện người dùng React:

Mẫu tác nhân: adk (Tác nhân React đơn giản)
Triển khai: none (Hiện tại, bạn không thể triển khai trên đám mây)
Khu vực: us-central1

Thao tác này sẽ tạo một cấu trúc thư mục dự án chứa logic chính của tác nhân, các kiểm thử và hướng dẫn GEMINI.md. Chuyển đến thư mục mới:

cd my-agent

4. Định cấu hình cơ sở

Agent Starter Pack tạo một tệp GEMINI.md hướng dẫn các công cụ lập trình dựa trên AI cách quản lý dự án của bạn. Chúng tôi sẽ cập nhật thông tin này để bổ sung tài liệu về tính năng Nền tảng Google Maps.

Mở GEMINI.md trong trình chỉnh sửa.
Thêm đường liên kết tham chiếu sau vào phần ## Reference Documentation:

- **Google Maps Grounding**: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-maps

Ngữ cảnh này sẽ giúp mọi trợ lý lập trình AI hiểu được tính năng cơ sở.

5. Cập nhật tác nhân

Bây giờ, chúng ta sẽ định cấu hình tác nhân để hoạt động như một công cụ lập kế hoạch hành trình, hoàn chỉnh với công cụ Nền tảng Google Maps.

Mở tệp app/agent.py.
Thay thế toàn bộ nội dung của app/agent.py bằng đoạn mã sau:

"""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",
)

Đoạn mã này định cấu hình một tác nhân dựa trên gemini-2.5-flash sử dụng công cụ google_maps_grounding để truy xuất thông tin hiện tại về địa điểm và tuyến đường.

Để xem tất cả các mô hình hiện có, hãy xem tài liệu về Vertex AI.

6. Chạy tác nhân

Sau khi thiết lập logic của tác nhân, hãy thử kiểm thử logic đó trong giao diện web cục bộ.

Từ gốc của thư mục my-agent, hãy chạy lệnh sau để khởi động ứng dụng web:

uv run adk web

hoặc nếu bạn đang sử dụng môi trường ảo:

adk web

Mở URL được cung cấp trong đầu ra của thiết bị đầu cuối trong trình duyệt.
Kiểm thử tác nhân bằng cách đặt câu hỏi cho tác nhân. Ví dụ:

"Lên lịch trình 1 ngày ở San Francisco, trong đó có một nhà hàng Ý ngon."
"Tôi đang ở Tokyo, bạn có thể gợi ý cho tôi một hành trình có các địa danh lịch sử thú vị và một quán ramen được đánh giá cao với bầu không khí ấm cúng không?"

Bạn sẽ thấy kết quả tương tự như một hành trình chi tiết, được bổ sung các bài đánh giá thực tế và nội dung mô tả tuyến đường lấy trực tiếp từ Google Maps.

Đầu ra mẫu về hành trình của nhân viên hỗ trợ

7. Xác minh cơ sở trong mã

Để xác nhận theo phương thức lập trình rằng tác nhân của bạn đang sử dụng thành công tính năng cơ sở dữ liệu của Maps, bạn có thể kiểm tra các sự kiện phản hồi để biết siêu dữ liệu dành riêng cho Maps.

Khi bạn chạy tác nhân (ví dụ: trong một kịch bản kiểm tra), tác nhân sẽ tạo ra các sự kiện chứa grounding_metadata. Bạn có thể lặp lại grounding_chunks trong siêu dữ liệu này và kiểm tra thuộc tính maps.

Dưới đây là ví dụ minh hoạ cách kiểm tra thuộc tính maps, tương tự như những gì bạn có thể dùng trong một quy trình kiểm thử tự động:

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. Trích xuất đường nhiều đường được mã hoá

Ngoài việc xác minh rằng quá trình tiếp đất đã diễn ra, bạn có thể muốn trích xuất dữ liệu cụ thể như đường dẫn tuyến đường. Khi công cụ cơ sở Maps trả về thông tin về tuyến đường, thông tin này thường bao gồm một "Đường nhiều đoạn được mã hoá" có thể dùng để kết xuất tuyến đường trên giao diện người dùng Maps.

Bạn có thể tìm thấy đường nhiều đoạn này bằng cách kiểm tra văn bản trong thuộc tính maps của grounding_chunks. Sau đây là ví dụ về cách bạn có thể phát hiện:

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. Dọn dẹp

Để tránh các khoản phí phát sinh cho tài khoản Google Cloud của bạn, hãy xoá các tài nguyên đã tạo trong lớp học lập trình này.

Nếu bạn đã tạo một dự án riêng cho lớp học lập trình này, hãy xoá hoàn toàn dự án đó:

gcloud projects delete $PROJECT_ID

Nếu đã sử dụng một dự án hiện có và muốn giữ lại dự án đó, bạn không cần xoá tài nguyên cụ thể nào vì tác nhân chạy cục bộ và các API được dùng đều không máy chủ.

10. Xin chúc mừng

Xin chúc mừng! Bạn đã tạo thành công một tác nhân lập kế hoạch hành trình và đặt nền tảng cho tác nhân đó bằng thông tin chi tiết trên Google Maps.

Kiến thức bạn học được

Cách tạo khung cho một tác nhân mới bằng Gói khởi động tác nhân
Cách thêm các công cụ cơ sở vào định nghĩa ADK Agent
Cách kiểm thử một tác nhân ADK bằng trình chạy web tích hợp

Các bước tiếp theo

Khám phá các Công cụ ADK và mẫu tích hợp khác