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

وكلاء الذكاء الاصطناعي في Vibe Coding: إدارة مراحل الوكيل باستخدام Agents CLI وADK 2.0

1. نظرة عامة

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية استخدام Agents CLI لإدارة دورة حياة التطوير المحلية الكاملة لأحد وكلاء الذكاء الاصطناعي. سواء كنت تستخدم نماذج Gemini الحالية أو تنشئ وكلاء مخصّصين من البداية باستخدام مجموعة أدوات تطوير الوكلاء (الإصدار 2.0)، يوفّر لك Agents CLI الأدوات اللازمة لإنشاء الوكلاء وتصميمهم وتدقيقهم واختبارهم على جهازك.

أهداف الدورة التعليمية

كيفية تثبيت agents-cli وإعدادها ومهاراتها المرتبطة بها
كيفية إنشاء بنية أساسية لمشروع وكيل جديد
بنية وملفات أساسية لمشروع وكيل سير عمل بياني في ADK 2.0
كيفية تنفيذ عمليات تنظيف الرموز البرمجية وعمليات التدقيق الآلية
كيفية تشغيل واستخدام ساحة لعب الويب المحلية لإجراء اختبارات تفاعلية مع إعادة التحميل تلقائيًا

ما تحتاج إليه

الإصدار 3.11 أو الإصدارات الأحدث من Python
uv package manager
Node.js 18+ (في حال استخدام مهارات وكيل الترميز)
‫Antigravity IDE (يمكنك تثبيته وضبطه من Google Antigravity)

المتطلبات الأساسية

يفترض هذا الدرس التطبيقي حول الترميز أنّك على دراية بما يلي:

استخدام نافذة Terminal وسطر الأوامر

لا يلزم توفّر خبرة سابقة في وكلاء الذكاء الاصطناعي أو الإصدار 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، عليك المصادقة باستخدام "بيانات الاعتماد التلقائية للتطبيق" (ADC) من 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. تتولّى هذه الأداة المهام الصعبة المتعلقة بإدارة مشاريع العملاء.

بعد تثبيت Antigravity، نفِّذ أمر الإعداد مباشرةً في الوحدة الطرفية.

👉 افتح وحدة طرفية ونفِّذ ما يلي:

uvx google-agents-cli setup

يؤدي هذا الأمر إلى تثبيت ما يلي تلقائيًا:

أداة واجهة سطر الأوامر للوكلاء على مستوى العالم على نظامك
سبع مهارات خاصة بمساعد الترميز في مجالات معيّنة يمكن أن تستخدمها 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 المتكاملة، يتم عرض ملفات المشروع والعناصر التي تم إنشاؤها حديثًا مباشرةً في اللوحة المساعدة (الجانب الأيسر). يمكنك عرض app/agent.py هناك، أو فتحه من مستكشف الملفات في بيئة التطوير المتكاملة لاستكشاف الرمز البرمجي الذي تم إنشاؤه.

# 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,
)

المفاهيم الرئيسية

سير العمل والحواف: في الإصدار 2.0 من "حزمة تطوير التطبيقات"، يتم تنظيم تطبيقات الوكيل كرسومات بيانية باستخدام Workflow. تحدّد قائمة edges مسار التنفيذ، حيث تربط العُقد ببعضها البعض من START وتتيح إنشاء فروع شرطية استنادًا إلى المسارات (مثل التوجيه إلى faq_agent على "shipping" أو handle_unrelated على "unrelated").
LlmAgent: عُقد تعريفية تحدّد المهام المستندة إلى النماذج اللغوية الكبيرة مع تعليمات ونماذج ومخرجات منظَّمة محدّدة (output_schema).
العُقد والسياق: دوال Python مزيّنة بـ @node (أو دوال عادية) تنفّذ منطقًا وتصل إلى حالة التنفيذ من خلال Context وتنتج عناصر Event لتمرير البيانات وإشارات التوجيه على طول الرسم البياني.
النموذج: يتم استخدام `gemini-3.1-flash-lite' كنموذج الاستدلال السريع تلقائيًا.
App Wrapper: يغلّف العنصر App ذو المستوى الأعلى سير العمل الأساسي. تستكشف الأدوات الخارجية، مثل ساحة اللعب المحلية وأدوات تقييم حِزم تطوير التطبيقات وAgent Runtime، سير عملك وتنفّذه من خلال هذه الواجهة app الموحّدة.

6. Automated Linting

قبل تشغيل الوكيل أو اختباره، من الممارسات الجيدة التأكّد من أنّ الرمز البرمجي نظيف ومنسّق بشكل صحيح.

👉 طلب Antigravity:

Run linting on my agent project to verify its health.

ستنفّذ Antigravity agents-cli lint في الخلفية لتشغيل عمليات التحقّق التي تم ضبطها مسبقًا، والتحقّق من عمليات الاستيراد والبنية وتناسق التنسيق في جميع ملفاتك.

7. الاختبار التفاعلي باستخدام Playground

تُعدّ ساحة لعب الويب المحلية أسرع طريقة للتحقّق من سلوك الوكيل. توفّر هذه الواجهة محادثة تفاعلية يمكنك من خلالها التحدّث مع وكيلك والاطّلاع على عمليات تنفيذ الأدوات في الوقت الفعلي.

👉 طلب 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: استكشاف سير عمل الرسومات، وعملاء نماذج اللغات الكبيرة، والعُقد، والحواف، والتوجيه الشرطي
Managed Local Health: تم إجراء عمليات تحقّق مبرمَجة من جودة الرمز البرمجي باستخدام agents-cli lint.
السلوك الذي تم التحقّق منه: تم اختبار الوكيل بشكل تفاعلي مع إعادة التحميل السريع في الوقت الفعلي من خلال ساحة اللعب، وتم إجراء اختبارات سريعة على سطر الأوامر.

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

بعد إتقان حلقة التطوير المحلية، إليك كيفية توسيع نطاق "العميل" وتحويله إلى منتج:

التقييم: يمكنك تقييم أداء الوكيل باستخدام مجموعة التقييم agents-cli eval run لقياس الدقة ورصد أي تراجع في الأداء.
نشر الوكيل ومراقبة أدائه على مستوى المؤسسة: يمكنك إنشاء حزمة ونشر الوكيل في بيئات الإنتاج، مثل Agent Runtime أو Cloud Run، باستخدام agents-cli deploy. إعداد بيانات القياس عن بُعد للإنتاج من أجل بث السجلّات وعمليات التنفيذ إلى Cloud Trace وBigQuery

وكلاء الذكاء الاصطناعي في Vibe Coding: إدارة مراحل الوكيل باستخدام Agents CLI وADK 2.0

1. نظرة عامة

أهداف الدورة التعليمية

ما تحتاج إليه

المتطلبات الأساسية

2. إعداد المصادقة والبيئة

الخيار 1: مفتاح Gemini API (Google AI Studio)

الخيار 2: بيانات الاعتماد التلقائية للتطبيق في Google Cloud

3- إعداد واجهة سطر الأوامر الخاصة بـ "الوكلاء" و"المهارات"

4. إنشاء "مشروع الوكيل"

5- استكشاف رمز الوكيل

المفاهيم الرئيسية

6. Automated Linting

7. الاختبار التفاعلي باستخدام Playground

اختبار ميزة "إعادة التحميل التلقائي في الوقت الفعلي"

8. تنفيذ سطر الأوامر

9. تنظيف

10. الملخّص والخطوات التالية

ما تعلّمته

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

موارد إضافية