الكلمة الافتتاحية لمؤتمر Next‏ 2026 للمطوّرين: إنشاء وكلاء ADK باستخدام المهارات والأدوات

1- مقدمة

في هذا الدرس التطبيقي حول الترميز، ستنشئ وكيل تخطيط الماراثون متطوّرًا باستخدام "حزمة تطوير الوكلاء" (ADK). ستدرس تدريجيًا إمكانات الوكيل، بدءًا من تعليمات النظام المنظَّمة جيدًا وصولاً إلى التحميل الديناميكي للمهارات وربط أدوات بروتوكول Model Context Protocol (MCP). أخيرًا، ستختبر الوكيل محليًا وتنشره على Agent Runtime (Agent Engine).

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

  • تهيئة مشروع وكيل ADK جديد
  • إنشاء تعليمات نظام قوية باستخدام أداة إنشاء منظَّمة
  • إضافة أدوات بروتوكول Model Context Protocol (MCP) من "خرائط Google" لسياق الموقع الجغرافي الفعلي
  • تحميل المهارات بشكل ديناميكي في مجموعة أدوات الوكيل
  • اختبار تنفيذ الوكيل محليًا
  • نشر الوكيل على Agent Engine (Cloud Run)

المتطلبات

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

هذا الدرس التطبيقي حول الترميز مخصّص للمطوّرين ذوي الخبرة المتوسطة الذين يتطلّعون إلى إنشاء وكلاء ذكاء اصطناعي توليدي متخصصين.

المدة المقدّرة: 45 دقيقة

من المفترض أن تقلّ تكلفة الموارد التي تم إنشاؤها في هذا الدرس التطبيقي حول الترميز عن 2 دولار أمريكي.

2. قبل البدء

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

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

بدء Cloud Shell

Cloud Shell هي بيئة سطر أوامر تعمل على Google Cloud ومحمّلة مسبقًا بالأدوات اللازمة.

  1. انقر على تفعيل Cloud Shell في أعلى Google Cloud Console.
  2. بعد الاتصال بـ Cloud Shell، تحقَّق من مصادقتك:
    gcloud auth list
  3. تأكَّد من ضبط مشروعك:
    gcloud config get project
  4. إذا لم يتم ضبط مشروعك على النحو المتوقّع، اضبطه:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

تحقَّق من المصادقة:

gcloud auth list

تأكَّد من مشروعك:

gcloud config get project

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

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

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

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

gcloud services enable \
  aiplatform.googleapis.com \
  run.googleapis.com \
  secretmanager.googleapis.com \
  mapstools.googleapis.com \
  storage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  serviceusage.googleapis.com

إنشاء مفتاح واجهة برمجة التطبيقات Google Maps API

لاستخدام أدوات بروتوكول Model Context Protocol (MCP) من "خرائط Google"، عليك إنشاء مفتاح Google Maps API.

  1. في Google Cloud Console، استخدِم شريط البحث للانتقال إلى منصة خرائط Google > بيانات الاعتماد.
  2. إذا طُلب منك ذلك، أكِّد مشروعك على Google Cloud.
  3. انقر على إنشاء بيانات اعتماد واختَر مفتاح واجهة برمجة تطبيقات.
  4. انسخ مفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه. ستحتاج إليه في الخطوة التالية.

3- إعداد البيئة

في هذا الدرس التطبيقي حول الترميز، تتم استضافة الرمز البرمجي على GitHub. ستنشئ نسخة طبق الأصل من المستودع الذي يحتوي على بنية الدليل والمكوّنات الفرعية المطلوبة (مثل الدليل skills/).

  1. أنشئ نسخة طبق الأصل من المستودع وانتقِل إلى مجلد المشروع:
git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/demo-1
  1. اضبط بيئة Python افتراضية وثبِّت "حزمة تطوير الوكلاء" (ADK):
uv venv
source .venv/bin/activate
uv sync
  1. اضبط مفتاح Google Maps API. يقرأ التطبيق هذا المفتاح من متغيّر بيئة:
export GOOGLE_MAPS_API_KEY="<YOUR_MAPS_API_KEY>"

ضبط متغيّرات البيئة

يستخدم وكيل المحاكاة ملف .env للإعداد. انسخ نموذج الملف وعدِّله باستخدام رقم تعريف مشروعك.

  1. انسخ نموذج ملف البيئة:
cp planner_agent/sample.env planner_agent/.env
  1. افتح planner_agent/.env وعدِّل الحقل GOOGLE_CLOUD_PROJECT باستخدام رقم تعريف مشروعك الفعلي على Google Cloud، وعدِّل الحقل GOOGLE_MAPS_API_KEY باستخدام مفتاح Google Maps API الذي أنشأته.

يجب أن يبدو الملف على النحو التالي:

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=global
GOOGLE_MAPS_API_KEY=<YOUR_MAPS_API_KEY>
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=true

4- إنشاء وكيل ADK جديد

استكشِف الملف الأساسي الذي يحدّد الوكيل: planner_agent/agent.py.

في مستودع build-agents-with-skills، تتم تهيئة الوكيل باستخدام فئة Agent في "حزمة تطوير الوكلاء" (ADK). تحدّد هذه الفئة النموذج الأساسي واسم الهوية، وتجلب التعليمات والأدوات المحدّدة في الوحدات الأخرى.

افتح planner_agent/agent.py للاطّلاع على رمز التهيئة:

instruction="Answer user questions to the best of your knowledge"
description="A helpful assistant for user questions."
tools=[]

# ...

root_agent = Agent(
    model='gemini-3-flash-preview',
    name='planner_agent',
    description=description,
    instruction=instruction,
    tools=tools
)

تجرّد فئة Agent سجلّ الرسائل وتنسيق الأدوات والتواصل مع النموذج اللغوي الكبير، ما يتيح لك التركيز على سلوك الوكيل.

في الوقت الحالي، يكون الوكيل عامًا جدًا. يمكنك التفاعل معه مثل أي نموذج لغوي كبير آخر.

uv run adk run planner_agent

سيؤدي هذا الأمر إلى بدء محادثة مع الوكيل. يستخدم هذا الأمر gemini-3-flash-preview كنموذج له ويمكنه الإجابة عن الأسئلة الأساسية.

Running agent planner_agent, type exit to exit.
[user]: What is the length of a Marathon
[planner_agent]: The official length of a marathon is **26.2 miles**, which is
equivalent to **42.195 kilometers**.

يعرف الوكيل بعض الحقائق عن سباقات الماراثون. ومع ذلك، لا يكفي ذلك لتخطيط ماراثون مناسب يتضمّن قواعد وتخطيطًا للمسار.

5- إنشاء تعليمات النظام

تحدّد تعليمات النظام (التعليمات) سلوك الوكيل. بدلاً من سلسلة كبيرة واحدة، يستخدم هذا المشروع PromptBuilder (planner_agent/utils.py) لإنشاء التعليمات بشكل ديناميكي.

افتح planner_agent/prompts.py للاطّلاع على كيفية تنظيم التعليمات في أقسام منطقية:

from collections import OrderedDict
from .utils import PromptBuilder

ROLE = """\
...
"""

RULES = """\
...
"""

WORKFLOW = """\
...
"""

###

# Planner instructions with no tools mentioned
PLANNER_INSTRUCTION_NO_TOOLS = PromptBuilder(
    OrderedDict(
        role=ROLE,
        rules=RULES,
        tools=TOOLS_PROMPT_ONLY,
        workflow=WORKFLOW_PROMPT_ONLY,
    )
).build()

# Planner instruction with skills and tools defined
PLANNER_INSTRUCTION = PromptBuilder(
    OrderedDict(
        role=ROLE,
        rules=RULES,
        skills=SKILLS,
        tools=TOOLS,
        workflow=WORKFLOW,
    )
).build()

في planner_agent/agent.py، تم استيراد هذا الملف مسبقًا.

ابحث عن القسم الذي يحتوي على TODO: Replace Instruction and Description وأزِل التعليق من عملية إعادة تعيين متغيّرات instruction وdescription.

يجب أن يبدو هذا القسم من الرمز البرمجي على النحو التالي:

instruction=PLANNER_INSTRUCTION_NO_TOOLS
description="Expert GIS analyst for marathon route and event planning."

أنت تستورد إصدارًا من التعليمات للوكيل لا يشير إلى أي أدوات. ستضيف الأدوات في خطوة لاحقة.

يمكنك اختبار هذا الإصدار من الوكيل:

uv run adk run planner_agent

في نافذة المحادثة، أرسِل التعليمات التالية:

Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

بعد بضع لحظات، من المفترض أن تتلقّى ردًا مشابهًا لما يلي:

Running agent planner_agent, type exit to exit.
[user]: Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the evening timeframe
[planner_agent]: Here is the comprehensive marathon plan for Las Vegas.

As requested, I have designed this event for an evening start on April 24, 2027. Because certain parameters (theme and budget) were not specified, I have applied pragmatic defaults: this will be a "Neon Nights" scenic theme to capitalize on the evening Strip, operating on a moderate-to-high budget given the infrastructure needed to secure major Las Vegas corridors.

### 1. Intent Alignment
*   **City & Theme:** Las Vegas, Nevada. Theme: "Neon Nights" an evening race maximizing the visual impact of the illuminated city.
*   **Date & Time:** Saturday, April 24, 2027. Late April evenings in Las Vegas offer optimal running weather (temperatures dropping from ~70°F at sunset to ~60°F). Race start is 6:30 PM (sunset is approx. 7:20 PM).
...
...

باستخدام تعليمات محدّدة جيدًا، تكون النتيجة قريبة جدًا من النتيجة المتوقّعة. في الخطوة التالية، ستضيف أدوات لنقل الوكيل إلى المستوى التالي.

6- إضافة المهارات والأدوات

لتفعيل المهارات والأدوات في planner_agent/agent.py، ابحث عن القسم الذي يحتوي على TODO: Replaces Tools وأزِل التعليق من السطرَين التاليَين. يجب أن يبدو الرمز البرمجي على النحو التالي:

instruction=PLANNER_INSTRUCTION
tools=get_tools()

هذا هو التغيير الوحيد المطلوب في الرمز البرمجي في هذه الخطوة. يشرح الجزء المتبقي من هذا القسم المفاهيم الأساسية للمهارات والأدوات.

المهارات

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

بالنسبة إلى وكيل تخطيط الماراثون، تم تحديد 3 مهارات:

  1. gis-spatial-engineering : مسؤولة عن معالجة بيانات GeoJSON لإنشاء مسار الماراثون.
  2. mapping : استخدام أدوات "خرائط Google" للبحث عن الأماكن ومعلومات الطقس.
  3. race-director : التحقّق من أنّ مسار الماراثون يتّبع إرشادات التخطيط.

يمكن أن تتضمّن المهارات نصوصًا برمجية وملفات أصول ومراجع إضافية.

يحمِّل التطبيق جميع المهارات ويوفّرها كأدوات في planner_agent/tools.py. لاحظ كيفية إجراء ذلك في الدالة get_tools():

def get_tools() -> list:
    """Build the planner's tool list with lazy-loaded skills."""
    from google.adk.code_executors.unsafe_local_code_executor import UnsafeLocalCodeExecutor

    skills_dir = pathlib.Path(__file__).parent / "skills"

    skills = []
    if skills_dir.exists():
        skills = [
            load_skill_from_dir(d)
            for d in sorted(skills_dir.iterdir())
            if d.is_dir() and not d.name.startswith("_") and (d / "SKILL.md").exists()
        ]

    additional_tools = _load_additional_tools(skills_dir)

    skill_toolset = SkillToolset(
        skills=skills,
        code_executor=UnsafeLocalCodeExecutor(),
        additional_tools=additional_tools,
    )

    tools = [
        skill_toolset,
        PreloadMemoryTool(),
    ]

    tools.extend(get_maps_tools())

    return tools

الجزء الأكثر إثارة للاهتمام هو طريقة load_skill_from_dir من "حزمة تطوير الوكلاء" (ADK). هناك طريقة أخرى لإنشاء المهارات في "حزمة تطوير الوكلاء" (ADK)، وهي مضمّنة. على الرغم من عدم استخدامها في هذا الدرس التطبيقي حول الترميز، تبدو هذه الطريقة على النحو التالي:

from google.adk.skills import models

greeting_skill = models.Skill(
    frontmatter=models.Frontmatter(
        name="greeting-skill",
        description=(
            "A friendly greeting skill that can say hello to a specific person."
        ),
    ),
    instructions=(
        "Step 1: Read the 'references/hello_world.txt' file to understand how"
        " to greet the user. Step 2: Return a greeting based on the reference."
    ),
    resources=models.Resources(
        references={
            "hello_world.txt": "Hello! So glad to have you here!",
            "example.md": "This is an example reference.",
        },
    ),
)

إضافة أدوات التعيين

يحتاج مخطِّط الماراثون إلى سياق مكاني لإنشاء المسارات. يمكنك توفير ذلك من خلال دمج خادم بروتوكول Model Context Protocol (MCP) من "خرائط Google".

في planner_agent/tools.py، لاحظ كيفية تسجيل خادم بروتوكول Model Context Protocol (MCP) باستخدام أداة ApiRegistry:

from google.adk.integrations.api_registry import ApiRegistry

class MapsApiRegistry(ApiRegistry):
    """ApiRegistry subclass that strips ADC headers to force API key auth."""

    def get_toolset(self, *args, **kwargs):  # noqa: ANN002, ANN003
        toolset = super().get_toolset(*args, **kwargs)
        conn = getattr(toolset, "_connection_params", None)
        headers = getattr(conn, "headers", None) if conn else None
        if headers:
            headers.pop("Authorization", None)  # type: ignore[union-attr]
            headers.pop("x-goog-user-project", None)  # type: ignore[union-attr]
        return toolset

def get_maps_tools() -> list:
    """Return Maps MCP toolset if configured."""
    project_id = os.getenv("GOOGLE_CLOUD_PROJECT", "").strip()
    maps_key = _resolve_maps_key()

    if not project_id or not maps_key:
        return []

    # Map the MCP server location on Google Cloud
    mcp_server_name = f"projects/{project_id}/locations/global/mcpServers/google-mapstools.googleapis.com-mcp"
    
    # Initialize the custom API registry that supports header injection
    api_registry = MapsApiRegistry(
        api_registry_project_id=project_id,
        header_provider=header_provider,
    )
    return [api_registry.get_toolset(mcp_server_name=mcp_server_name)]

من خلال إضافة مجموعة أدوات بروتوكول Model Context Protocol (MCP)، يكتسب الوكيل تلقائيًا القدرة على طلب تفاصيل التوجيه والارتفاع والموقع الجغرافي من "خرائط Google".

7- تشغيل الوكيل محليًا

بعد ربط الوكيل والتعليمات والأدوات معًا، شغِّل الوكيل محليًا. في هذه المرة، ستستخدم adk web حتى تتمكّن من الاطّلاع على أحداث تحميل المهارات واستدعاء الأدوات.

uv run adk web

من المفترض أن يظهر لك ما يلي:

INFO:     Started server process [99665]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
  1. افتح المتصفّح وانتقِل إلى عنوان URL المعروض في الوحدة الطرفية (عادةً http://localhost:8000).
  2. في القائمة المنسدلة أعلى يمين الشاشة، اختَر planner_agent.
  3. في نافذة المحادثة، أرسِل التعليمات التالية:
Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

من المفترض أن تظهر لك المهارات التي يتم تحميلها والأدوات التي يتم استدعاؤها. بعد بضع لحظات، سينشئ الوكيل خطة ماراثون.

يجب أن تبدو واجهة المستخدم على النحو التالي:

واجهة مستخدم ADK على الويب

8- نشر الوكيل

إذا كنت راضيًا عن أداء الوكيل محليًا، يمكنك نشره على Agent Engine، الذي يستضيف الوكيل على Cloud Run بشكل آمن.

لنشر الوكيل، استخدِم أمر النشر في ADK CLI:

uv run adk deploy agent_engine \
  --env_file planner_agent/.env --region=us-central1 \
  planner_agent

عند اكتمال عملية النشر، تعرض واجهة سطر الأوامر نقطة نهاية مستضافة بشكل آمن للوكيل. يمكنك الآن دمج نقطة النهاية هذه في تطبيقات الواجهة الأمامية أو برامج روبوت المحادثة أو أنظمة الواجهة الخلفية الأخرى. يمكنك أيضًا استخدام Agent Runtime Playground لاختبار الوكيل.

تبدو النتيجة على النحو التالي:

Files and dependencies resolved
Deploying to agent engine...
✅ Created agent engine: projects/<PROJECT_ID>/locations/us-west1/reasoningEngines/<AGENT_ID>

يمكنك استخدام النص البرمجي Python المقدَّم للتواصل مع الوكيل.

  1. انسخ نموذج ملف البيئة:
cp sample.env .env
  1. افتح .env وعدِّل الحقل GOOGLE_CLOUD_PROJECT باستخدام رقم تعريف مشروعك الفعلي على Google Cloud.

يجب أن يبدو الملف على النحو التالي:

GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-central1
  1. يمكنك إدراج الوكلاء في مشروعك.
python main.py list

من المفترض أن يظهر لك ما يلي:

Listing deployed agents...

ID: <AGENT_ID> | Display Name: planner_agent

بعد الحصول على رقم تعريف الوكيل الذي تم نشره، يمكنك إرسال تعليمات:

export AGENT_ID=<AGENT_ID>

python main.py prompt --agent-id ${AGENT_ID} --message "Plan a marathon for
10000 participants in Las Vegas on April 24, 2027 in the evening timeframe"

ستظهر لك نتيجة على النحو التالي:

Streaming response from agent <AGENT_ID>:

{'model_version': 'gemini-3-flash-preview', 'content': {'parts': [{'text': 'Here is a comprehensive
...
...
...

9- تَنظيم

لتجنُّب فرض رسوم مستمرة على حسابك على Google Cloud، احذف الموارد التي تم إنشاؤها خلال هذا الدرس التطبيقي حول الترميز.

احذف خدمة Cloud Run التي أنشأها النشر:

python main.py delete --agent-id ${AGENT_ID}

إذا خزّنت مفتاح Google Maps API في Secret Manager، احذف السر:

gcloud secrets delete maps-api-key --project=$PROJECT_ID

إذا أنشأت مشروعًا جديدًا على Google Cloud لهذا الدرس التطبيقي حول الترميز، يمكنك حذف المشروع بأكمله لإزالة جميع الموارد وواجهات برمجة التطبيقات المرتبطة به:

gcloud projects delete $PROJECT_ID

10- تهانينا

تهانينا! لقد أنشأت وكيل تخطيط الماراثون متطوّرًا باستخدام "حزمة تطوير الوكلاء" (ADK).

ما الذي تعلّمته

  • تهيئة مشروع "حزمة تطوير الوكلاء" (ADK)
  • استخدام PromptBuilder لتعليمات النظام النمطية
  • دمج إمكانات التعيين باستخدام أدوات بروتوكول Model Context Protocol (MCP) وApiRegistry
  • تحميل المهارات بشكل مشروط باستخدام SkillToolset
  • الاختبار محليًا والنشر على Agent Engine

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