1. 1. نظرة عامة
في هذا الدرس التطبيقي، ستنشئ نظامًا متعدّد الوكلاء يصمّم حلبة سباق Formula E ويحصل على الموافقة عليها وفقًا لمجموعة مبسّطة من قواعد الاتحاد الدولي للسيارات (FIA).
ستستخدم agents-cli لإنشاء مشروعَين عاديَين من مشاريع Agent Development Kit (ADK)، ثم كتابة الأجزاء المهمة: مهارة وكيل وثلاثة وكلاء وتقييم. ويتم الحصول على كل شيء آخر (تنسيق المشروع والخادم والتبعيات وإعدادات النشر) من واجهة سطر الأوامر.
هل أنت جديد في Formula E؟
لست بحاجة إلى معرفة رياضة السيارات. هذه المصطلحات الخمسة كافية:
- فورمولا إي: بطولة سباقات السيارات الكهربائية بالكامل التي ينظّمها الاتحاد الدولي للسيارات. وتُقام معظم السباقات على حلبات شوارع مؤقتة في مراكز المدن.
- المصادقة: هي الموافقة الرسمية من الاتحاد الدولي للسيارات على أنّ الحلبة آمنة للسباق. بدون المصادقة، لن يكون هناك سباق.
- الكبح المتجدد: عندما تضغط على فرامل السيارة، تعيد المحركات شحن البطارية. كلما زادت قوة الفرملة، زادت الطاقة المستردة، لذا تتطلب قواعد هذا الدرس التطبيقي حول الترميز منطقة فرملة قوية واحدة على الأقل.
- طبقات CAD: طبقات مُسمّاة في رسومات تصميم الحلبة، مثل خط السباق ومسار الصيانة والحواجز. يتحقّق الاتحاد الدولي للسيارات من توفّر العناصر الإلزامية.
- وضع الهجوم: يحصل السائقون على تعزيز مؤقت للقوة من خلال القيادة عبر منطقة تفعيل تقع خارج خط السباق.
يؤدي الوكلاء دورَين: أحدهما يصمّم الحلبة، والآخران يتحقّقان من امتثالها لمعايير الاتحاد الدولي للسيارات.
ما ستنشئه
تمثّل المربّعات الخضراء الوكلاء، والمربّعات المتقطّعة أدواتهم، بالطريقة نفسها التي يرسمها بها ADK Playground. تتضمّن اثنتان من الأدوات وكلاء آخرين: fia_assessor هو وكيل FIA Assessor الذي يمتلك مهارة الامتثال لقانون FIA، وremote_gatekeeper يستدعي وكيل Gatekeeper في المشروع الآخر عبر A2A.
الوكيل | المشروع | الوظيفة |
|
مهندس معماري رئيسي |
| يقرأ المكان، ويسأل "المقيّم"، ويحلّ المشاكل، ويطلب موافقة "حارس البوابة" |
|
مقيِّم FIA |
| يتحقق من التخطيط باستخدام مهارة FIA وأداة تسجيل |
|
Digital Twin Gatekeeper |
| تشغيل قائمة التحقّق النهائية من الموافقة |
|
ما ستتعلمه
- كيفية تخطيط
agents-cli scaffold createلمشروع ADK، والملفات التي يمكنك تعديلها - كيفية تجميع المعرفة الخاصة بالمجال في شكل مهارة وكيل (
SKILL.mdوreferences/وscripts/) وتحميلها باستخدامSkillToolsetفي ADK - كيفية مطابقة
thinking_levelمع وظيفة كل وكيل - كيفية تقييم الوكلاء باستخدام
agents-cli eval run - كيفية نشر وكيل في Agent Runtime، وأوجه الاختلاف بين هوية الوكيل وحساب الخدمة، وكيفية استدعاء الوكيل المنشور عبر بروتوكول A2A.
2. 2. إعداد البيئة
قبل البدء
يجب أن يكون لديك مشروع على Google Cloud مع تفعيل الفوترة. إذا كنت تتّبع هذا الدرس التطبيقي حول الترميز في إحدى الفعاليات، استخدِم الحساب والمشروع اللذين تم منحهما لك.
فتح Cloud Shell وضبط مشروعك
افتح Cloud Shell، ثم شغِّل:
# Cloud Shell sometimes opens without a project set. If so, this sets it to
# the first project on your account.
if [ -z "$(gcloud config get-value project 2>/dev/null)" ]; then
gcloud config set project "$(gcloud projects list --format='value(projectId)' --limit=1)"
fi
export GOOGLE_CLOUD_PROJECT="$(gcloud config get-value project)"
export REGION="us-central1"
export ASSETS="$HOME/devrel-demos/codelabs/formula-e-track-planner"
echo "Project: $GOOGLE_CLOUD_PROJECT Region: $REGION"
إنشاء بيانات اعتماد للوكلاء
تم تسجيل الدخول إلى "gcloud"، ولكن رمز Python البرمجي الذي يشغّله وكلاؤك يستخدم بيانات الاعتماد التلقائية للتطبيق (ADC)، والتي تتطلّب تسجيل دخول منفصل:
gcloud auth application-default login
افتح الرابط الذي يظهر لك، وسجِّل الدخول باستخدام الحساب نفسه، وانسخ الرمز، والصقه مرة أخرى في Cloud Shell. بعد ذلك، اضبط المشروع الذي تتم فوترة الحصة له:
gcloud auth application-default set-quota-project "$GOOGLE_CLOUD_PROJECT"
تفعيل واجهات برمجة التطبيقات
gcloud services enable \
aiplatform.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
storage.googleapis.com \
cloudresourcemanager.googleapis.com \
serviceusage.googleapis.com \
compute.googleapis.com \
iam.googleapis.com \
logging.googleapis.com \
cloudtrace.googleapis.com
الغرض من كل واجهة برمجة تطبيقات:
واجهات برمجة التطبيقات | يتم الاستخدام مع |
| نماذج Gemini وAgent Runtime |
| عمليات التحقّق من المشروع والأذونات التي يتم إجراؤها من خلال |
| إنشاء حساب الخدمة التلقائي في Compute Engine الذي تستخدمه عملية النشر في الخطوة 7 |
| مساحة التخزين والسجلّات وعمليات التتبُّع، كما هو مقترَح في دليل إعداد بيئة تشغيل الوكيل |
| عمليات إنشاء الحاويات والصور، المضمّنة كإجراء وقائي للنشر في الخطوة 7 |
وقد تم تفعيل بعض هذه الميزات في العديد من المشاريع. لن يؤدي تفعيل واجهة برمجة تطبيقات مفعَّلة إلى أي تغيير.
تثبيت "uv" و"agents-cli"
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
uv tool install google-agents-cli==1.10.0
agents-cli --version
تم اختبار هذا الدرس التطبيقي حول الترميز باستخدام الإصدار 1.10.0 من agents-cli، لذا عليك تثبيت هذا الإصدار للحصول على الملفات نفسها التي تم إنشاؤها.
3- 3- إنشاء هيكل للمشاريع وإضافة مواد العرض
إنشاء المشروعَين
تنشئ أداة agents-cli scaffold create مشروع ADK كاملاً وقابلاً للنشر. شغِّل الأداة مرتين، مرة لكل نظام وكيل.
أولاً، مخطِّط المسار:
cd ~
agents-cli scaffold create track-planner \
--agent adk \
--deployment-target agent_runtime \
--region "$REGION" \
--prototype \
--yes
بعد ذلك، يتّبع حارس البوابة الخطوات التالية:
cd ~
agents-cli scaffold create gatekeeper \
--agent adk \
--deployment-target agent_runtime \
--region "$REGION" \
--prototype \
--yes
علم | المعنى |
| البدء من نموذج Python ADK |
| إنشاء الخادم والإعدادات لبيئة تشغيل الوكيل |
| تخطّي CI/CD، والحفاظ على الحد الأدنى من المشروع |
| قبول الإعدادات التلقائية بدون طلب |
استكشاف التنسيق
يبدو المشروع الذي تم إنشاؤه على النحو التالي: يمكنك تعديل الملفات التي تحمل العلامة ✍️ فقط:
track-planner/
├── agents-cli-manifest.yaml # Records the template, deployment target and root agent name
├── pyproject.toml # Dependencies (google-adk, a2a-sdk, ...)
├── .env # Your project and model location, filled in for you
├── Dockerfile # Used by `agents-cli deploy`; copies app/ into the image
├── app/
│ ├── agent.py # ✍️ Your agents
│ ├── fast_api_app.py # Generated server: ADK API, A2A routes, Agent Runtime routes
│ └── app_utils/ # Generated helpers (A2A, sessions)
└── tests/
├── unit/ # Fast tests with no model calls
├── integration/ # Generated server tests
└── eval/ # ✍️ eval_config.yaml and datasets for `agents-cli eval`
للحصول على وصف لكل ملف تم إنشاؤه، يُرجى الاطّلاع على بنية المشروع في دليل Agents CLI.
تجربة الوكيل الذي تم إنشاؤه
قبل تغيير أي شيء، شغِّل وكيل النموذج لمعرفة ما يوفّره لك الإطار الأساسي. ثبِّت التبعيات وابدأ تشغيل بيئة الاختبار المحلية على المنفذ 8080:
cd ~/track-planner
agents-cli install
agents-cli playground --port 8080
لفتحها، انقر على زر معاينة الويب في شريط أدوات Cloud Shell (رمز العين في أعلى يسار الصفحة)، ثم اختَر معاينة على المنفذ 8080.
في ساحة التجربة، اطرح على الوكيل المستنِد إلى نموذج سؤالاً يمكن لأدواته الإجابة عنه، على سبيل المثال:
What's the weather in San Francisco?
تعرض اللوحة الجانبية كل حدث، بما في ذلك طلب الأداة get_weather ونتيجته. ستستخدم طريقة العرض نفسها لاحقًا لمتابعة وكلائك.
عند الانتهاء، ارجع إلى الوحدة الطرفية واضغط على Ctrl+C لإيقاف بيئة الاختبار.
إضافة مواد عرض Formula E
بيانات المكان وقواعد الاتحاد الدولي للسيارات والنص البرمجي للفيزياء والأدوات ومجموعات بيانات التقييم ليست جزءًا من الدرس، لذا يمكنك نسخها من GitHub بدلاً من كتابتها:
cd ~
git clone --depth 1 --filter=blob:none --sparse \
--branch formula-e-lab-v1 \
https://github.com/tdsymonds/devrel-demos.git
git -C devrel-demos sparse-checkout set codelabs/formula-e-track-planner
cp -r "$ASSETS/track-planner/." ~/track-planner/
cp -r "$ASSETS/gatekeeper/." ~/gatekeeper/
formula-e-lab-v1 هي علامة إصدار ثابتة، لذا يحصل الجميع على الملفات نفسها. تم ضبط $ASSETS في الخطوة 2 ويشير إلى المجلد الذي نسخته للتو.
يؤدي ذلك إلى إضافة الملفات التالية:
track-planner/
├── app/
│ ├── tools.py # get_track_topology, evaluate_track_layout
│ ├── auth.py # A2A client with per-request token refresh
│ ├── data/circuits.json # Five candidate venues
│ └── skills/fia-compliance-skill/
│ ├── references/track_regulations.md # The FIA rules
│ └── scripts/calculate_regen_zones.py # Braking-energy calculator
└── tests/
├── unit/test_tools.py
└── eval/datasets/track_eval.json, track_eval_quick.json
gatekeeper/
├── app/tools.py # verify_infrastructure_checklist
└── tests/unit/test_tools.py
التثبيت والاختبار
(cd ~/track-planner && agents-cli install && uv run pytest tests/unit)
(cd ~/gatekeeper && agents-cli install && uv run pytest tests/unit)
يُشغّل agents-cli install uv sync لإنشاء بيئة افتراضية لكل مشروع. يجب اجتياز جميع اختبارات الوحدات.
4. 4. كتابة مهارة الامتثال لقانون FIA
مهارة الوكيل هي حزمة من التعليمات والمستندات المرجعية والنصوص البرمجية في مجلد واحد. يُحمّل SkillToolset في ADK الملف على ثلاثة مستويات، لكي يقرأ الوكيل ما يحتاج إليه فقط:
المستوى | ملف | عندما يرى موظف الدعم هذه البيانات |
1 | | دائمًا (بضع عشرات من الرموز المميّزة) |
2 | جسم | عندما يتصل بـ |
3 | | عندما يتصل بـ |
تتوفّر المهارة في app/skills/ لأنّ ملف Dockerfile الذي تم إنشاؤه ينسخ app/ فقط إلى الصورة المنشورة.
اطّلِع على ملفات المستوى 3
لقد نسخت ملفات المستوى 3 للمهارة في الخطوة 3:
- يحتوي ملف
references/track_regulations.mdعلى القواعد التي يتحقّق منها "المقيِّم"، وهي: حدود الطول والعرض، والحواجز التي تحتاجها كل منطقة كبح، وطبقات CAD الإلزامية (بالإضافة إلى الطبقات الطبية لمسارات المستشفيات)، وهدف التجديد، وقواعد "وضع الهجوم". -
scripts/calculate_regen_zones.pyهي آلة حاسبة. من خلال معرفة سرعة الدخول إلى منطقة الكبح وسرعة الخروج منها ومسافة الكبح، يمكنه حساب الطاقة المستردة والحاجز الذي يحتاجه المنعطف، وبالتالي لا يحتاج الوكيل إلى تخمين قوانين الفيزياء.
شغِّل النص البرمجي للمنعطف العاشر في حلبة لندن، حيث تضغط السيارات على المكابح لخفض سرعتها من 215 إلى 55 كيلومتر في الساعة على مسافة 82 مترًا:
cd ~/track-planner
uv run python app/skills/fia-compliance-skill/scripts/calculate_regen_zones.py \
--entry-kph 215 --exit-kph 55 --brake-dist-m 82
تستعيد السيارة حوالي 508 كيلوواط هنا، وهو أعلى من الهدف البالغ 250 كيلوواط. وتتباطأ عند أكثر من 2G، لذا يحتاج المنعطف إلى حواجز Tecpro (F1_TEC3):
{"entry_kph": 215.0, "exit_kph": 55.0, "brake_dist_m": 82.0, "deceleration_g": 2.07, "estimated_regen_kw": 507.7, "meets_250kw_target": true, "required_barrier_layer": "F1_TEC3"}
كتابة SKILL.md
أنشئ الملف الذي يربط المهارة معًا:
cloudshell edit app/skills/fia-compliance-skill/SKILL.md
أضِف هذا المحتوى:
---
name: fia-compliance-skill
description: >
FIA Formula E street circuit rules: length and width limits, mandatory CAD
layers, barrier selection, and Gen3 regenerative braking estimates. Use when
designing, checking or fixing a Formula E circuit layout.
---
# FIA Formula E Compliance
Follow these steps for every circuit you check.
1. **Read the rules.** Call `load_skill_resource` with
`file_path="references/track_regulations.md"`.
2. **Estimate regeneration for every heavy braking zone.** Call
`run_skill_script` with `file_path="scripts/calculate_regen_zones.py"` and
`args={"entry-kph": <entry>, "exit-kph": <exit>, "brake-dist-m": <distance>}`.
Never guess kW values. Use the highest `estimated_regen_kw` as the
circuit's peak regeneration.
3. **Check barriers.** Any zone whose `required_barrier_layer` is `F1_TEC3`
needs the `F1_TEC3` CAD layer.
4. **Report.** List every rule the layout fails and a concrete fix for each
one.
يقرأ النموذج description لتحديد متى يجب استخدام المهارة، لذا يوضّح ما تغطيه المهارة ومتى يجب استخدامها.
الاطّلاع على كيفية ربط المهارة
افتح app/tools.py في "محرِّر Cloud Shell":
cloudshell edit app/tools.py
ابحث عن دالة build_fia_skill_toolset:
def build_fia_skill_toolset() -> SkillToolset:
return SkillToolset(
skills=[load_skill_from_dir(SKILL_DIR)],
code_executor=UnsafeLocalCodeExecutor(),
)
- يقرأ "
load_skill_from_dir" مجلد المهارات:SKILL.mdوreferences/وscripts/. - يحوّل
SkillToolsetهذه البيانات إلى أدوات يمكن للوكيل استدعاؤها:list_skillsوload_skillوload_skill_resourceوrun_skill_script. - يسمح
UnsafeLocalCodeExecutorلـ "run_skill_script" بتشغيل نص Python البرمجي على هذا الجهاز. هذا الإجراء مناسب للاستخدام في المختبر، ولكن يجب استخدام منفّذ في وضع الحماية في مرحلة الإنتاج.
ستربط مجموعة الأدوات هذه بالمقيِّم في الخطوة التالية.
5- 5- كتابة الوكلاء
تتحكّم نماذج Gemini 3 في الاستدلال باستخدام thinking_level (LOW أو MEDIUM أو HIGH) بدلاً من ميزانية الرموز المميّزة. في ADK، يمكنك ضبطه باستخدام types.ThinkingConfig(thinking_level=types.ThinkingLevel.HIGH). يجب اختيار النموذج المناسب لكل وكيل: فكلما زاد التفكير، تحسّن التخطيط، ولكن زاد وقت الاستجابة والتكلفة.
The Gatekeeper (LOW)
يُشغّل Gatekeeper قائمة تحقّق حتمية فقط، لذا لا يحتاج إلى الكثير من الاستدلال. استبدِل وكيل النموذج:
cloudshell edit ~/gatekeeper/app/agent.py
"""FIA Digital Twin Gatekeeper agent.
This agent runs in its own project and is deployed to Agent Runtime. The track
planner calls it over the A2A protocol.
"""
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types
from app.tools import verify_infrastructure_checklist
# Tested with Gemini 3.8 Flash. To try Gemini 4 Argon, change this to
# "gemini-4-argon", delete the `temperature` settings below (Argon ignores
# them) and run `uv add "google-genai>=2.30.1"` in this project first.
MODEL = "gemini-3.8-flash"
root_agent = Agent(
# Must match `root_agent_name` in agents-cli-manifest.yaml.
name="gatekeeper",
model=Gemini(
model=MODEL,
retry_options=types.HttpRetryOptions(attempts=3),
),
description=(
"FIA Digital Twin Gatekeeper. Runs the final homologation checklist "
"for a Formula E circuit blueprint."
),
instruction=(
"You are the FIA Digital Twin Gatekeeper. For every circuit blueprint "
"you receive, call `verify_infrastructure_checklist` with its circuit "
"ID, CAD layers, minimum width and peak regeneration. Reply with the "
"status and any missing CAD layers. Never approve a blueprint the "
"checklist rejects."
),
# A deterministic checklist needs little reasoning: keep it fast and cheap.
generate_content_config=types.GenerateContentConfig(
temperature=0.0,
thinking_config=types.ThinkingConfig(
thinking_level=types.ThinkingLevel.LOW,
),
),
tools=[verify_infrastructure_checklist],
)
app = App(
root_agent=root_agent,
name="app",
)
تشغيل Gatekeeper على الجهاز
افتح علامة تبويب ثانية في Cloud Shell وابدأ تشغيل الخادم الذي أنشأه Gatekeeper على المنفذ 8001:
cd ~/gatekeeper
APP_URL=http://localhost:8001 uv run uvicorn app.fast_api_app:app --port 8001
في علامة التبويب الأولى، انظر إلى بطاقة وكيل A2A في Gatekeeper. في ما يلي كيفية تعرُّف الوكلاء الآخرين على Gatekeeper وما يمكنه فعله:
curl -s http://localhost:8001/a2a/app/.well-known/agent-card.json | jq .
من المفترض أن يظهر لك ملف JSON على النحو التالي (مختصر):
{
"name": "gatekeeper",
"description": "FIA Digital Twin Gatekeeper. Runs the final homologation checklist for a Formula E circuit blueprint.",
"supportedInterfaces": [
{"url": "http://localhost:8001/a2a/app", "protocolBinding": "JSONRPC", "protocolVersion": "1.0"}
],
"skills": [
{"id": "gatekeeper", "name": "model", "description": "FIA Digital Twin Gatekeeper. ..."},
{"id": "gatekeeper-verify_infrastructure_checklist", "name": "verify_infrastructure_checklist", "description": "Runs the final homologation checklist ..."}
]
}
nameوdescriptionمأخوذان مباشرةً من تعريفAgent(...).- يسرد
skillsما يمكن للوكيل فعله. أضافت حزمة ADK السمةverify_infrastructure_checklistتلقائيًا، باستخدام سلسلة المستندات الخاصة بالأداة. - يُعلم
supportedInterfacesالمتصلين بمكان إرسال طلبات A2A. لهذا السبب، بدأت الخادم باستخدامAPP_URL=http://localhost:8001: يقرأ المتصل البطاقة أولاً، ثم يرسل طلباته إلى أيurlتعلن عنه البطاقة.
لم تتم كتابة أي شيء هنا يدويًا: ينشئ الخادم المزوّد بالبنية الأساسية البطاقة من وكيلك. سيقرأ مخطِّط المسار هذه البطاقة للعثور على "حارس البوابة" والاتصال به.
المقيِّم (MEDIUM) والمهندس المعماري الرئيسي (HIGH)
يتضمّن مخطِّط المسار وكيلَين:
- يقيّم المقيِّم عدة قواعد، لذا يحصل على
MEDIUM. ويتم تضمينه فيAgentTool، لذا يستدعيه كبير المهندسين المعماريين كدالة ويحصل على النتيجة. - يخطط المهندس المعماري الرئيسي ويصلح وينسق، لذلك يحصل على
HIGH. ويصل إلى Gatekeeper من خلالRemoteA2aAgent، الذي أنشأهcreate_remote_gatekeeper_agent()فيapp/auth.py، ويغلّفه أيضًا فيAgentTool.
لماذا ندمج كلتا الدالتَين المساعدتَين في أدوات؟ يُرسل AgentTool ردّه إلى المتصل، وبالتالي يبقى "كبير المهندسين المعماريين" مسؤولاً عن كتابة المخطط النهائي. إذا كان "حارس البوابة" sub_agent بدلاً من ذلك، سيسلّم "كبير المهندسين المعماريين" المحادثة إليه، وستصبح الحالة القصيرة لـ "حارس البوابة" هي الإجابة النهائية.
افتح ملف app/agent.py الخاص بأداة تخطيط المسارات:
cloudshell edit ~/track-planner/app/agent.py
انسخ الرمز التالي واستبدِل المحتوى الكامل لملف ~/track-planner/app/agent.py به:
"""Formula E track planner: Lead Architect, FIA Assessor and remote Gatekeeper.
- The Lead Architect (root agent) designs the circuit and stays in charge.
- The FIA Assessor checks the layout and is called as a tool (`AgentTool`).
- The Gatekeeper runs in a separate project. It is also called as a tool, over
A2A, so its verdict comes back to the Lead Architect.
"""
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.adk.tools.agent_tool import AgentTool
from google.genai import types
from app.auth import create_remote_gatekeeper_agent
from app.tools import build_fia_skill_toolset
from app.tools import evaluate_track_layout
from app.tools import get_track_topology
# Tested with Gemini 3.8 Flash. To try Gemini 4 Argon, change this to
# "gemini-4-argon", delete the `temperature` settings below (Argon ignores
# them) and run `uv add "google-genai>=2.30.1"` in this project first.
MODEL = "gemini-3.8-flash"
fia_skill_toolset = build_fia_skill_toolset()
# 1. FIA Assessor: MEDIUM thinking to weigh several rules without much latency.
assessor_agent = Agent(
name="fia_assessor",
model=Gemini(
model=MODEL,
retry_options=types.HttpRetryOptions(attempts=3),
),
description=(
"FIA safety and energy assessor. Audits a proposed circuit against "
"the geometry, regeneration and CAD layer rules."
),
instruction=(
"You are the FIA Assessor. Load the `fia-compliance-skill` and follow "
"it. Estimate regeneration for each braking zone with "
"`calculate_regen_zones.py`, then call `evaluate_track_layout` with "
"the highest value. Reply with the verdict, the score and every "
"remediation note."
),
generate_content_config=types.GenerateContentConfig(
temperature=0.1,
thinking_config=types.ThinkingConfig(
thinking_level=types.ThinkingLevel.MEDIUM,
),
),
tools=[fia_skill_toolset, evaluate_track_layout],
)
# 2. Remote Gatekeeper, reached over A2A (see app/auth.py).
remote_gatekeeper = create_remote_gatekeeper_agent()
# 3. Lead Architect: HIGH thinking for multi-step planning and trade-offs.
root_agent = Agent(
# Must match `root_agent_name` in agents-cli-manifest.yaml.
name="track_planner",
model=Gemini(
model=MODEL,
retry_options=types.HttpRetryOptions(attempts=3),
),
description=(
"Lead Formula E circuit architect. Designs FIA-compliant street "
"circuits and gets them homologated."
),
instruction=(
"You are the Lead Formula E Circuit Architect. For every request:\n"
"1. Call `get_track_topology` for the venue.\n"
"2. Call the `fia_assessor` tool with the full topology.\n"
"3. If the Assessor rejects the layout, propose concrete fixes (for "
"example widen a sector to 10.0m or add missing CAD layers) and "
"re-assess the fixed layout.\n"
"4. Once the Assessor passes it, call the `remote_gatekeeper` tool "
"with the circuit ID, CAD layers, minimum width and peak "
"regeneration for final approval.\n"
"5. Finish with a short blueprint: circuit ID, length, minimum width, "
"peak regeneration, every CAD layer by name, and the Gatekeeper's "
"status."
),
generate_content_config=types.GenerateContentConfig(
temperature=0.2,
thinking_config=types.ThinkingConfig(
thinking_level=types.ThinkingLevel.HIGH,
),
),
# Both helpers are tools, so their answers come back to the Lead Architect
# and it writes the final blueprint.
tools=[
get_track_topology,
AgentTool(agent=assessor_agent),
AgentTool(agent=remote_gatekeeper),
],
)
app = App(
root_agent=root_agent,
name="app",
)
تشغيل النظام بأكمله في Playground
تأكَّد من أنّ Gatekeeper لا يزال قيد التشغيل في علامة التبويب الثانية. في علامة التبويب الأولى، ابدأ تشغيل "مساحة تجربة مخطط المسار" (track planner's playground):
cd ~/track-planner
agents-cli playground --port 8080
انقر على معاينة الويب > معاينة على المنفذ 8080، كما فعلت في الخطوة 3.
اطلب حلبة في مكان يستوفي القواعد:
Design and homologate a Formula E circuit at Tokyo Bay.
راقِب لوحة الأحداث أثناء عمل الوكلاء. من المفترض أن تظهر لك بالترتيب التالي:
get_track_topology: يحمّل كبير المهندسين المعماريين بيانات خليج طوكيو.fia_assessor: يسلّم كبير المهندسين المعماريين التخطيط إلى "المقيِّم"، الذي يستدعيload_skillوload_skill_resourceوrun_skill_script(مرة واحدة لكل منطقة كبح)، ثمevaluate_track_layout.-
remote_gatekeeper: يتصل "المهندس الرئيسي" بـ "حارس البوابة" عبر A2A. سيظهر الطلب مسجَّلاً في علامة التبويب الثانية. - مخطط نهائي من كبير المهندسين المعماريين، يسرد كل طبقة CAD وحالة الموافقة من حارس البوابة.
انقر على أي حدث للاطّلاع على مدخلاته ومخرجاته الدقيقة.
ابدأ الآن جلسة جديدة وجرِّب مكانًا يخالف القواعد:
Can the Monaco Harbour layout be homologated? If not, fix it and try again.
هذه المرة يرفض المُقيِّم المنعطف الذي يبلغ طوله 6.8 متر، ويقترح كبير المهندسين المعماريين منعطفًا أوسع، ويعود التخطيط الثابت إلى المُقيِّم قبل الوصول إلى حارس البوابة.
عند الانتهاء، اضغط على Ctrl+C في علامة التبويب الأولى لإيقاف بيئة الاختبار. اترك Gatekeeper قيد التشغيل في علامة التبويب الثانية: ستحتاج إليه في الخطوة التالية.
6. 6. تقييم الوكلاء
يُشغِّل agents-cli eval run وكيلك على مجموعة بيانات، ويسجّل كل جولة واستدعاء أداة، ويقيّم النتائج. يمكنك تحديد ما تريد قياسه في tests/eval/eval_config.yaml.
انظر إلى مجموعة البيانات
افتح مجموعة البيانات في "محرِّر Cloud Shell":
cd ~/track-planner
cloudshell edit tests/eval/datasets/track_eval.json
يحتوي الملف على قائمة بـ eval_cases. تتضمّن كل حالة eval_case_id وprompt (سؤال المستخدم) وreference (الإجابة الجيدة). يقارن قاضي النموذج اللغوي الكبير إجابة الوكيل بالمرجع.
| ما يتم اختباره |
| مكان يجتاز كل قاعدة ويتمّ الموافقة عليه |
| لا يتوافق المنعطف المزدوج الذي يبلغ طوله 6.8 متر مع قاعدة العرض |
| لا تستوفي حلبة السباق التي يبلغ طولها 4,350 مترًا قاعدة الطول |
| تخطيط يفتقد إلى طبقات CAD الإلزامية |
| منطقة كبح أقل من الهدف البالغ 250 كيلوواط |
| الوصول إلى المستشفى يحتاج إلى طبقات CAD الطبية |
| منطقة "وضع الهجوم" على خط السباق |
| محادثة متعددة الجولات: يتم رفض موناكو، ويطلب المستخدم إصلاح المشكلة، ويجب الموافقة على التنسيق الذي تم إصلاحه |
تستخدم الحالة الأخيرة agent_data بدلاً من prompt. فهي تعيد تشغيل الجولات السابقة من المحادثة، ما يتيح لك اختبار كيفية تعامل الوكيل مع طلب متابعة، وليس مجرد سؤال واحد.
يحتوي الملف track_eval_quick.json في المجلد نفسه على حالتين فقط: الحالة 1 (سؤال واحد) والحالة 8 (محادثة). ستشغّل هذا الاستعلام لأنّه أسرع ويستخدم حصة أقل.
كتابة المقاييس
تحدّد مجموعة البيانات الأسئلة التي يجب طرحها على الوكيل. eval_config.yaml يوضّح كيفية تقييم الإجابات. يقرأ agents-cli eval run هذه الإجابات بعد أن يجيب موظف الدعم عن كل حالة، ويطبّق كل مقياس على كل إجابة.
افتح الملف الذي أنشأه السقالة:
cloudshell edit tests/eval/eval_config.yaml
يحتوي هذا المقياس على قاضٍ عام للنماذج اللغوية الكبيرة (custom_response_quality) ومقياس agent_turn_count يحتسب الجولات فقط. هذه بداية جيدة لأي وكيل، ولكنّها لا تذكر أي شيء عن "فورمولا إي". ستحتفظ بالمقيّم وتضيف مقياسًا يتحقّق من قاعدة خاصة بهذا النطاق.
تجمع التقييمات الجيدة عادةً بين نوعين من المقاييس:
النوع | كيفية احتساب النقاط | مناسب لما يلي: | المفاضلة |
LLM-as-a-judge | يقرأ أحد النماذج الإجابة و | السمات غير الواضحة: هل الإجابة صحيحة وكاملة وواضحة؟ | يتم احتساب تكلفة طلب النموذج لكل حالة، وقد تختلف النتائج قليلاً بين عمليات التشغيل |
مقياس الرمز | تتحقّق دالة Python صغيرة من الإجابة | حقائق دقيقة يمكن التحقّق منها: هل تضمّنت الإجابة معلومات يجب أن تكون موجودة؟ | يتحقّق فقط مما يمكنك التعبير عنه في الرمز |
استبدِل محتوى الملف بما يلي:
metrics_to_run:
- custom_response_quality
- fia_cad_layer_compliance
custom_metrics:
# LLM-as-a-judge. response_quality.py is generated by `agents-cli scaffold
# create`; it grades the final answer against the case's `reference`.
- name: custom_response_quality
custom_function_file: response_quality.py
# Deterministic code metric: an approved blueprint must name every
# mandatory FIA CAD layer.
- name: fia_cad_layer_compliance
custom_function: |
def evaluate(instance):
response = str(instance.get("response") or "")
reference = str(instance.get("reference") or "")
# Only approvals must list every layer. Rejections and other
# questions (such as Attack Mode) don't, so skip them.
if "APPROVED" not in reference:
return {"score": 1.0, "explanation": "Not an approval case."}
required = [
"F1_TRACK_CENTRELINE",
"F1_PIT_ENTRY_SPEED_LIMIT_LANE",
"F1_WALL_TEMP",
"F1_TEC3",
]
missing = [layer for layer in required if layer not in response]
return {
"score": round(1 - len(missing) / len(required), 2),
"explanation": "Missing: " + (", ".join(missing) or "none"),
}
وظيفة كل جزء:
metrics_to_runيسرد المقاييس المطلوب تنفيذها، حسب الاسم. تؤدي إزالة اسم هنا إلى إيقاف هذا المقياس بدون حذفه.custom_response_qualityهو قاضي النموذج اللغوي الكبير. يشيرcustom_function_fileإلىtests/eval/response_quality.py، الذي أنشأه السقالة. افتحه إذا كنت تريد الاطّلاع على طلب التحكيم.fia_cad_layer_complianceهو مقياس الرمز البرمجي، ويتم كتابته مضمّنًا ضمنcustom_function. في كل حالة، يتلقّىinstance(الطلب، وresponseالنهائي للوكيل، وreference). في الحالات التي تكون فيها الإجابة المتوقّعة هي الموافقة، يتحقّق من أنّ الردّ يتضمّن أسماء طبقات CAD الأربع الإلزامية ويسرد أي طبقات غير متوفّرة. على سبيل المثال، يحصل المخطط الذي يستبعدF1_TEC3على درجة 0.75. أما الحالات الأخرى، فتحصل على درجة 1.0، لأنّ الرفض أو الإجابة في "وضع الهجوم" لا يتطلبان إدراج كل طبقة.
لماذا يجب التحقّق من طبقات CAD؟ فالمخطط المعتمد الذي يغفل طبقة إلزامية يكون خاطئًا حتى لو كان يبدو جيدًا، وقد يتغاضى قاضي النموذج اللغوي الكبير عن ذلك. يطبّق فحص الرموز القاعدة نفسها بالطريقة نفسها في كل عملية فحص.
إجراء التقييم
أبقِ Gatekeeper المحلي قيد التشغيل في علامة التبويب الثانية، ثم شغِّل:
agents-cli eval run \
--dataset tests/eval/datasets/track_eval_quick.json \
--config tests/eval/eval_config.yaml \
--concurrency 1
ls artifacts/grade_results/
يستغرق التقييم بضع دقائق. تنفّذ كل حالة سير عمل متعدّد الوكلاء بالكامل، أي حوالي عشر طلبات من النموذج مع Lead Architect على HIGH، لذا فإنّ Step 1/2: eval generate هو الجزء البطيء. لم يعلق.
عند الانتهاء، افتح تقرير HTML في artifacts/grade_results/ باستخدام "محرِّر Cloud Shell". تشير نتائج fia_cad_layer_compliance المنخفضة إلى أنّ الإجابة النهائية لمهندس الحلول الرئيسي لا تتضمّن بعض الطبقات. حاوِل تضييق نطاق التعليمات وإجراء التقييم مرة أخرى.
7. 7. نشر Gatekeeper في بيئة تشغيل الوكيل
يمكنك نشر Gatekeeper فقط. يستمر تشغيل مخطط المسار في Cloud Shell ويستدعيه.
فتح علامة تبويب جديدة في Cloud Shell
يستغرق النشر من 5 إلى 8 دقائق، لذا يمكنك إجراؤه في علامة تبويب جديدة أثناء انتهاء التقييم من الخطوة 6:
- انقر على فتح علامة تبويب جديدة (+) في شريط أدوات Cloud Shell.
- لا تحتفظ علامة التبويب الجديدة بالمتغيّرات من الخطوة 2، لذا عليك ضبطها مرة أخرى:
export GOOGLE_CLOUD_PROJECT="$(gcloud config get-value project)" export REGION="us-central1" export ASSETS="$HOME/devrel-demos/codelabs/formula-e-track-planner" export PATH="$HOME/.local/bin:$PATH" echo "Project: $GOOGLE_CLOUD_PROJECT Region: $REGION"
اترك Gatekeeper المحلي قيد التشغيل في علامة التبويب الثانية: لا يزال التقييم يستخدمه، ولا يحتاج النشر إلى إيقافه.
نشر
في علامة التبويب الجديدة، انشر Gatekeeper. ويتم تشغيله كحساب خدمة Compute Engine التلقائي للمشروع:
cd ~/gatekeeper
PROJECT_NUMBER=$(gcloud projects describe "$GOOGLE_CLOUD_PROJECT" --format="value(projectNumber)")
agents-cli deploy \
--no-agent-identity \
--service-account "${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
--project "$GOOGLE_CLOUD_PROJECT" \
--region "$REGION" \
--no-confirm-project
تستغرق عملية النشر من 5 إلى 8 دقائق تقريبًا. لا تغلق علامة تبويب Cloud Shell أثناء تشغيلها. إذا انقطع اتصال بث السجلّ، يمكنك التحقّق من مستوى التقدّم باستخدام agents-cli deploy --status. أثناء الانتظار، ارجع إلى الخطوة 6 واقرأ تقرير التقييم الخاص بك.
فحص هوية الوكيل
يسجّل "agents-cli" المورد المنشور في "deployment_metadata.json":
export RUNTIME_ID=$(jq -r .remote_agent_runtime_id ~/gatekeeper/deployment_metadata.json)
echo "$RUNTIME_ID"
curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://${REGION}-aiplatform.googleapis.com/v1beta1/${RUNTIME_ID}" \
| jq -r .spec.effectiveIdentity
السطر الثاني من الناتج هو الهوية التي يعمل بها Gatekeeper:
تم النشر باستخدام | مثال على الناتج |
حساب الخدمة (تلقائي) |
|
هوية الوكيل |
|
تتم مشاركة حساب الخدمة من خلال كل ما يستخدمه في المشروع. تنتمي "هوية الوكيل" إلى هذا الوكيل الواحد، لذا يمكنك منحه الأدوار التي يحتاجها بالضبط والاطّلاع على إجراءاته بشكل منفصل في سجلّات التدقيق.
8. 8. الاتصال بخادم Gatekeeper المنشور عبر A2A
يوفّر Agent Runtime مسارات A2A التي أنشأها Gatekeeper خلف مسار /api تمت مصادقته.
تأكَّد من انتهاء التقييم من الخطوة 6، ثم أوقِف Gatekeeper المحلي في علامة التبويب الثانية (Ctrl+C). من الآن فصاعدًا، يستدعي مخطط المسار المخطط المنشور. في علامة التبويب الأولى، وجِّه مخطِّط المسار إليها:
export RUNTIME_ID=$(jq -r .remote_agent_runtime_id ~/gatekeeper/deployment_metadata.json)
: "${RUNTIME_ID:?No deployed Gatekeeper found. Complete Step 7 first.}"
cd ~/track-planner
echo "GATEKEEPER_A2A_URL=https://${REGION}-aiplatform.googleapis.com/reasoningEngines/v1/${RUNTIME_ID}/api/a2a/app" >> .env
سبب إعادة تحميل العميل للرمز المميّز
فتح "app/auth.py" تنتهي صلاحية رموز الدخول إلى Google Cloud بعد ساعة واحدة، لذا فإنّ العميل الذي يضبط عنوان Authorization ثابتًا عند بدء التشغيل يبدأ في تعذُّر تنفيذ الطلب مع ظهور الخطأ 401 Unauthorized بعد ساعة. GoogleAuthRefresh subclasses httpx.Auth and checks the credentials on every request, refreshing them when needed. يُرفق create_remote_gatekeeper_agent() هذه السمة بعناوين URL التي تتضمّن https:// فقط.
تنفيذها من البداية إلى النهاية
ابدأ تشغيل Playground مرة أخرى حتى يتمكّن من التقاط GATEKEEPER_A2A_URL الجديد:
agents-cli playground --port 8080
انقر على معاينة الويب > معاينة على المنفذ 8080، وابدأ جلسة جديدة، واطرح السؤال التالي:
Assess the Monaco Harbour layout, widen the chicane to 11m, and get Gatekeeper approval.
تظهر الأحداث كما في الخطوة 5، ولكن يتم الآن توجيه طلب remote_gatekeeper إلى Gatekeeper في Agent Runtime بدلاً من علامة التبويب الثانية.
الاطّلاع على المكالمة الواردة في Agent Runtime
إثبات أنّ الطلب وصل فعلاً إلى Gatekeeper المنشور عبر A2A:
- في وحدة تحكّم Cloud، ابحث عن Agent Platform، ثم افتح عمليات النشر في القائمة اليمنى.
- اختَر gatekeeper.
- افتح علامة التبويب الجلسات.
ستظهر لك جلسة جديدة يبدأ رقم تعريف المستخدم فيها بـ A2A_USER_. تم إنشاؤه من قِبل خادم Gatekeeper's A2A عندما استدعاه مخطِّط المسار. افتح علامة التبويب عمليات التتبُّع في الصفحة نفسها للاطّلاع على طلب النموذج من Gatekeeper وطلب الأداة verify_infrastructure_checklist لهذا الطلب.
اختياري: نشر مخطِّط المسار أيضًا
حتى الآن، يتم تشغيل مخطِّط المسار في Cloud Shell، لذا فإنّ طلبات A2A إلى Gatekeeper تستخدم بيانات اعتمادك . انشر المخطِّط أيضًا، وسيتم تشغيل كلا الوكيلَين في بيئة تشغيل الوكيل، ويستدعي كل منهما الآخر باستخدام هوياتهما المنشورة.
اضغط على Ctrl+C لإيقاف Playground، ثم انشر Planner بالطريقة نفسها التي استخدمتها لنشر Gatekeeper:
cd ~/track-planner
PROJECT_NUMBER=$(gcloud projects describe "$GOOGLE_CLOUD_PROJECT" --format="value(projectNumber)")
agents-cli deploy \
--no-agent-identity \
--service-account "${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
--project "$GOOGLE_CLOUD_PROJECT" \
--region "$REGION" \
--no-confirm-project
يتم تشغيل كلا الوكيلَين كحساب خدمة Compute Engine نفسه. احتفِظ بـ --service-account: بدونه، يتم تشغيل المخطِّط كوكيل خدمة تلقائي لـ Agent Runtime ولا يمكنه استدعاء Gatekeeper (راجِع لماذا حساب الخدمة هذا؟ في الخطوة 7).
كيفية وصول المخطِّط المنشور إلى Gatekeeper:
- ينسخ
agents-cli deployالقيم في.envإلى عملية النشر، وبذلك يحصل المخطِّط علىGATEKEEPER_A2A_URLالتي أضفتها أعلاه. - في Agent Runtime، يستخدم
GoogleAuthRefreshفيapp/auth.pyالهوية المنشورة للمخطِّط بدلاً من هويتك.
تستغرق عملية النشر من 5 إلى 8 دقائق تقريبًا. عند الانتهاء، تحقَّق من الهوية التي يتم تشغيل المخطِّط بها:
export PLANNER_ID=$(jq -r .remote_agent_runtime_id deployment_metadata.json)
curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://${REGION}-aiplatform.googleapis.com/v1beta1/${PLANNER_ID}" \
| jq -r .spec.effectiveIdentity
لتجربة النظام المنشور:
- في Cloud Console، ارجع إلى Agent Platform > Deployments.
- اختَر track-planner وافتح علامة التبويب Playground.
- أدخل:
Design and homologate a Formula E circuit at Tokyo Bay. - انتظِر حتى تظهر حالة موافَق عليه في المخطّط من قِبل Gatekeeper.
- ارجع إلى عمليات النشر، واختَر gatekeeper وافتح علامة التبويب الجلسات. تم إنشاء أحدث جلسة
A2A_USER_من المخطِّط المنشور، وليس من Cloud Shell.
عند التنظيف في الخطوة التالية، احذف المخطط أيضًا:
curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://${REGION}-aiplatform.googleapis.com/v1beta1/${PLANNER_ID}?force=true"
9. 9. تحديد المشاكل وحلّها وإزالة البرامج الضارة
تحديد المشاكل وحلّها
المشكلة | تعديل الإجابات |
| يُرجى قبول بنود الخدمة في Cloud Console، ثم إعادة المحاولة. |
المشروع هو | أعِد تشغيل أوامر المشروع في الخطوة 2. |
| شغِّل |
| أكمِل الخطوة 4 أو انسخ |
من | ابدأ تشغيل Gatekeeper المحلي (الخطوة 5)، أو اضبط |
| لا يمكن لحسابك استخدام Agent Identity. اتّبِع مربّع التنظيف في الخطوة 7، ثم استخدِم عملية نشر حساب الخدمة. |
يُبلغ مخطط المسار المنشور عن | لا يُسمح لهوية المخطِّط بالاتصال بـ Gatekeeper. أعِد نشرها باستخدام |
| لقد بلغت حصة Gemini المخصّصة لك. انتظِر دقيقة أو أضِف " |
| يُرجى إيقاف الخادم الآخر أو اختيار |
تَنظيم
احذف Gatekeeper المنشور حتى لا يستمر في العمل:
export RUNTIME_ID=$(jq -r .remote_agent_runtime_id ~/gatekeeper/deployment_metadata.json)
: "${RUNTIME_ID:?No deployed Gatekeeper found.}"
curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://${REGION}-aiplatform.googleapis.com/v1beta1/${RUNTIME_ID}?force=true"
إذا أنشأت مشروعًا لهذا الدرس التطبيقي حول الترميز فقط، يمكنك حذف المشروع بأكمله بدلاً من ذلك. إذا كنت في فعالية، احتفِظ بالمشروع الذي تم منحه لك إلى أن يطلب منك المنظّمون خلاف ذلك.
ما تعلّمته
- يوفّر لك
agents-cli scaffold createمشروع ADK عاديًا وقابلاً للنشر، وما عليك سوى كتابة الوكلاء والمهارات والتقييمات. - تُبقي مهارات الوكيل المعرفة الخاصة بالنطاق بعيدة عن الطلبات إلى أن يحتاج إليها الوكيل.
- يتيح لك
thinking_levelتحديد مستوى عمق الاستدلال مقابل السرعة لكل وكيل. - يساعدك
agents-cli eval runفي تحويل سؤال "هل تعمل الحملة؟" إلى نتائج يمكنك تتبُّعها. - تتيح ميزتا "هوية الوكيل" و"التواصل بين الوكلاء" للوكلاء الذين تم نشرهم بشكل مستقل العمل معًا بأمان.