ساخت یک عامل برنامه‌ریزی سفر با ADK و Google Maps Grounding

۱. مقدمه

در این آزمایشگاه کد، شما با استفاده از کیت توسعه عامل (ADK) و اتصال آن به نقشه‌های گوگل، یک عامل برنامه‌ریزی سفر خواهید ساخت. شما با استفاده از داده‌های دنیای واقعی از نقشه‌های گوگل، از عامل می‌خواهید که مسیرهای خوش‌منظره و توصیه‌های رستوران تولید کند .

کاری که انجام خواهید داد

• راه‌اندازی اولیه یک پروژه عامل با استفاده از بسته شروع‌کننده عامل
• پیکربندی اپراتور برای استفاده از ابزار Google Maps Grounding
• عامل حاصل را به صورت محلی با یک رابط وب آزمایش کنید

آنچه نیاز دارید

• یک مرورگر وب مانند کروم
• یک پروژه گوگل کلود با قابلیت پرداخت صورتحساب

این آزمایشگاه کد برای توسعه‌دهندگان سطح متوسط ​​است که با پایتون و گوگل کلود آشنایی دارند، اما لزوماً متخصص نیستند.

۲. قبل از شروع

ایجاد یک پروژه ابری گوگل

1. در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید .
2. مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .

شروع پوسته ابری

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

۳. بسته‌ی آغازین Agent را نصب کنید

ساده‌ترین راه برای شروع یک پروژه ADK استفاده از Agent Starter Pack است. Google Cloud Agent Starter Pack یک ابزار رابط خط فرمان (CLI) متن‌باز است که برای تسریع توسعه و استقرار عامل‌های هوش مصنوعی مولد آماده برای تولید در Google Cloud طراحی شده است.

1. مطمئن شوید که uv نصب شده است، سپس دستور create را برای راه‌اندازی اولیه یک پروژه عامل جدید اجرا کنید:

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 (عامل واکنش ساده)
• استقرار : none (استقرار ابری فعلاً غیرفعال است)
• منطقه : us-central1

این یک ساختار دایرکتوری پروژه ایجاد می‌کند که شامل منطق عامل اصلی، تست‌ها و راهنمای GEMINI.md شما است. به دایرکتوری جدید خود بروید:

cd my-agent

۴. پیکربندی اتصال زمین

بسته‌ی آغازین Agent یک فایل GEMINI.md ایجاد می‌کند که ابزارهای کدنویسی مبتنی بر هوش مصنوعی را در مورد نحوه‌ی مدیریت پروژه‌ی شما آموزش می‌دهد. ما این فایل را به‌روزرسانی خواهیم کرد تا مستندات Google Maps Grounding را نیز شامل شود.

1. GEMINI.md در ویرایشگر خود باز کنید.
2. لینک مرجع زیر را در بخش ## Reference Documentation اضافه کنید:

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

این زمینه به هر دستیار کدنویسی هوش مصنوعی کمک می‌کند تا ویژگی اتصال به زمین را درک کند.

۵. به‌روزرسانی عامل

حالا ما عامل را طوری پیکربندی می‌کنیم که به عنوان یک برنامه‌ریز سفر عمل کند، و ابزار Google Maps Grounding را نیز به آن اضافه می‌کنیم.

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 مراجعه کنید.

۶. عامل را اجرا کنید

با منطق عامل خود، سعی کنید آن را در رابط وب محلی خود آزمایش کنید.

1. از ریشه دایرکتوری my-agent خود، دستور زیر را برای شروع برنامه وب اجرا کنید:

uv run adk web

یا اگر از یک محیط مجازی استفاده می‌کنید:

adk web

2. URL ارائه شده در خروجی ترمینال را در مرورگر خود باز کنید.
3. با پرسیدن یک سوال از عامل، آن را آزمایش کنید. برای مثال:

• «یک برنامه سفر یک روزه در سانفرانسیسکو، شامل یک رستوران ایتالیایی خوب، برنامه‌ریزی کنید.»
• «من دارم به توکیو سفر می‌کنم، می‌توانید یک برنامه سفر با جاذبه‌های تاریخی جالب و یک رستوران رامن با امتیاز بالا و فضایی دنج به من بدهید؟»

شما باید خروجی مشابه یک برنامه سفر دقیق غنی شده با نظرات واقعی و توضیحات مسیر که مستقیماً از Google Maps گرفته شده است را ببینید.

۷. اتصال زمین را در کد تأیید کنید

برای تأیید برنامه‌نویسی‌شده‌ی اینکه عامل شما با موفقیت از Maps grounding استفاده می‌کند، می‌توانید رویدادهای پاسخ را برای ابرداده‌های خاص Maps بررسی کنید.

وقتی عامل خود را اجرا می‌کنید (برای مثال، در یک اسکریپت آزمایشی)، عامل رویدادهایی را ارائه می‌دهد که حاوی 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!")

۸. استخراج چندخطی‌های کدگذاری‌شده

علاوه بر تأیید وقوع اتصال به زمین، ممکن است بخواهید داده‌های خاصی مانند مسیرهای مسیر را استخراج کنید. هنگامی که ابزار اتصال به زمین Maps اطلاعات مسیر را برمی‌گرداند، اغلب شامل یک "چندخطی کدگذاری شده" است که می‌تواند برای رندر مسیر در نمای نقشه استفاده شود.

شما می‌توانید این چندخطی را با بررسی متن درون ویژگی 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!")

۹. تمیز کردن

برای جلوگیری از هزینه‌های مداوم برای حساب Google Cloud خود، منابع ایجاد شده در طول این codelab را حذف کنید.

1. اگر یک پروژه اختصاصی برای این آزمایشگاه کد ایجاد کرده‌اید، آن را به‌طور کامل حذف کنید:

gcloud projects delete $PROJECT_ID

اگر از یک پروژه موجود استفاده کرده‌اید و می‌خواهید آن را نگه دارید، هیچ منبع خاصی برای حذف ندارید، زیرا Agent به صورت محلی اجرا می‌شود و APIهای مورد استفاده بدون سرور هستند.

۱۰. تبریک

تبریک می‌گویم! شما با موفقیت یک برنامه‌ریز سفر ساختید و آن را با استفاده از بینش‌های نقشه‌های گوگل (Google Maps insights) راه‌اندازی کردید.

آنچه آموخته‌اید

• نحوه ایجاد یک عامل جدید با استفاده از Agent Starter Pack
• نحوه اضافه کردن ابزارهای اتصال به زمین به تعریف ADK Agent
• نحوه آزمایش یک عامل ADK با استفاده از اجراکننده وب داخلی

مراحل بعدی

• سایر ابزارهای ADK و الگوهای ادغام را بررسی کنید

اسناد مرجع

• مستندات ADK
• اتصال به زمین در نقشه‌های گوگل