1. نظرة عامة
في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية استخدام Agents CLI لإدارة دورة التطوير المحلية الكاملة لوكيل بالذكاء الاصطناعي. سواء كنت تستخدم نماذج Gemini الحالية أو تنشئ وكلاء مخصّصين من البداية باستخدام حزمة تطوير الوكلاء (ADK 2.0)، يوفّر Agents CLI الأدوات اللازمة لإنشاء الوكلاء واختبارهم وتنسيقهم محليًا.
أهداف الدورة التعليمية
- كيفية تثبيت
agents-cliوإعداده ومهاراته المرتبطة - كيفية إنشاء مشروع وكيل جديد
- بنية ملفات مشروع وكيل سير عمل الرسم البياني في حزمة تطوير الوكلاء (ADK 2.0) وملفاته الرئيسية
- كيفية تشغيل عمليات التنسيق الآلية وعمليات تنظيف الرموز البرمجية
- كيفية تشغيل ساحة اللعب على الويب المحلية واستخدامها لإجراء اختبارات تفاعلية مع إعادة التحميل التلقائي
ما تحتاج إليه
- Python 3.11 أو إصدار أحدث
- uv
- Node.js 18 أو إصدار أحدث (في حال استخدام مهارات وكيل الترميز)
- Antigravity IDE (تثبيته وإعداده من Google Antigravity)
المتطلبات الأساسية
يفترض هذا الدرس التطبيقي حول الترميز أنّك على دراية بما يلي:
- استخدام وحدة طرفية وسطر أوامر
لا يلزم وجود خبرة سابقة في الوكلاء بالذكاء الاصطناعي أو حزمة تطوير الوكلاء (ADK 2.0).
2. إعداد المصادقة والبيئة
يُرجى تقديم بيانات اعتماد المصادقة للوكيل لاستدعاء نماذج Gemini.
الخيار 1: مفتاح Gemini API (Google AI Studio)
إذا كنت تستخدم مفتاح Gemini API عاديًا (يمكنك الحصول عليه من Google AI Studio)، يمكنك تصديره في جلسة الوحدة الطرفية في بيئة التطوير المتكاملة (IDE):
export GEMINI_API_KEY="your_api_key_here"
export GOOGLE_GENAI_USE_ENTERPRISE=FALSE
الخيار 2: بيانات الاعتماد التلقائية لتطبيق Google Cloud
إذا كنت تستخدم Vertex AI على Google Cloud، يمكنك المصادقة باستخدام بيانات الاعتماد التلقائية لتطبيق Google Cloud وتعيين مشروع على السحابة الإلكترونية النشط:
gcloud auth application-default login
gcloud config set project <YOUR_PROJECT_ID>
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=REPLACE-WITH-YOUR-PROJECT_ID # Replace with your project ID
export GOOGLE_CLOUD_LOCATION=REPLACE-WITH-LOCATION # Replace the location
3. إعداد Agents CLI والمهارات
الخطوة الأولى هي تثبيت أداة agents-cli. تتولى هذه الأداة إدارة مشاريع الوكلاء.
بعد تثبيت Antigravity، نفِّذ أمر الإعداد مباشرةً في الوحدة الطرفية.
👈 افتح وحدة طرفية ونفِّذ الأمر التالي:
uvx google-agents-cli setup
يؤدي هذا الأمر إلى تثبيت ما يلي تلقائيًا:
- أداة Agents CLI على مستوى العالم على جهازك
- سبع مهارات لمساعد الترميز خاصة بمجالات معيّنة يمكن أن يستخدمها Antigravity لمساعدتك في إنشاء الوكلاء وتنسيقهم وتقييمهم ونشرهم يتم تثبيت هذه المهارات مرة واحدة على مستوى العالم في
~/.agents/skills/ويكتشفها Antigravity تلقائيًا.
ملاحظة: يتم تثبيت المهارات في ~/.agents/skills/ ويختارها Antigravity تلقائيًا. يمكنك التحقّق من ذلك باستخدام الأمر /skills أو إعدادات Antigravity.
الناتج المتوقَّع (تم اقتطاعه):
█▀█ █▀▀ █▀▀ █▄ █ ▀█▀ █▀ █▀▀ █ █`
`█▀█ █▄█ ██▄ █ ▀█ █ ▄█ █▄▄ █▄ █`
`Your coding agent just got an upgrade.`
`1. Authentication`
`─────────────────`
`✓ Authenticated with Google Cloud`
`2. CLI Installation`
`───────────────────`
`▸ uv tool install google-agents-cli`
`✓ Installed google-agents-cli`
`3. Skills Installation`
`──────────────────────`
`▸ npx -y skills add https://github.com/google/agents-cli -y --all -g`
`◇ Found 7 skills`
`~/.agents/skills/google-agents-cli-adk-code`
`~/.agents/skills/google-agents-cli-deploy`
`~/.agents/skills/google-agents-cli-eval`
`~/.agents/skills/google-agents-cli-observability`
`~/.agents/skills/google-agents-cli-publish`
`~/.agents/skills/google-agents-cli-scaffold`
`~/.agents/skills/google-agents-cli-workflow`
4. إنشاء مشروع الوكيل
في هذا القسم، ستنشئ دليل مشروع منظّمًا بالكامل باستخدام نموذج النموذج الأوّلي.
👈 اطلب من Antigravity:
Use ADK 2.0 to create a new graph workflow agent project called
customer-support-agent. I don't want to deploy this agent, so you can skip
the deployment files. The workflow should act as a customer support
representative for a shipping company. It should first classify if the user
query is related to shipping (rates, tracking, delivery, returns) or
unrelated. If it is related to shipping, route to a shipping FAQ agent to
answer the question. If it is unrelated, route to a node that politely
declines to answer.
ينفِّذ Antigravity تلقائيًا أمر إنشاء النموذج (agents-cli scaffold create customer-support-agent --prototype --yes) ويضبط ملفات المشروع لك.
5. استكشاف رمز الوكيل
👈 اطلب من Antigravity شرح الرمز البرمجي الذي تم إنشاؤه:
Read and explain the project structure of my new agent project. Walk me
through how `app/agent.py` is configured, highlighting the role of the
tools, nodes, edges, and the root Workflow.
في Antigravity IDE، تظهر ملفات المشروع والعناصر التي تم إنشاؤها حديثًا مباشرةً في اللوحة الثانوية (الجانب الأيمن). يمكنك عرض app/agent.py هناك، أو فتحه من مستكشف ملفات بيئة التطوير المتكاملة (IDE) لاستكشاف الرمز البرمجي الذي تم إنشاؤه.
# app/agent.py
from __future__ import annotations
from typing import Any, Literal
from google.adk.agents.context import Context
from google.adk.apps.app import App
from google.adk.events.event import Event
from google.adk.workflow import Edge
from google.adk.workflow import Workflow
from google.adk.workflow.agents.llm_agent import LlmAgent
from google.adk.workflow.node import node
from pydantic import BaseModel
from pydantic import Field
class InquiryCategory(BaseModel):
category: Literal['shipping', 'unrelated'] = Field(
description=(
'Determine if the user query is related to shipping (rates, tracking,'
' delivery times, returns) or unrelated.'
)
)
def save_query(node_input: str):
"""Saves user query in state for downstream nodes."""
yield Event(data=node_input, state={'user_query': node_input})
categorize_agent = LlmAgent(
name='categorize',
model='gemini-3.1-flash-lite',
instruction='You are an expert classifier. Categorize the user query.',
output_key='inquiry_category',
output_schema=InquiryCategory,
)
@node
def route_inquiry(ctx: Context, node_input: Any):
"""Routes the workflow based on the classified category."""
category_data = ctx.state.get('inquiry_category', {})
category = category_data.get('category', 'unrelated')
query = ctx.state.get('user_query', '')
yield Event(data=query, route=category)
faq_agent = LlmAgent(
name='shipping_faq',
model='gemini-3.1-flash-lite'',
instruction="""You are a customer support representative for a shipping company. Answer user questions based ONLY on the shipping FAQ below. Do not answer questions outside of the FAQ.
SHIPPING FAQ:
- Rates: Standard shipping is $5.99. Express shipping is $12.99. Orders
over $50 qualify for free standard shipping.
- Tracking: You can track your order by entering your tracking number on
our website's tracking page.
- Delivery Times: Standard delivery takes 3-5 business days. Express
delivery takes 1-2 business days.
- Returns: We offer free returns within 30 days of delivery. Please make
sure the item is in its original condition.
""",
)
@node
def handle_unrelated(ctx: Context, node_input: Any):
"""Handles unrelated inquiries politely."""
yield Event(
data=(
'I am sorry, I am a shipping customer support assistant and can only'
' answer questions related to our shipping FAQ.'
)
)
root_agent = Workflow(
name='customer_support_workflow',
edges=[
*Edge.chain('START', save_query, categorize_agent, route_inquiry),
(route_inquiry, faq_agent, 'shipping'),
(route_inquiry, handle_unrelated, 'unrelated'),
],
)
app = App(
name='customer_support_agent',
root_agent=root_agent,
)
المفاهيم الرئيسية
- سير العمل والحواف: في حزمة تطوير الوكلاء (ADK 2.0)، يتم تنسيق تطبيقات الوكلاء على شكل رسم بياني باستخدام
Workflow. تحدّد قائمةedgesمسار التنفيذ، حيث تربط العُقد معًا منSTARTوتتيح التفرّع المشروط استنادًا إلى المسارات (على سبيل المثال، التوجيه إلىfaq_agentفي"shipping"أوhandle_unrelatedفي"unrelated"). - LlmAgent: عُقد إعلانية تحدّد المهام المستندة إلى النماذج اللغوية الكبيرة (LLM) مع تعليمات ونماذج ومخرجات منظّمة (
output_schema) محدّدة - العُقد والسياق: دوال Python مزيّنة بـ
@node(أو دوال عادية) تنفِّذ منطقًا وتصل إلى حالة التنفيذ من خلالContextوتنتج كائناتEventلتمرير البيانات وإشارات التوجيه على طول الرسم البياني - النموذج: يتم استخدام `gemini-3.1-flash-lite' كنموذج استدلال سريع تلقائيًا.
- غلاف التطبيق: يغلّف الكائن
Appعالي المستوى سير العمل الأساسي. تكتشف الأدوات الخارجية، مثل ساحة اللعب المحلية وأدوات تقييم حزمة تطوير الوكلاء (ADK) وAgent Runtime، سير عملك وتنفِّذه من خلال واجهةappالموحّدة هذه.
6. التنسيق الآلي
قبل تشغيل الوكيل أو اختباره، من المستحسن التأكّد من أنّ الرمز البرمجي نظيف ومنسّق بشكل صحيح.
👉 اطلب من Antigravity:
Run linting on my agent project to verify its health.
سينفِّذ Antigravity الأمر agents-cli lint في الخلفية لتشغيل عمليات التحقّق التي تم ضبطها مسبقًا، ما يؤدي إلى التحقّق من عمليات الاستيراد وبنية الجملة وتنسيقها بشكل متّسق في جميع ملفاتك.
7. الاختبار التفاعلي باستخدام ساحة اللعب
تُعد ساحة اللعب على الويب المحلية أسرع طريقة للتحقّق من سلوك الوكيل. توفّر واجهة محادثة تفاعلية يمكنك من خلالها التحدّث مع وكيلك وفحص عمليات تنفيذ الأدوات في الوقت الفعلي.
👉 اطلب من Antigravity:
Launch the local development playground for my agent.
سيشغّل Antigravity خادم التطوير المحلي (agents-cli playground). افتح عنوان URL المقدَّم (عادةً http://127.0.0.1:8080/dev-ui/?app=app) في متصفّح الويب، واختَر المجلد app من القائمة المنسدلة لبدء التحدّث مع وكيلك.
ابدأ التحدّث مع وكيلك في واجهة الويب. جرِّب طرح سؤال متعلق بالشحن:
How much is standard shipping?
لاحظ كيف يصنّف سير العمل السؤال ويوجّهه بنجاح إلى faq_agent للإجابة عنه. جرِّب أيضًا طرح سؤال غير ذي صلة للتحقّق من أنّ سير العمل يوجّه السؤال إلى handle_unrelated ويرفض الإجابة عنه بشكل صحيح:
What is the weather like?
اختبار إعادة التحميل التلقائي في الوقت الفعلي
يمكنك الاطّلاع على كيفية ظهور التعديلات التي يتم إجراؤها على وكيلك في الوقت الفعلي في ساحة اللعب.
- عدِّل تعليمات
faq_agentفيapp/agent.pyمن خلال مطالبة Antigravity بما يلي:Modify the faq_agent instruction in app/agent.py to make the shipping rates response more playful and enthusiastic. Add some emojis and highlight the free shipping threshold. - أرسِل رسالة جديدة إلى الوكيل في ساحة اللعب لاختبار إعادة التحميل التلقائي:
How much is standard shipping?
8. التنفيذ من سطر الأوامر
لإجراء اختبارات سريعة أو عمليات أتمتة أو كتابة نصوص برمجية، يمكنك أن تطلب من Antigravity تشغيل وكيلك مباشرةً من الوحدة الطرفية.
👉 اطلب من Antigravity:
Run a CLI query asking my agent how long standard delivery takes.
سينفِّذ Antigravity أمر الاستعلام (agents-cli run "How long does standard delivery take?"). يؤدي ذلك إلى تشغيل استنتاج سريع لمرة واحدة وطباعة الرد النهائي للوكيل بالإضافة إلى تفاصيل تنفيذ الأداة.
9. تنظيف
لتجنُّب ترك موارد غير مرغوب فيها في بيئتك المحلية، اتّبِع خطوات التنظيف التالية:
- إيقاف الخوادم المحلية: إذا كان خادم
agents-cli playgroundلا يزال قيد التشغيل، أوقِفه في الوحدة الطرفية بالضغط علىCtrl + C. - إزالة ملفات المشروع المحلية: احذف دليل مشروع الوكيل الذي تم إنشاؤه من جهازك المحلي.
rm -rf customer-support-agent
10. الملخّص والخطوات التالية
تهانينا! لقد تمكّنت بنجاح من إدارة دورة التطوير المحلية الكاملة لوكيل بالذكاء الاصطناعي باستخدام Agents CLI وحزمة تطوير الوكلاء (ADK 2.0).
ما تعلّمته
- إعداد الأدوات: تم تثبيت Agents CLI وضبط مهارات سير العمل الخاصة بمجالات معيّنة لـ Antigravity.
- إنشاء مشروع: تم إنشاء مشروع
customer-support-agentمنظّم بالكامل باستخدام قوالب موحّدة. - تحليل بنية حزمة تطوير الوكلاء (ADK 2.0): تم استكشاف عمليات سير عمل الرسم البياني والوكلاء بالنماذج اللغوية الكبيرة (LLM) والعُقد والحواف والتوجيه المشروط.
- إدارة الحالة المحلية: تم تشغيل عمليات التحقّق الآلية من جودة الرمز البرمجي باستخدام
agents-cli lint. - التحقّق من السلوك: تم اختبار الوكيل بشكل تفاعلي مع إعادة التحميل التلقائي في الوقت الفعلي من خلال ساحة اللعب، وتم إجراء اختبارات سريعة على سطر الأوامر.
الخطوات التالية:
بعد إتقان حلقة التطوير المحلية، إليك كيفية توسيع نطاق وكيلك وتحويله إلى منتج:
- التقييم: يمكنك تسجيل نقاط وكيلك مقابل مجموعة التقييم باستخدام
agents-cli eval runلقياس الدقة والعثور على حالات التراجع. - النشر و & إمكانية المراقبة على نطاق المؤسسة في السحابة الإلكترونية: يمكنك تجميع وكيلك ونشره في بيئات الإنتاج، مثل Agent Runtime أو Cloud Run باستخدام
agents-cli deploy. يمكنك إعداد بيانات القياس عن بُعد للإنتاج من أجل بث السجلات وعمليات تتبُّع التنفيذ إلى Cloud Trace وBigQuery.