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 cho 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ẽ nhắc tác nhân tạo các 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 chạy một dự án tác nhân bằng Gói khởi động tác nhân
Định cấu hình tác nhân để sử dụng công cụ Liên kết thực tế với 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 bộ chọn dự án, hãy chọn hoặc tạo một dự án trên Google Cloud.
Đảm bảo rằng bạn đã bật tính năng thanh toán cho dự án trên đám mây. Tìm hiểu cách kiểm tra xem tính năng thanh toán đã được bật cho một dự án hay chưa.

Bắt đầu 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 dự án 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 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 tác nhân. Gói khởi động tác nhân Google Cloud 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 create để 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

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 của bạn cho quá trình phát triển cục bộ bằng một giao diện người dùng React:

Agent Template: adk (Simple React Agent)
Deployment: none (Cloud Deployment hiện đã tắt)
Region: us-central1

Thao tác này sẽ tạo cấu trúc thư mục dự án chứa logic tác nhân chính, các bài 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 tính năng liên kết thực tế

Gói khởi động tác nhân tạo một tệp GEMINI.md hướng dẫn các công cụ viết mã sử dụng AI về cách quản lý dự án của bạn. Chúng ta sẽ cập nhật tệp này để đưa vào tài liệu về tính năng liên kết thực tế với Google Maps.

Mở GEMINI.md trong trình chỉnh sửa.
Thêm đường liên kết tham chiếu sau đây trong 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ý viết mã AI hiểu được tính năng liên kết thực tế.

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ụ Liên kết thực tế với Google Maps.

Mở tệp app/agent.py.
Thay thế toàn bộ nội dung của app/agent.py bằng 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",
)

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ề các đị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

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

Từ thư mục 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 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 hỏi tác nhân một câu hỏi. Ví dụ:

"Plan a 1-day itinerary in San Francisco including a good Italian restaurant." (Lập kế hoạch cho hành trình 1 ngày ở San Francisco, bao gồm cả một nhà hàng Ý ngon.)
"I'm visiting Tokyo, can you give me an itinerary with interesting historical landmarks and a highly rated ramen spot with a cozy vibe?" (Tôi đang đến thăm Tokyo, bạn có thể cho tôi một hành trình có các địa danh lịch sử thú vị và một địa điểm bán mì ramen được đánh giá cao với không gian ấm cúng không?)

Bạn sẽ thấy đầu ra tương tự như một hành trình chi tiết được làm phong phú bằng các bài đánh giá thực tế và mô tả tuyến đường được lấy trực tiếp từ Google Maps.

Ví dụ về kết quả hành trình của nhân viên hỗ trợ

7. Xác minh tính năng liên kết thực tế 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 liên kết thực tế với Maps, bạn có thể kiểm tra các sự kiện phản hồi cho 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à một 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ể sử dụng trong một bài 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 đoạn được mã hoá

Ngoài việc xác minh rằng tính năng liên kết thực tế đã xảy 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ụ liên kết thực tế với Maps trả về thông tin tuyến đường, công cụ này thường bao gồm một "Đường nhiều đoạn được mã hoá" có thể dùng để hiển thị tuyến đường trên giao diện người dùng bản đồ.

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

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í liên tục cho tài khoản Google Cloud, hãy xoá các tài nguyên được 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á toàn bộ dự án đó:

gcloud projects delete $PROJECT_ID

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

10. Xin chúc mừng

Xin chúc mừng! Bạn đã xây dựng thành công một tác nhân lập kế hoạch hành trình và liên kết tác nhân đó bằng thông tin chi tiết từ 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ụ liên kết thực tế vào định nghĩa Tác nhân ADK
Cách kiểm thử 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 khác và mẫu tích hợp