درس تطبيقي حول الترميز: إنشاء وكلاء GraphRAG باستخدام "حزمة تطوير الوكلاء"

1. نظرة عامة

في هذا الدرس التطبيقي حول الترميز، ستنشئ نظامًا متطوّرًا لأبحاث الاستثمار متعدد الوكلاء يجمع بين إمكانات "حزمة تطوير الوكلاء" (ADK) من Google وقاعدة بيانات Neo4j Graph وMCP Toolbox. يوضّح هذا البرنامج التعليمي العملي كيفية إنشاء وكلاء أذكياء يفهمون سياق البيانات من خلال علاقات الرسوم البيانية ويقدّمون ردودًا دقيقة للغاية على طلبات البحث.

لماذا GraphRAG + أنظمة متعددة الوكلاء؟

تحسّن GraphRAG (التوليد المعزّز بالاسترجاع المستند إلى الرسم البياني) أساليب التوليد المعزّز بالاسترجاع التقليدية من خلال الاستفادة من بنية العلاقات الغنية في الرسومات البيانية المعرفية. بدلاً من البحث عن مستندات مشابهة فقط، يمكن لوكلاء GraphRAG إجراء ما يلي:

التنقّل بين العلاقات المعقّدة بين الكيانات
فهم السياق من خلال بنية الرسم البياني
تقديم نتائج قابلة للتفسير استنادًا إلى البيانات المرتبطة
تنفيذ الاستدلال المتعدّد الخطوات على مستوى الرسم البياني المعرفي

تتيح لك الأنظمة المتعددة الوكلاء ما يلي:

تقسيم المشاكل المعقّدة إلى مهام فرعية متخصّصة
إنشاء تطبيقات ذكاء اصطناعي معيارية يسهل صيانتها
تفعيل المعالجة المتوازية والاستخدام الفعّال للموارد
إنشاء أنماط استدلال هرمي باستخدام التنسيق

ما ستنشئه

ستنشئ نظامًا كاملاً لأبحاث الاستثمار يتضمّن ما يلي:

وكيل قاعدة بيانات الرسومات البيانية: ينفّذ طلبات بحث Cypher ويفهم مخطط Neo4j
وكيل أبحاث المستثمرين: يكتشف علاقات المستثمرين ومحافظهم الاستثمارية
وكيل أبحاث الاستثمار: يصل إلى رسومات بيانية معرفية شاملة من خلال أدوات MCP
الوكيل الرئيسي: ينسّق جميع الوكلاء الفرعيين بذكاء

سيجيب النظام عن أسئلة معقّدة مثل:

"مَن هم المنافسون الرئيسيون لـ YouTube؟"
ما هي الشركات التي تم ذكرها بشكل إيجابي في كانون الثاني (يناير) 2023؟
"مَن استثمر في شركة ByteDance وأين استثمر أيضًا؟"

نظرة عامة على البنية

من خلال هذا الدرس التطبيقي حول الترميز، ستتعرّف على الأسس المفاهيمية والتنفيذ العملي لإنشاء وكلاء GraphRAG على مستوى المؤسسات.

ما ستتعلمه

كيفية إنشاء أنظمة متعددة الوكلاء باستخدام "حزمة تطوير الوكلاء" (ADK) من Google
كيفية دمج قاعدة بيانات Neo4j البيانية مع ADK لتطبيقات GraphRAG
كيفية تنفيذ Model Context Protocol (MCP) Toolbox لطلبات البحث في قواعد البيانات التي تم التحقّق من صحتها مسبقًا
كيفية إنشاء أدوات ووظائف مخصّصة لوكلاء الذكاء الاصطناعي
كيفية تصميم التسلسلات الهرمية للوكلاء وأنماط التنسيق
كيفية تنظيم تعليمات الوكيل لتحقيق الأداء الأمثل
كيفية تصحيح أخطاء التفاعلات بين عدة وكلاء بشكل فعّال

المتطلبات

متصفّح الويب Chrome
حساب Gmail
مشروع Google Cloud تم تفعيل الفوترة فيه
معرفة أساسية بأوامر سطر الأوامر ولغة Python (مفيدة ولكنّها ليست مطلوبة)

يستخدم هذا الدرس التطبيقي حول الترميز، المصمّم للمطوّرين من جميع المستويات (بما في ذلك المبتدئين)، لغة Python وNeo4j في التطبيق النموذجي. على الرغم من أنّ الإلمام الأساسي بلغة Python وقواعد بيانات الرسوم البيانية يمكن أن يكون مفيدًا، لا يلزم وجود خبرة سابقة لفهم المفاهيم أو متابعة الدورة التدريبية.

2. التعرّف على التوليد المعزّز بالاسترجاع (GraphRAG) وأنظمة متعددة الوكلاء

قبل الخوض في تفاصيل التنفيذ، دعونا نتعرّف على المفاهيم الأساسية التي يستند إليها هذا النظام.

Neo4j هي قاعدة بيانات رسومية أصلية رائدة تخزّن البيانات كشبكة من العُقد (الكيانات) والعلاقات (الروابط بين الكيانات)، ما يجعلها مثالية لحالات الاستخدام التي يكون فيها فهم الروابط أمرًا أساسيًا، مثل الاقتراحات واكتشاف الاحتيال والرسوم البيانية المعرفية وغير ذلك. على عكس قواعد البيانات العلائقية أو المستندة إلى المستندات التي تعتمد على جداول ثابتة أو بنى هرمية، يتيح نموذج الرسم البياني المرن في Neo4j تمثيلاً بديهيًا وفعّالاً للبيانات المعقّدة والمترابطة.

بدلاً من تنظيم البيانات في صفوف وجداول مثل قواعد البيانات الارتباطية، تستخدم Neo4j نموذج رسم بياني، حيث يتم تمثيل المعلومات على شكل عُقد (كيانات) وعلاقات (روابط بين هذه الكيانات). ويجعل هذا النموذج التعامل مع البيانات المرتبطة بطبيعتها أمرًا سهلًا للغاية، مثل الأشخاص أو الأماكن أو المنتجات أو الأفلام أو الممثلين أو الأنواع في حالتنا.

على سبيل المثال، في مجموعة بيانات أفلام:

يمكن أن تمثّل العقدة Movie أو Actor أو Director
يمكن أن تكون العلاقة ACTED_IN أو DIRECTED

يتيح لك هذا البناء طرح أسئلة بسهولة، مثل:

ما هي الأفلام التي شارك فيها هذا الممثل؟
مَن عمل مع "كريستوفر نولان"؟
ما هي الأفلام المشابهة استنادًا إلى الممثلين أو الأنواع المشتركة؟

ما هي GraphRAG؟

تعزّز آلية التوليد المعزّز بالاسترجاع (RAG) ردود النماذج اللغوية الكبيرة من خلال استرجاع المعلومات ذات الصلة من مصادر خارجية. عادةً ما يتضمّن البحث والاسترجاع المستند إلى التوليد ما يلي:

تضمين المستندات في المتجهات
عمليات البحث عن متجهات مشابهة
تمرير المستندات التي تم استرجاعها إلى النموذج اللغوي الكبير

توسّع GraphRAG نطاق ذلك من خلال استخدام الرسومات البيانية المعرفية:

تضمين الكيانات والعلاقات
اجتياز روابط الرسم البياني
استرداد المعلومات السياقية المتعددة المراحل
تقدّم نتائج منظَّمة وقابلة للتفسير

لماذا الرسومات البيانية لوكلاء الذكاء الاصطناعي؟

اطرح السؤال التالي: "من هم منافسو YouTube، وما هي الجهات الاستثمارية التي موّلت كلاً من YouTube ومنافسيه؟"

ما يحدث في نهج RAG التقليدي:

عمليات البحث عن مستندات حول منافسي YouTube
البحث بشكل منفصل عن معلومات المستثمرين
صعوبة الربط بين هاتين المعلومتين
قد لا يتم رصد العلاقات الضمنية

ما يحدث في نهج GraphRAG:

MATCH (org:Organization {name: "OpenAI"})-[:HAS_COMPETITOR]-(competitor:Organization)
MATCH (org)-[:HAS_INVESTOR]->(investor:Person)
MATCH (competitor)-[:HAS_INVESTOR]->(investor)
RETURN org, competitor, investor

يمثّل الرسم البياني العلاقات بشكل طبيعي، ما يجعل طلبات البحث المتعددة الخطوات بسيطة وفعّالة.

أنظمة متعدّدة الوكلاء في ADK

حزمة تطوير الوكلاء (ADK) هي إطار عمل مفتوح المصدر من Google لإنشاء وكلاء الذكاء الاصطناعي ونشرهم في بيئة إنتاج. توفّر هذه المنصة عناصر أساسية سهلة الاستخدام لتنظيم الوكلاء المتعدّدين ودمج الأدوات وإدارة مهام سير العمل، ما يسهّل إنشاء أنظمة متطورة من خلال دمج الوكلاء المتخصّصين. تعمل "حزمة تطوير التطبيقات" بسلاسة مع Gemini وتتيح النشر على Cloud Run أو Kubernetes أو أي بنية أساسية.

توفّر "حزمة تطوير الوكلاء" (ADK) عناصر أساسية لإنشاء أنظمة متعددة الوكلاء:

التسلسل الهرمي لموظّف الدعم:

# Root agent coordinates specialized agents
root_agent = LlmAgent(
    name="RootAgent",
    sub_agents=[
        graph_db_agent,
        investor_agent,
        investment_agent
    ]
)

موظّفو الدعم المتخصّصون: لكل موظّف دعم

أدوات محدّدة: الدوال التي يمكنها استدعاؤها
تعليمات واضحة: دورها وإمكاناتها
الخبرة في المجال: معرفة مجالها

أنماط التنسيق:

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

MCP Toolbox for Databases

بروتوكول سياق النموذج (MCP) هو معيار مفتوح لربط أنظمة الذكاء الاصطناعي بمصادر البيانات والأدوات الخارجية. MCP Toolbox for Databases هي أداة من Google تتيح إدارة طلبات البحث في قواعد البيانات التعريفية، ما يسمح لك بتحديد طلبات بحث تم التحقّق من صحتها مسبقًا وأنشأها خبراء كأدوات قابلة لإعادة الاستخدام. بدلاً من السماح لنماذج اللغات الكبيرة بإنشاء طلبات بحث قد تكون غير آمنة، تقدّم "مجموعة أدوات بروتوكول سياق النموذج" طلبات بحث تمت الموافقة عليها مسبقًا مع التحقّق من صحة المَعلمات، ما يضمن الأمان والأداء والموثوقية مع الحفاظ على المرونة لوكلاء الذكاء الاصطناعي.

النهج التقليدي:

# LLM generates query (may be incorrect/unsafe)
query = llm.generate("SELECT * FROM users WHERE...")
db.execute(query)  # Risk of errors/SQL injection

منهجية MCP:

# Pre-validated query definition
- name: get_industries
  description: Fetch all industries from database
  query: |
    MATCH (i:Industry)
    RETURN i.name, i.id

المزايا:

تمت الموافقة عليها مسبقًا من قِبل الخبراء
الحماية من هجمات الحقن
تم تحسين الأداء
مُدارة مركزيًا
إعادة الاستخدام على مستوى الوكلاء

اللمسات الأخيرة

يؤدي الجمع بين GraphRAG وMulti-Agent Framework من خلال ADK وMCP إلى إنشاء نظام فعّال:

يتلقّى الوكيل الرئيسي طلب بحث المستخدم
توجيه الطلبات إلى موظف دعم متخصص استنادًا إلى نوع الطلب
يستخدم الوكيل أدوات MCP لاسترداد البيانات بأمان
بنية الرسم البياني توفّر سياقًا غنيًا
ينشئ النموذج اللغوي الكبير ردًا يستند إلى المصادر وقابلاً للتفسير

بعد أن فهمنا البنية، لنبدأ في الإنشاء.

3- إعداد مشروع Google Cloud

إنشاء مشروع

في Google Cloud Console، ضمن صفحة اختيار المشروع، اختَر مشروعًا على Google Cloud أو أنشِئه.
تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. تعرَّف على كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع .
ستستخدم Cloud Shell، وهي بيئة سطر أوامر تعمل في Google Cloud. انقر على "تفعيل Cloud Shell" في أعلى "وحدة تحكّم Google Cloud". يمكنك التبديل بين Cloud Shell Terminal (لتنفيذ أوامر السحابة الإلكترونية) والمحرّر (لإنشاء المشاريع) من خلال النقر على الزر المناسب من Cloud Shell.

صورة زر تفعيل Cloud Shell

بعد الاتصال بـ Cloud Shell، يمكنك التأكّد من أنّك قد أثبتّ هويتك وأنّ المشروع مضبوط على رقم تعريف مشروعك باستخدام الأمر التالي:

gcloud auth list

نفِّذ الأمر التالي في Cloud Shell للتأكّد من أنّ أمر gcloud يعرف مشروعك.

gcloud config list project

إذا لم يتم ضبط مشروعك، استخدِم الأمر التالي لضبطه:

gcloud config set project <YOUR_PROJECT_ID>

راجِع المستندات لمعرفة أوامر gcloud وطريقة استخدامها.

رائع! نحن الآن جاهزون للانتقال إلى الخطوة التالية، وهي فهم مجموعة البيانات.

4. التعرّف على مجموعة بيانات "الشركات"

في هذا الدرس التطبيقي حول الترميز، سنستخدم قاعدة بيانات Neo4j للقراءة فقط التي تمّت تعبئتها مسبقًا ببيانات الاستثمار والشركات من الرسم البياني المعرفي من Diffbot.

تحتوي مجموعة البيانات على ما يلي:

‫237,358 عقدة تمثّل:
المؤسسات (الشركات)
الأشخاص (المدراء التنفيذيون والموظفون)
المقالات (الأخبار والإشارات)
المجالات
التقنيات
المستثمرون
العلاقات، بما في ذلك:
‫HAS_INVESTOR - حسابات الاستثمار المرتبطة
‫HAS_COMPETITOR - العلاقات التنافسية
‫MENTIONS - مراجع المقالات
HAS_CEO - علاقات العمل
HAS_CATEGORY - تصنيفات المجالات

الوصول إلى قاعدة البيانات التجريبية

في هذا الدرس التطبيقي حول الترميز، سنستخدم إصدارًا تجريبيًا مستضافًا. أضِف بيانات الاعتماد التالية إلى ملاحظاتك:

URI: neo4j+s://demo.neo4jlabs.com
Username: companies
Password: companies
Database: companies

الوصول إلى المتصفّح:

يمكنك استكشاف البيانات بشكل مرئي على الرابط: https://demo.neo4jlabs.com:7473

سجِّل الدخول باستخدام بيانات الاعتماد نفسها وحاوِل تنفيذ ما يلي:

// Sample query to explore the graph
MATCH (c:Organization)-[:HAS_COMPETITOR]-(competitor:Organization)
RETURN c.name, competitor.name
LIMIT 10

عرض بنية الرسم البياني

جرِّب طلب البحث هذا في Neo4j Browser للاطّلاع على أنماط العلاقات:

// Find investors and their portfolio companies
MATCH (company:Organization)-[:HAS_INVESTOR]->(investor:Person)
WITH investor, collect(company.name) as portfolio
RETURN investor.name, size(portfolio) as num_investments, portfolio
ORDER BY num_investments DESC
LIMIT 5

يعرض طلب البحث هذا أهم 5 مستثمرين نشطين ومحافظهم الاستثمارية.

لماذا هذه قاعدة البيانات مناسبة لـ GraphRAG؟

تُعدّ مجموعة البيانات هذه مثالية لعرض GraphRAG لأنّها:

العلاقات الغنية: روابط معقّدة بين الكيانات
البيانات الواقعية: شركات وأشخاص ومقالات إخبارية فعلية
طلبات البحث المتعددة المراحل: تتطلّب التنقّل بين أنواع علاقات متعددة
البيانات الزمنية: المقالات التي تتضمّن طوابع زمنية لإجراء تحليل مستند إلى الوقت
تحليل المشاعر: نتائج المشاعر المحسوبة مسبقًا للمقالات

بعد أن فهمت بنية البيانات، لننتقل إلى إعداد بيئة التطوير.

5- إنشاء نسخة طبق الأصل من المستودع وضبط البيئة

إنشاء نسخة طبق الأصل من المستودع

في وحدة Cloud Shell الطرفية، شغِّل الأمر التالي:

# Clone the repository
git clone https://github.com/sidagarwal04/neo4j-adk-multiagents.git

# Navigate into the directory
cd neo4j-adk-multiagents

استكشاف بنية المستودع

يُرجى تخصيص بعض الوقت لفهم تخطيط المشروع:

neo4j-adk-multiagents/
├── investment_agent/       # Main agent code
│   ├── agent.py           # Agent definitions
│   ├── tools.py           # Custom tool functions
│   └── .adk/              # ADK configuration
│       └── tools.yaml     # MCP tool definitions
├── main.py                # Application entry point
├── setup_tools_yaml.py    # Configuration generator
├── requirements.txt       # Python dependencies
├── example.env           # Environment template
└── README.md             # Project documentation

إعداد بيئة افتراضية

إنشاء بيئة Python افتراضية وتفعيلها باستخدام uv:

# Install uv if not already installed
pip install uv

# Create virtual environment
uv venv

# Activate the environment
source .venv/bin/activate  # On macOS/Linux
# or
.venv\Scripts\activate  # On Windows

من المفترض أن يظهر (.venv) قبل موجّه الأوامر في نافذة الأوامر.

تثبيت الحِزم التابعة

ثبِّت جميع الحِزم المطلوبة:

uv pip install -r requirements.txt

تشمل التبعيات الرئيسية ما يلي:

txtgoogle-adk>=1.21.0          # Agent Development Kit
neo4j>=6.0.3               # Neo4j Python driver
python-dotenv>=1.0.0       # Environment variables
google-cloud-aiplatform>=1.30.0  # Vertex AI

ضبط متغيرات البيئة

أنشئ **.env** **ملفك:**

cp example.env .env

عدِّل **.env** **الملف:**

في حال استخدام Cloud Shell، انقر على "فتح المحرِّر" في شريط الأدوات، ثم انتقِل إلى .env وعدِّل ما يلي:

للكشف عن ملف .env المخفي، اتّبِع الخطوات التالية:

انقر على View > Toggle Hidden files في "محرِّر Google Cloud Shell".

# Neo4j Configuration (Demo Database)
NEO4J_URI=neo4j+s://demo.neo4jlabs.com
NEO4J_USERNAME=companies
NEO4J_PASSWORD=companies
NEO4J_DATABASE=companies

# Google AI Configuration
# Choose ONE of the following options:

# Option 1: Google AI API (Recommended)
GOOGLE_GENAI_USE_VERTEXAI=0
GOOGLE_API_KEY=your_api_key_here  # Get from https://aistudio.google.com/app/apikey

# Option 2: Vertex AI (If using GCP)
# GOOGLE_GENAI_USE_VERTEXAI=1
# GOOGLE_CLOUD_PROJECT=your-project-id
# GOOGLE_CLOUD_LOCATION=us-central1

# ADK Configuration
GOOGLE_ADK_MODEL=gemini-3.1-flash-lite-preview # or gemini-3-flash-preview

# MCP Toolbox Configuration
MCP_TOOLBOX_URL=https://toolbox-990868019953.us-central1.run.app/mcp/sse

إنشاء إعدادات "صندوق أدوات MCP":

نفِّذ برنامج الإعداد النصي لإنشاء ملف tools.yaml من متغيّرات البيئة:

python setup_tools_yaml.py

يؤدي ذلك إلى إنشاء investment_agent/.adk/tools.yaml مع ضبط بيانات اعتماد Neo4j بشكل صحيح لأدوات MCP.

التحقّق من الإعدادات

تأكَّد من إعداد كل شيء بشكل صحيح:

# Verify .env file exists
ls -la .env

# Verify tools.yaml was generated
ls -la investment_agent/.adk/tools.yaml

# Test Python environment
python -c "import google.adk; print('ADK installed successfully')"

# Test Neo4j connection
python -c "from neo4j import GraphDatabase; print('Neo4j driver installed')"

اكتملت الآن عملية ضبط إعدادات بيئة التطوير بالكامل. بعد ذلك، سنتعمّق في بنية الأنظمة المتعددة الوكلاء.

6. فهم بنية الوكلاء المتعدّدين

نظام الوكلاء الأربعة

يستخدم نظام أبحاث الاستثمار لدينا بنية متعددة الوكلاء هرمية مع أربعة وكلاء متخصصين يعملون معًا للإجابة عن طلبات البحث المعقدة حول الشركات والمستثمرين ومعلومات السوق.

                ┌──────────────┐
                │  Root Agent  │ ◄── User Query
                └──────┬───────┘
                       │
      ┌────────────────┼────────────────┐
      │                │                │
┌─────▼─────┐    ┌────▼─────┐    ┌────▼──────────┐
│ Graph DB  │    │ Investor │    │  Investment   │
│  Agent    │    │ Research │    │  Research     │
└───────────┘    │  Agent   │    │  Agent        │
                 └──────────┘    └───────────────┘

الوكيل الرئيسي (المنسّق):

يعمل "الوكيل الأساسي" كمنسّق ذكي للنظام بأكمله. يتلقّى طلبات المستخدمين ويحلّل النية ويوجه الطلبات إلى الوكيل المتخصّص الأنسب. يمكنك التفكير في هذه الميزة على أنّها مدير مشروع يفهم العضو الأنسب في الفريق لكل مهمة. يتولّى أيضًا تجميع الردود وتنسيق النتائج كجداول أو رسومات بيانية عند الطلب، والحفاظ على سياق المحادثة في طلبات بحث متعددة. يُفضّل "الوكيل الجذر" دائمًا الوكلاء المتخصّصين على وكيل قاعدة البيانات العامة، ما يضمن معالجة طلبات البحث من خلال المكوّن الأكثر خبرة المتاح.

وكيل قاعدة بيانات الرسوم البيانية:

يوفّر Graph Database Agent اتصالاً مباشرًا بإمكانات الرسوم البيانية الفعّالة في Neo4j. يفهم هذا النموذج مخطط قاعدة البيانات، وينشئ طلبات بحث بلغة Cypher من اللغة الطبيعية، وينفّذ عمليات اجتياز معقّدة للرسومات البيانية. يتخصّص هذا الوكيل في الأسئلة البنيوية وعمليات التجميع والاستنتاج المتعدّد الخطوات في الرسم البياني المعرفي. وهي الخبير الاحتياطي عندما تتطلّب الاستعلامات منطقًا مخصّصًا لا يمكن للأدوات المحدّدة مسبقًا التعامل معه، ما يجعلها ضرورية للتحليل الاستكشافي والاستعلامات التحليلية المعقّدة التي لم يتم توقّعها في تصميم النظام.

وكيل البحث عن المستثمرين:

يركّز "وكيل أبحاث المستثمرين" حصريًا على علاقات الاستثمار وتحليل المحافظ الاستثمارية. يمكنه تحديد المستثمرين في شركات معيّنة باستخدام ميزة مطابقة الاسم الدقيق، واسترداد محافظ المستثمرين الكاملة التي تعرض جميع استثماراتهم، وتحليل أنماط الاستثمار في مختلف الصناعات. يساعد هذا التخصّص في الإجابة عن أسئلة مثل "مَن استثمر في شركة ByteDance؟" أو "ما هي الشركات الأخرى التي استثمرت فيها شركة Sequoia Capital؟" يستخدم الوكيل دوال Python مخصّصة تستعلم مباشرةً من قاعدة بيانات Neo4j عن العلاقات المرتبطة بالمستثمرين.

وكيل أبحاث الاستثمار:

يستفيد "الوكيل الذكي لأبحاث الاستثمار" من "مجموعة أدوات بروتوكول سياق النموذج" (MCP) للوصول إلى طلبات بحث تم التحقّق من صحتها مسبقًا وأعدّها خبراء. يمكنه استرداد جميع المجالات المتاحة، واسترداد الشركات ضمن مجالات معيّنة، والعثور على مقالات تتضمّن تحليل المشاعر، واكتشاف الإشارات إلى المؤسسات في الأخبار، والحصول على معلومات عن الأشخاص العاملين في الشركات. على عكس Graph Database Agent الذي ينشئ طلبات البحث بشكلٍ ديناميكي، يستخدم هذا الوكيل طلبات بحث آمنة ومحسّنة ومحدّدة مسبقًا تتم إدارتها والتحقّق من صحتها مركزيًا. وهذا يجعلها آمنة وفعّالة في الوقت نفسه بالنسبة إلى مهام البحث الشائعة.

7. تشغيل نظام الوكلاء المتعدّدين واختباره

تشغيل التطبيق

بعد أن فهمت البنية، لنشغّل النظام الكامل ونتفاعل معه.

بدء تشغيل واجهة الويب الخاصة بـ ADK:

# Make sure you're in the project directory with activated virtual environment
cd ~/neo4j-adk-multiagents
source .venv/bin/activate  # If not already activated

# Launch the application
uv run adk web

من المفترَض أن تظهر لك نتيجة مشابهة لما يلي:

INFO:     Started server process [2542]
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: استكشاف الصناعات

What industries are available in the database?

السلوك المتوقّع:

توجيه طلبات Root Agent إلى Investment Research Agent
استخدام أداة MCP: get_industries()
تعرض هذه السمة قائمة منسَّقة بجميع المجالات.

ما يجب مراقبته:

في واجهة مستخدم "حزمة تطوير التطبيقات"، وسِّع تفاصيل التنفيذ للاطّلاع على ما يلي:

قرار اختيار الوكيل
استدعاء الأداة: get_industries()
نتائج أولية من Neo4j
الردّ المنسَّق

طلب البحث 2: العثور على مستثمرين

Who invested in ByteDance?

السلوك المتوقّع:

يحدّد Root Agent هذا الطلب على أنّه مرتبط بالمستثمرين
المسارات إلى "وكيل البحث عن المستثمرين"
الأداة المستخدَمة: find_investor_by_name("ByteDance")
تعرض هذه الطريقة المستثمرين مع أنواعهم (شخص/مؤسسة).

الردّ المتوقّع:

I found 2 investors in ByteDance:

1. Rong Yue (Person)
2. Wendi Murdoch (Person)

Would you like to know more about their investment portfolios?

الطلب 3: الشركات حسب المجال**

I found 2 investors in ByteDance:

1. Rong Yue (Person)
2. Wendi Murdoch (Person)

Would you like to know more about their investment portfolios?

"Show me companies in the Artificial Intelligence industry"

السلوك المتوقّع:

توجيه طلبات Root Agent إلى Investment Research Agent
استخدام أداة MCP: get_companies_in_industry("Artificial Intelligence")
تعرض هذه السمة قائمة بشركات الذكاء الاصطناعي مع أرقام التعريف وتواريخ التأسيس

ما يجب مراقبته:

لاحظ كيف يستخدم الوكيل مطابقة اسم المجال تمامًا
تكون النتائج محدودة لتجنُّب إخراج كمية كبيرة من البيانات
تنسيق البيانات بوضوح لتسهيل قراءتها

طلبات البحث المتوسطة (متعددة الخطوات ضمن وكيل واحد)

طلب البحث 4: تحليل المشاعر

Find articles with positive sentiment from January 2023

السلوك المتوقّع:

طرق الوصول إلى "أداة البحث عن الاستثمارات"
استخدام أداة MCP: get_articles_with_sentiment(0.7, 2023, 1)
عرض المقالات التي تتضمّن العناوين ونتائج تحليل المشاعر وتواريخ النشر

نصيحة لتصحيح الأخطاء:

اطّلِع على مَعلمات استدعاء الأداة:

‫min_sentiment: 0.7 (يفسّر الوكيل "إيجابي" على أنّه >= 0.7)
year: 2023
month: 1

طلب البحث 5: طلب بحث معقّد في قاعدة البيانات

How many companies are in the database?

السلوك المتوقّع:

توجيه طلبات Root Agent إلى Graph Database Agent
يتصل الوكيل get_neo4j_schema() أولاً لفهم البنية
إنشاء Cypher: MATCH (c:Company) RETURN count(c)
تنفيذ طلب البحث وعرض العدد

الردّ المتوقّع:

There are 8,064 companies in the database.

طلبات البحث المتقدّمة (التنسيق بين عدّة وكلاء)

طلب البحث 6: تحليل المحفظة

Who invested in ByteDance and what else have they invested in?

السلوك المتوقّع:

هذا طلب بحث من جزأين يتطلّب تنسيقًا بين الوكلاء:

الخطوة 1: الوكيل الأساسي ← وكيل البحث عن المستثمرين
المكالمات find_investor_by_name("ByteDance")
الحصول على قائمة المستثمرين: [رونغ يوي، ويندي مردوخ]
الخطوة 2: لكل مستثمر → Investor Research Agent
المكالمات find_investor_by_id(investor_id)
استرداد المحفظة الكاملة
الخطوة 3: تجميع Root Agent وتنسيقه

الردّ المتوقّع:

I found 2 investors in ByteDance. Here are their portfolios:

1. Rong Yue (Person)
   - ByteDance
   - Inspur
   
2. Wendi Murdoch (Person)
   - ByteDance
   - (No other investments in database)

ما يجب مراقبته:

استدعاء أدوات متعددة بالتسلسل
الحفاظ على السياق بين الخطوات
نتائج مجمّعة بذكاء

طلب البحث 7: البحث في عدة نطاقات

What are 5 AI companies mentioned in positive articles, and who are their CEOs?

السلوك المتوقّع:

يتطلّب هذا الاستعلام المعقّد عدة وكلاء وأدوات:

الخطوة 1: وكيل أبحاث الاستثمار
get_companies_in_industry("Artificial Intelligence")
عرض قائمة بشركات الذكاء الاصطناعي
الخطوة 2: Investment Research Agent
get_articles_with_sentiment(0.8)
عرض مقالات إيجابية
الخطوة 3: فلاتر Root Agent
تحديد شركات الذكاء الاصطناعي التي تظهر في مقالات إيجابية
اختيار أهم 5
الخطوة 4: Investment Research Agent
get_people_in_organizations([company_names], "CEO")
عرض معلومات الرئيس التنفيذي
الخطوة 5: تنسيقات Root Agent كجدول

الردّ المتوقّع:

Here are 5 AI companies with positive news and their CEOs:

| Company | Industry | CEO | Avg Sentiment |
|---------|----------|-----|---------------|
| OpenAI | Artificial Intelligence | Sam Altman | 0.92 |
| Anthropic | Artificial Intelligence | Dario Amodei | 0.89 |
| ... | ... | ... | ... |

ما يجب مراقبته:

استدعاء أدوات متعددة من خلال وكلاء مختلفين
فلترة البيانات ومنطق الدمج
تنسيق جدول احترافي

طلب البحث 8: تحليل تنافسي

Who are YouTube's main competitors?

السلوك المتوقّع:

يوجّه Root Agent الطلب إلى Graph Database Agent (طلب بحث عن علاقة)
ينشئ الوكيل رمز Cypher محسّنًا باستخدام GraphRAG:

MATCH (c:Company {name: "YouTube"})-[:COMPETES_WITH]->(competitor)
RETURN competitor.name as competitor_name

عرض قائمة بالشركات المنافسة

الردّ المتوقّع:

YouTube's main competitors are:

- TikTok (ByteDance)
- Dailymotion
- Twitter
- BuzzFeed
- Mixer
- OpenAI (for video content)

طلبات البحث اللاحقة المستنِدة إلى السياق

طلب البحث 9: سؤال متابعة (بعد طلب البحث 8)

Which investors funded both YouTube and its competitors?

السلوك المتوقّع:

يتذكّر Root Agent السياق السابق (YouTube والمنافسون)
المسارات إلى "وكيل البحث عن المستثمرين"
بالنسبة إلى YouTube وكل منافس، يمكنك العثور على المستثمرين
تحديد المستثمرين الذين يظهرون في شركات متعددة

الردّ المتوقّع:

Based on our previous analysis of YouTube's competitors, I found these 
investors who funded multiple companies in this competitive landscape:

Sequoia Capital invested in:
- YouTube
- TikTok (ByteDance)
- Twitter

Accel Partners invested in:
- YouTube  
- BuzzFeed

This suggests these investors have strategic positions across the video content platform ecosystem.

طلب البحث 10: ملخّص البحث

Summarize our research findings so far

السلوك المتوقّع:

مراجعة Root Agent لسجلّ المحادثات
تجميع النتائج الرئيسية من طلبات البحث السابقة
تقديم ملخّص متماسك

الردّ المتوقّع:

Here's a summary of our investment research session:

1. Industry Overview: We explored the Artificial Intelligence industry 
   with 150+ companies in the database.

2. ByteDance Analysis: 
   - Investors: Rong Yue, Wendi Murdoch
   - Rong Yue also invested in Inspur

3. Market Sentiment: We analyzed articles from January 2023, finding 
   strong positive sentiment (avg 0.85) for tech companies.

4. Competitive Landscape: YouTube faces competition from TikTok, 
   Dailymotion, and others, with some investors (Sequoia, Accel) holding 
   positions across competing platforms.

5. Key Players: Identified CEOs of major AI companies with positive media coverage.

فهم تفاعلات الوكيل في "طريقة العرض للتصحيح"

توفّر واجهة الويب الخاصة بـ ADK إمكانية الاطّلاع على تفاصيل التنفيذ. في ما يلي ما يجب البحث عنه:

المخطط الزمني للأحداث

تعرض هذه السمة التسلسل الزمني على النحو التالي:

[USER] Query received
[ROOT_AGENT] Analyzing query intent
[ROOT_AGENT] Routing to investment_research_agent
[INVESTMENT_RESEARCH_AGENT] Tool call: get_companies_in_industry
[TOOL] Executing with params: {"industry_name": "Artificial Intelligence"}
[TOOL] Returned 47 results
[INVESTMENT_RESEARCH_AGENT] Formatting response
[ROOT_AGENT] Presenting to user

تفاصيل استدعاء الأداة

انقر على أي استدعاء أداة للاطّلاع على ما يلي:

اسم الوظيفة
مَعلمات الإدخال
القيمة المعروضة
وقت التنفيذ
أي أخطاء

اتّخاذ القرارات من قِبل الوكيل

مراقبة عملية الاستدلال التي يجريها النموذج اللغوي الكبير:

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

الملاحظات والإحصاءات الشائعة

أنماط توجيه طلبات البحث:
كلمات رئيسية مثل "مستثمر" و"استثمار" → "وكيل أبحاث المستثمرين"
كلمات رئيسية مثل "مجال" و"شركات" و"مقالات" ← وكيل أبحاث الاستثمار
عمليات التجميع والعدّ والمنطق المعقّد → Graph Database Agent
ملاحظات حول الأداء:
تكون أدوات MCP عادةً أسرع (طلبات بحث مُحسَّنة مسبقًا)
يستغرق إنشاء استعلامات Cypher المعقّدة وقتًا أطول (وقت تفكير النموذج اللغوي الكبير).
تؤدي طلبات استخدام أدوات متعددة إلى زيادة وقت الاستجابة، ولكنها تقدّم نتائج أكثر ثراءً.
التعامل مع الأخطاء:
في حال تعذّر تنفيذ طلب بحث:
الوكيل يوضّح المشكلة
يقترح تصحيحات (مثلاً، "لم يتم العثور على اسم الشركة، يُرجى التحقّق من التدقيق الإملائي")
قد يتم تجربة أساليب بديلة

نصائح لإجراء اختبارات فعّالة

البدء بأسئلة بسيطة: اختبِر الوظائف الأساسية لكل وكيل قبل طرح طلبات بحث معقّدة.
استخدام المتابعات: اختبِر الاحتفاظ بالسياق من خلال أسئلة المتابعة
مراقبة التوجيه: راقِب الموظف الذي يتعامل مع كل طلب بحث لفهم منطق التوجيه.
التحقّق من استدعاء الأدوات: التأكّد من استخراج المَعلمات بشكل صحيح من اللغة الطبيعية
اختبار الحالات القصوى: جرِّب طلبات بحث غامضة أو أخطاء إملائية أو طلبات غير معتادة

أصبح لديك الآن نظام GraphRAG متعدد الوكلاء يعمل بكامل طاقته. جرِّب طرح أسئلتك الخاصة لاستكشاف إمكاناتها.

8. تَنظيم

لتجنُّب تحمّل رسوم في حسابك على Google Cloud مقابل الموارد المستخدَمة في هذه المشاركة، اتّبِع الخطوات التالية:

في Google Cloud Console، انتقِل إلى صفحة إدارة الموارد.
في قائمة المشاريع، اختَر المشروع الذي تريد حذفه، ثم انقر على حذف.
في مربّع الحوار، اكتب رقم تعريف المشروع، ثم انقر على إيقاف لحذف المشروع.

9- تهانينا

🎉 تهانينا! لقد أنشأت بنجاح نظام GraphRAG متعدد الوكلاء بجودة إنتاجية باستخدام "حزمة تطوير الوكلاء" من Google وNeo4j وMCP Toolbox.

من خلال الجمع بين إمكانات التنسيق الذكي في ADK ونموذج البيانات الغني بالعلاقات في Neo4j وأمان طلبات بحث MCP التي تم التحقّق من صحتها مسبقًا، أنشأت نظامًا متطوّرًا يتجاوز طلبات البحث البسيطة في قاعدة البيانات، فهو يفهم السياق ويستدل في العلاقات المعقّدة وينسّق الوكلاء المتخصّصين لتقديم إحصاءات شاملة ودقيقة.

في هذا الدرس التطبيقي حول الترميز، أكملت ما يلي:

✅ إنشاء نظام متعدد الوكلاء باستخدام "حزمة تطوير الوكلاء" (ADK) من Google مع تنظيم هرمي

✅ قاعدة بيانات رسومية مدمجة من Neo4j للاستفادة من طلبات البحث التي تراعي العلاقات والاستدلال المتعدد الخطوات

‫✅ تنفيذ MCP Toolbox لطلبات البحث الآمنة والمسبقة التحقّق في قواعد البيانات كأدوات قابلة لإعادة الاستخدام

✅ إنشاء وكلاء متخصصين للبحث عن المستثمرين وتحليل الاستثمارات وعمليات قاعدة البيانات البيانية

✅ تصميم عملية توجيه ذكية تفوّض طلبات البحث تلقائيًا إلى وكيل الدعم الخبير الأنسب

✅ التعامل مع أنواع البيانات المعقّدة من خلال تسلسل أنواع Neo4j المناسب لدمج Python بسلاسة

✅ تطبيق أفضل ممارسات الإنتاج لتصميم الوكيل والتعامل مع الأخطاء وتصحيح أخطاء النظام

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

لا يقتصر تصميم GraphRAG المتعدد الوكلاء على أبحاث الاستثمار، بل يمكن توسيعه ليشمل ما يلي:

الخدمات المالية: تحسين المحفظة وتقييم المخاطر ورصد الاحتيال
الرعاية الصحية: تنسيق رعاية المرضى، وتحليل التفاعلات الدوائية، والبحوث السريرية
التجارة الإلكترونية: اقتراحات مخصّصة، وتحسين سلسلة الإمداد، وإحصاءات العملاء
المسائل القانونية والامتثال: تحليل العقود، ومراقبة اللوائح التنظيمية، والبحث في السوابق القضائية
البحث الأكاديمي: مراجعة المحتوى الأدبي، واكتشاف التعاون، وتحليل الاقتباسات
ذكاء المؤسسات: تحليل المنافسين، وأبحاث السوق، والرسومات البيانية المعرفية للمؤسسات

في أي مكان يتوفّر فيه بيانات معقّدة مترابطة + خبرة في المجال + واجهات لغة طبيعية، يمكن أن يؤدي هذا المزيج من أنظمة الوكلاء المتعدّدين في ADK ورسوم Neo4j البيانية المعرفية والاستعلامات التي تم التحقّق من صحتها باستخدام MCP إلى تعزيز الجيل التالي من تطبيقات المؤسسات الذكية.

مع استمرار تطوّر "حزمة تطوير الوكلاء" ونماذج Gemini من Google، ستتمكّن من دمج أنماط استدلال أكثر تطورًا، ودمج البيانات في الوقت الفعلي، وإمكانات متعدّدة الوسائط لإنشاء أنظمة ذكية حقًا ومدرِكة للسياق.

استمر في الاستكشاف والبناء للارتقاء بتطبيقاتك المستندة إلى الوكلاء الأذكياء إلى المستوى التالي.

يمكنك استكشاف المزيد من البرامج التعليمية العملية حول "الرسم البياني المعرفي" على Neo4j GraphAcademy والتعرّف على أنماط إضافية للوكلاء في مستودع نماذج ADK.

🚀 هل أنت مستعد لإنشاء نظام وكيل ذكي جديد؟

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

Google ADK:
مستودع GitHub الرسمي
مستندات شاملة
مستودع الأمثلة
مدونة الإطلاق
Neo4j:
Neo4j GenAI Hub
Neo4j Developer
GraphRAG
Neo4j GenAI Ecosystem
وكلاء الذكاء الاصطناعي باستخدام Neo4j وMCP Toolbox