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

1. مقدمة

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

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

  • إعداد مشروع وكيل ADK جديد
  • إنشاء تعليمات نظام قوية باستخدام أداة إنشاء منظَّمة
  • إضافة أدوات بروتوكول Model Context في "خرائط 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".
  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

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

  1. في Google Cloud Console، استخدِم شريط البحث للانتقال إلى منصة خرائط Google > بيانات الاعتماد.
  2. أكِّد مشروعك على Google Cloud إذا طُلب منك ذلك.
  3. انقر على إنشاء بيانات اعتماد واختَر مفتاح API.
  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. اضبط مفتاح 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=us-west1
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 في "حزمة تطوير التطبيقات". تحدّد هذه السمة النموذج الأساسي واسم الهوية، وتستند إلى التعليمات والأدوات المحدّدة في الوحدات الأخرى.

افتح 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. الخرائط: يمكنك استخدام أدوات "خرائط 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.",
        },
    ),
)

إضافة أدوات الربط

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

في planner_agent/tools.py، لاحظ كيف تم تسجيل خادم 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)]

من خلال إضافة مجموعة أدوات 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 بأمان.

لنشر الوكيل، استخدِم أمر النشر في واجهة سطر الأوامر لحزمة نشر الوكلاء:

uv run adk deploy agent_engine \
  --env_file planner_agent/.env \
  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-west1
  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}

إذا خزّنت مفتاح Maps API في Secret Manager، احذف السرّ باتّباع الخطوات التالية:

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

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

gcloud projects delete $PROJECT_ID

10. تهانينا

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

ما تعلّمته

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

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