Agent Development Kit (ADK)

دليلك الشامل لبناء جيل جديد من التطبيقات الذكية لشركة RUI باستخدام إطار عمل جوجل المتقدم.

1. تهيئة البيئة البرمجية

قبل البدء، تأكدي من استخدام Python 3.10+ وتجهيز بيئة افتراضية (Virtual Environment) للحفاظ على استقرار مشروع ONYX.

إنشاء وتفعيل البيئة (Windows):

python -m venv .venv
.venv\Scripts\activate

python -m venv .venv
.venv\Scripts\activate

تثبيت المكتبات المطلوبة:

pip install google-adk litellm

pip install google-adk litellm

2. بناء وكيل متعدد الأدوات (Multi-Tool Agent)

هذا النوع من الوكلاء قادر على تنفيذ وظائف حقيقية مثل جلب الطقس أو الوقت عبر ربط الموديل بدوال Python مباشرة. الـ Docstrings هنا هي مفتاح الذكاء، لأن الموديل يستخدمها ليفهم متى يستدعي الأداة.

هيكلية المجلد المقترحة:

multi_tool_agent/
├── __init__.py   # "from . import agent"
├── agent.py      # ملف تعريف المنطق والأدوات
└── .env          # مفاتيح API (GOOGLE_API_KEY)

مثال تطبيقي (agent.py):

import datetime
from zoneinfo import ZoneInfo
from google.adk.agents import Agent

def get_weather(city: str) -> dict:
    """جلب حالة الطقس الحالية لمدينة محددة."""
    # يمكن هنا ربط API حقيقي لاحقاً
    return {"status": "success", "report": f"الطقس في {city} مشمس حالياً."}

root_agent = Agent(
    name="weather_time_agent",
    model="gemini-2.5-flash",
    description="وكيل متخصص في الطقس والوقت.",
    instruction="أنت مساعد ودود، استخدم الأدوات المتاحة فقط للإجابة على استفسارات المدن.",
    tools=[get_weather],
)

import datetime
from zoneinfo import ZoneInfo
from google.adk.agents import Agent

def get_weather(city: str) -> dict:
    """جلب حالة الطقس الحالية لمدينة محددة."""
    # يمكن هنا ربط API حقيقي لاحقاً
    return {"status": "success", "report": f"الطقس في {city} مشمس حالياً."}

root_agent = Agent(
    name="weather_time_agent",
    model="gemini-2.5-flash",
    description="وكيل متخصص في الطقس والوقت.",
    instruction="أنت مساعد ودود، استخدم الأدوات المتاحة فقط للإجابة على استفسارات المدن.",
    tools=[get_weather],
)

3. بناء فريق الوكلاء الأذكياء (Agent Team)

هنا يكمن الفرق الجوهري! بدلاً من وكيل واحد بمهام محدودة، نقوم ببناء نظام هرمي (Multi-Agent System). هذا الأسلوب يتيح توزيع المهام بين "عقول" مختلفة لزيادة الدقة وتقليل الأخطاء.

ما الجديد في نظام الفرق؟

المرونة مع عدة نماذج (Multi-LLM):استخدام Gemini للمهام السريعة، و GPT-4o للمهام المعقدة، و Claude للتحليل اللغوي في نفس الجلسة.
التفويض الذكي (Delegation):توزيع الطلبات تلقائياً (Auto Flow) على وكلاء فرعيين (مثلاً وكيل للترحيب، ووكيل للبحث التقني).
الذاكرة المستمرة (Session State):تمكين الوكلاء من تذكر تفضيلات المستخدم عبر تعاقب الأدوار (Turns) باستخدام Session Service.

مقارنة سريعة:

الميزة	Single Agent	Agent Team
المهام	محدودة/بسيطة	معقدة/تراكمية
النماذج	نموذج واحد	هجين (Gemini, Claude, GPT)
السياق	ذاكرة لحظية	ذاكرة جلسة مستمرة

4. صمامات الأمان (Guardrails)

عند بناء أنظمة متقدمة لشركة RUI، من الضروري مراقبة أداء الوكلاء. ADK يوفر ميزة **Callbacks** التي تسمح لكِ بـ:

before_model_callbackفحص طلب المستخدم وتعديله أو حظره قبل أن يصل للموديل (لحماية الخصوصية).

before_tool_callbackمراجعة المدخلات التي يريد الوكيل إرسالها للأداة قبل التنفيذ الفعلي (أمان الكود).

5. تشغيل وإدارة الجلسات

للتفاعل مع الوكلاء برمجياً في بيئات مثل Jupyter أو في الـ Backend الخاص بـ ONYX، نستخدم الـ **Runner**.

from google.adk.sessions import InMemorySessionService
from google.adk.runners import Runner

# إدارة الذاكرة والجلسات
session_service = InMemorySessionService()

# تشغيل الوكيل ضمن سياق تطبيق محدد
runner = Runner(
    agent=weather_agent,
    app_name="ONYX_Weather_Bot",
    session_service=session_service
)

from google.adk.sessions import InMemorySessionService
from google.adk.runners import Runner

# إدارة الذاكرة والجلسات
session_service = InMemorySessionService()

# تشغيل الوكيل ضمن سياق تطبيق محدد
runner = Runner(
    agent=weather_agent,
    app_name="ONYX_Weather_Bot",
    session_service=session_service
)

Author: ONYX (2026)

Base Model: Agent Development Kit (ADK)