إنشاء وكيل لتخطيط برامج الرحلات باستخدام حزمة ADK و"خرائط Google" كمصدر

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، ستنشئ وكيل تخطيط رحلات باستخدام "حزمة تطوير الوكلاء" (ADK) وستربطه بخدمة "خرائط Google". ستطلب من الوكيل إنشاء طرق ذات مناظر خلابة واقتراحات بشأن المطاعم، وذلك بالاستفادة من بيانات من أرض الواقع من "خرائط Google".

الإجراءات التي ستنفذّها

• بدء مشروع وكيل باستخدام حزمة المبتدئين لإنشاء الوكلاء
• ضبط الوكيل لاستخدام أداة Google Maps Grounding
• اختبار الوكيل الناتج محليًا باستخدام واجهة ويب

المتطلبات

• متصفّح ويب، مثل Chrome
• مشروع Google Cloud تم تفعيل الفوترة فيه

هذا الدرس التطبيقي حول الترميز مخصّص للمطوّرين المتوسطي الخبرة الذين لديهم بعض المعرفة بلغة Python وGoogle Cloud، ولكن ليس بالضرورة أن يكونوا خبراء.

2. قبل البدء

إنشاء مشروع على Google Cloud

1. في Google Cloud Console، في صفحة اختيار المشروع، اختَر مشروعًا على Google Cloud أو أنشِئ مشروعًا.
2. تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع

بدء Cloud Shell

1. إثبات صحة المصادقة:

gcloud auth list

2. أكِّد مشروعك:

gcloud config get project

3. اضبطه إذا لزم الأمر:

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

تفعيل واجهات برمجة التطبيقات

نفِّذ الأمر التالي لتفعيل جميع واجهات برمجة التطبيقات المطلوبة:

gcloud services enable \
  aiplatform.googleapis.com

3- تثبيت حزمة المبتدئين لإنشاء الوكلاء

أسهل طريقة لبدء مشروع ADK هي استخدام "حزمة المبتدئين لإنشاء الوكلاء". حزمة Google Cloud Agent Starter Pack هي أداة مفتوحة المصدر لواجهة سطر الأوامر (CLI) مصمَّمة لتسريع عملية تطوير ونشر وكلاء الذكاء الاصطناعي التوليدي الجاهزين للاستخدام في بيئة الإنتاج على 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

يمكنك الاطّلاع على مستودع حزمة أدوات المساعدة للموظفين لمزيد من التفاصيل.

2. عندما يُطلب منك ذلك، قدِّم الخيارات التالية لإعداد مشروعك للتطوير المحلي باستخدام واجهة أمامية React:

• نموذج الوكيل: adk (وكيل بسيط يستند إلى React)
• النشر: none (تم إيقاف ميزة "النشر على السحابة الإلكترونية" حاليًا)
• المنطقة: us-central1

سيؤدي ذلك إلى إنشاء بنية دليل مشروع تحتوي على منطق الوكيل الرئيسي والاختبارات ودليل GEMINI.md. انتقِل إلى الدليل الجديد:

cd my-agent

4. ضبط Grounding

تنشئ "حزمة أدوات المطورين" ملف GEMINI.md يقدّم تعليمات لأدوات الترميز المستندة إلى الذكاء الاصطناعي حول كيفية إدارة مشروعك. سنعدّل هذه الصفحة لتتضمّن مستندات حول ميزة Grounding في "خرائط 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

سيساعد هذا السياق أي مساعدات ترميز مستندة إلى الذكاء الاصطناعي في فهم ميزة "الاستناد إلى المستندات".

5- تعديل الوكيل

سنضبط الآن الوكيل ليعمل كمخطِّط لبرامج الرحلات، مع استخدام أداة Grounding من "خرائط 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. التحقّق من تحديد المصدر في الرمز

للتأكّد آليًا من أنّ وكيلك يستخدم ميزة "الاستناد إلى خرائط Google" بنجاح، يمكنك فحص أحداث الردود بحثًا عن البيانات الوصفية الخاصة بـ "خرائط Google".

عند تشغيل الوكيل (على سبيل المثال، في نص برمجي اختباري)، يعرض الوكيل أحداثًا تحتوي على 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، احذف الموارد التي تم إنشاؤها أثناء هذا الدرس العملي.

1. إذا أنشأت مشروعًا مخصّصًا لهذا الدرس البرمجي، احذفه بالكامل:

gcloud projects delete $PROJECT_ID

إذا كنت قد استخدمت مشروعًا حاليًا وأردت الاحتفاظ به، ليس لديك أي موارد معيّنة لحذفها، لأنّ الوكيل تم تشغيله محليًا وكانت واجهات برمجة التطبيقات المستخدَمة بلا خادم.

10. تهانينا

تهانينا! لقد أنشأت بنجاح وكيل تخطيط لبرنامج الرحلة واستندت إليه باستخدام إحصاءات "خرائط Google".

ما تعلّمته

• كيفية إنشاء بنية أساسية لوكيل جديد باستخدام "حزمة بدء استخدام الوكيل"
• كيفية إضافة أدوات تحديد المعلومات الأساسية إلى تعريف "وكيل حزمة تطوير التطبيقات"
• كيفية اختبار وكيل ADK باستخدام أداة التشغيل المضمّنة على الويب

الخطوات التالية

• استكشاف أدوات حزمة تطوير التطبيقات (ADK) وأنماط الدمج الأخرى

المستندات المرجعية

• مستندات حزمة تطوير التطبيقات على Android
• الاستناد إلى بيانات "خرائط Google"