איך בונים סוכן לתכנון מסלול נסיעה באמצעות ADK ועיגון במפות Google

1. מבוא

בשיעור Codelab הזה נסביר איך ליצור סוכן לתכנון נסיעות באמצעות הערכה לפיתוח סוכנים (ADK) ולהצמיד אותו למפות Google. אתם יכולים להנחות את הסוכן ליצור מסלולים עם נופים יפים ולהמליץ על מסעדות, על סמך נתונים מהעולם האמיתי במפות Google.

הפעולות שתבצעו:

• אתחול של פרויקט סוכן באמצעות המדריך למתחילים ביצירת סוכנים
• הגדרת הסוכן לשימוש בכלי Google Maps Grounding
• בדיקה מקומית של הסוכן שנוצר באמצעות ממשק אינטרנט

הדרישות

• דפדפן אינטרנט כמו Chrome
• פרויקט ב-Google Cloud שהחיוב בו מופעל

ה-Codelab הזה מיועד למפתחים ברמת ביניים, שיש להם היכרות מסוימת עם Python ועם Google Cloud, אבל הם לא בהכרח מומחים.

‫2. לפני שמתחילים

יצירת פרויקט ב-Google Cloud

1. במסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים פרויקט ב-Google Cloud או יוצרים פרויקט.
2. הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט

הפעלת Cloud Shell

1. אימות האימות:

gcloud auth list

2. מאשרים את הפרויקט:

gcloud config get project

3. מגדירים אותו לפי הצורך:

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

הפעלת ממשקי ה-API

מריצים את הפקודה הבאה כדי להפעיל את כל ממשקי ה-API הנדרשים:

gcloud services enable \
  aiplatform.googleapis.com

3. התקנת חבילת התחלה של סוכן

הדרך הקלה ביותר להתחיל פרויקט ADK היא באמצעות המדריך למתחילים ביצירת סוכנים. חבילת המתחילים של סוכני Google Cloud היא כלי בקוד פתוח של ממשק שורת פקודה (CLI) שנועד להאיץ את הפיתוח והפריסה של סוכני AI גנרטיביים שמוכנים לייצור ב-Google Cloud.

1. מוודאים ש-uv מותקן, ואז מריצים את פקודת היצירה כדי לאתחל פרויקט חדש של סוכן:

uvx agent-starter-pack create

אם לא התקנתם את uv, אתם יכולים להשתמש ב-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

פרטים נוספים מופיעים במאגר agent-starter-pack.

2. כשמופיעה הנחיה, מספקים את האפשרויות הבאות כדי להגדיר את הפרויקט לפיתוח מקומי עם קצה קדמי של React:

• תבנית סוכן: adk (סוכן React פשוט)
• פריסה: none (השירות Cloud Deployment מושבת כרגע)
• אזור: us-central1

הפעולה הזו תיצור מבנה של ספריית פרויקט שמכיל את הלוגיקה הראשית של הסוכן, הבדיקות ומדריך GEMINI.md. מנווטים לספרייה החדשה:

cd my-agent

4. הגדרת ביסוס

חבילת המתחילים ליצירת סוכנים יוצרת קובץ GEMINI.md עם הוראות לכלים מבוססי-AI לתכנות, שמסבירות איך לנהל את הפרויקט. אנחנו נעדכן את המאמר הזה כך שיכלול את תיעוד ההארקה של מפות Google.

1. פותחים את GEMINI.md בעורך.
2. מוסיפים את קישור ההפניה הבא לקטע ## Reference Documentation:

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

ההקשר הזה יעזור לכל כלי AI לעזרה בתכנות להבין את תכונת ההארקה.

5. עדכון הסוכן

עכשיו נגדיר את הסוכן כך שיפעל כמתכנן מסלולים, באמצעות כלי העיגון של מפות Google.

1. פותחים את הקובץ app/agent.py.
2. מחליפים את כל התוכן של app/agent.py בקוד הבא:

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

הקוד הזה מגדיר סוכן מבוסס-gemini-2.5-flash שמשתמש בכלי google_maps_grounding כדי לאחזר מידע עדכני על מקומות ומסלולים.

כדי לראות את כל המודלים הזמינים, אפשר לעיין בתיעוד של Vertex AI.

6. הפעלת הסוכן

אחרי שיוצרים את הלוגיקה של הסוכן, מומלץ לבדוק אותה בממשק האינטרנט המקומי.

1. מריצים את הפקודה הבאה כדי להפעיל את אפליקציית האינטרנט, מתיקיית השורש של my-agent:

uv run adk web

או, אם משתמשים בסביבה וירטואלית:

adk web

2. פותחים בדפדפן את כתובת ה-URL שמופיעה בפלט של המסוף.
3. כדי לבדוק את הסוכן, שואלים אותו שאלה. לדוגמה:

• "תכנן מסלול ליום אחד בחיפה, כולל מסעדה איטלקית טובה".
• "אני מבקר בטוקיו, אפשר לקבל מסלול טיול עם ציוני דרך היסטוריים מעניינים ומקום מומלץ לאכול בו ראמן באווירה נעימה?"

אמור להתקבל פלט שדומה למסלול נסיעה מפורט עם ביקורות אמיתיות ותיאורי מסלול שנלקחו ישירות ממפות Google.

7. אימות ההתבססות על קוד

כדי לוודא באופן פרוגרמטי שהסוכן משתמש בהצלחה בהתבססות על מפות, אפשר לבדוק את אירועי התגובה כדי למצוא מטא-נתונים שספציפיים למפות.

כשמריצים את הסוכן (לדוגמה, בסקריפט בדיקה), הסוכן מחזיר אירועים שמכילים את grounding_metadata. אפשר לעבור על grounding_chunks במטא-נתונים ולבדוק את המאפיין maps.

בדוגמה הבאה אפשר לראות איך בודקים את המאפיין maps, בדומה למה שאפשר לעשות בבדיקה אוטומטית:

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. חילוץ קווים פוליגוניים מקודדים

בנוסף לווידוא שההארקה התרחשה, יכול להיות שתרצו לחלץ נתונים ספציפיים כמו נתיבי מסלולים. כשכלי ההארקה של מפות מחזיר מידע על מסלול, הוא כולל לעיתים קרובות 'קו פוליגוני מקודד' שאפשר להשתמש בו כדי להציג את המסלול בחלק הקדמי של מפה.

אפשר למצוא את הקו הפוליגוני הזה בטקסט שבמאפיין maps של התג grounding_chunks. דוגמה לאופן שבו אפשר לזהות את זה:

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. הסרת המשאבים

כדי להימנע מחיובים שוטפים בחשבון Google Cloud, מוחקים את המשאבים שנוצרו במהלך ה-codelab הזה.

1. אם יצרתם פרויקט ייעודי בשביל ה-Codelab הזה, מוחקים אותו לגמרי:

gcloud projects delete $PROJECT_ID

אם השתמשתם בפרויקט קיים ואתם רוצים לשמור אותו, אין משאבים ספציפיים למחיקה, כי הסוכן פעל באופן מקומי והממשקי ה-API שבהם נעשה שימוש הם בלי שרת (serverless).

10. מזל טוב

מעולה! יצרתם בהצלחה סוכן לתכנון מסלולי טיול, והגדרתם לו קרקוע באמצעות תובנות ממפות Google.

מה למדתם

• איך ליצור סוכן חדש באמצעות ערכת המתחילים של סוכנים
• איך מוסיפים כלי ביסוס להגדרת סוכן ADK
• איך בודקים סוכן ADK באמצעות כלי האינטרנט המובנה להרצת סוכנים

השלבים הבאים

• כלי ADK נוספים ודפוסי שילוב

מסמכי עזר

• מסמכי תיעוד של ADK
• הארקה של מפות Google