1- نظرة عامة
في هذا الدرس العملي، ستنشئ نظامًا متطوّرًا لأبحاث الاستثمار متعددة الجهات يجمع بين إمكانات "حزمة تطوير البرامج" (ADK) من Google وقاعدة بيانات Neo4j Graph Database ومجموعة أدوات "بروتوكول سياق النموذج" (MCP). يوضّح هذا البرنامج التعليمي العملي كيفية إنشاء وكلاء أذكياء يفهمون سياق البيانات من خلال علاقات الرسوم البيانية ويقدّمون ردودًا دقيقة للغاية على طلبات البحث.
لماذا GraphRAG + أنظمة متعددة الوكلاء؟
تعمل GraphRAG (التوليد المعزّز بالاسترجاع المستند إلى الرسومات البيانية) على تحسين أساليب التوليد المعزّز بالاسترجاع التقليدية من خلال الاستفادة من بنية العلاقات الغنية في الرسومات البيانية المعرفية. بدلاً من البحث عن مستندات مشابهة فقط، يمكن لوكلاء GraphRAG تنفيذ ما يلي:
- التنقّل بين العلاقات المعقّدة بين الكيانات
- فهم السياق من خلال بنية الرسم البياني
- تقديم نتائج قابلة للتفسير استنادًا إلى البيانات المرتبطة
- تنفيذ الاستدلال المتعدّد الخطوات على مستوى الرسم البياني المعرفي
تتيح لك أنظمة الوكلاء المتعددين ما يلي:
- تقسيم المشاكل المعقّدة إلى مهام فرعية متخصّصة
- إنشاء تطبيقات ذكاء اصطناعي معيارية وسهلة الصيانة
- تفعيل المعالجة المتوازية والاستخدام الفعّال للموارد
- إنشاء أنماط استدلال هرمي باستخدام التنسيق
ما ستنشئه
ستنشئ نظامًا كاملاً لأبحاث الاستثمار يتضمّن ما يلي:
- وكيل قاعدة بيانات الرسوم البيانية: ينفّذ طلبات بحث Cypher ويفهم مخطط Neo4j
- وكيل أبحاث المستثمرين: يكتشف علاقات المستثمرين ومحافظهم الاستثمارية
- وكيل أبحاث الاستثمار: يصل إلى رسومات بيانية معرفية شاملة من خلال أدوات MCP
- الوكيل الرئيسي: يدير جميع الوكلاء الفرعيين بذكاء
سيجيب النظام عن أسئلة معقّدة مثل:
- "مَن هم المنافسون الرئيسيون لـ YouTube؟"
- "ما هي الشركات التي تم ذكرها بشكل إيجابي في يناير 2023؟"
- "مَن استثمر في شركة ByteDance وأين استثمر أيضًا؟"
نظرة عامة على البنية
من خلال هذا الدرس التطبيقي حول الترميز، ستتعرّف على الأسس المفاهيمية والتنفيذ العملي لإنشاء وكلاء GraphRAG على مستوى المؤسسة.
ما ستتعلمه
- كيفية إنشاء أنظمة متعددة الوكلاء باستخدام "حزمة تطوير الوكلاء" (ADK) من Google
- كيفية دمج قاعدة بيانات Neo4j للرسومات مع "حزمة تطوير التطبيقات" لتطبيقات GraphRAG
- كيفية تنفيذ "مجموعة أدوات بروتوكول سياق النموذج" (MCP) لطلبات البحث في قاعدة البيانات التي تم التحقّق من صحتها مسبقًا
- كيفية إنشاء أدوات ووظائف مخصّصة لوكلاء الذكاء الاصطناعي
- كيفية تصميم التسلسلات الهرمية للوكلاء وأنماط التنسيق
- كيفية تنظيم تعليمات الوكيل لتحقيق الأداء الأمثل
- كيفية تصحيح أخطاء التفاعلات بين عدة وكلاء بشكل فعّال
المتطلبات
- متصفّح الويب Chrome
- حساب Gmail
- مشروع Google Cloud تم تفعيل الفوترة فيه
- الإلمام الأساسي بأوامر سطر الأوامر ولغة بايثون (مفيد ولكن ليس مطلوبًا)
يستخدم هذا الدرس التطبيقي، المصمّم للمطوّرين من جميع المستويات (بما في ذلك المبتدئين)، لغة Python وNeo4j في التطبيق النموذجي. على الرغم من أنّ الإلمام الأساسي بلغة Python وقواعد بيانات الرسوم البيانية يمكن أن يكون مفيدًا، لا يلزم وجود خبرة سابقة لفهم المفاهيم أو متابعة الدورة التدريبية.
2. التعرّف على GraphRAG وMulti-Agent Systems
قبل الخوض في تفاصيل التنفيذ، دعونا نتعرّف على المفاهيم الأساسية التي يستند إليها هذا النظام.
Neo4j هي قاعدة بيانات رسومية أصلية رائدة تخزّن البيانات كشبكة من العُقد (الكيانات) والعلاقات (الروابط بين الكيانات)، ما يجعلها مثالية لحالات الاستخدام التي يكون فيها فهم الروابط أمرًا أساسيًا، مثل الاقتراحات واكتشاف الاحتيال والرسوم البيانية المعرفية وغير ذلك. على عكس قواعد البيانات العلائقية أو المستندة إلى المستندات التي تعتمد على جداول ثابتة أو بنى هرمية، يتيح نموذج الرسم البياني المرن في Neo4j تمثيلاً بديهيًا وفعّالاً للبيانات المعقّدة والمترابطة.
بدلاً من تنظيم البيانات في صفوف وجداول مثل قواعد البيانات الارتباطية، تستخدم Neo4j نموذج رسم بياني، حيث يتم تمثيل المعلومات على شكل عُقد (كيانات) وعلاقات (روابط بين هذه الكيانات). ويجعل هذا النموذج التعامل مع البيانات المرتبطة بطبيعتها أمرًا سهلًا للغاية، مثل الأشخاص أو الأماكن أو المنتجات أو الأفلام أو الممثلين أو الأنواع في حالتنا.
على سبيل المثال، في مجموعة بيانات أفلام:
- يمكن أن تمثّل العقدة
MovieأوActorأوDirector - يمكن أن تكون العلاقة
ACTED_INأوDIRECTED
يتيح لك هذا البناء طرح أسئلة بسهولة، مثل:
- ما هي الأفلام التي شارك فيها هذا الممثل؟
- مَن عمل مع "كريستوفر نولان"؟
- ما هي الأفلام المشابهة استنادًا إلى الممثلين أو الأنواع المشتركة؟
ما هي GraphRAG؟
تعزّز آلية التوليد المعزّز بالاسترجاع (RAG) ردود النماذج اللغوية الكبيرة من خلال استرجاع المعلومات ذات الصلة من مصادر خارجية. عادةً ما تتضمّن نماذج RAG التقليدية ما يلي:
- تضمين المستندات في المتجهات
- عمليات البحث عن متجهات مشابهة
- تمرير المستندات التي تم استرجاعها إلى النموذج اللغوي الكبير
توسّع GraphRAG نطاق ذلك باستخدام الرسومات البيانية المعرفية:
- تضمين الكيانات والعلاقات
- اجتياز روابط الرسم البياني
- استرداد المعلومات السياقية المتعددة المراحل
- تقدّم نتائج منظَّمة وقابلة للتفسير
لماذا الرسومات البيانية لوكلاء الذكاء الاصطناعي؟
اطرح السؤال التالي: "مَن هم منافسو YouTube، وما هي الجهات الاستثمارية التي موّلت كلاً من YouTube ومنافسيه؟"
ما يحدث في نهج RAG التقليدي:
- عمليات البحث عن مستندات حول منافسي YouTube
- البحث بشكل منفصل عن معلومات المستثمرين
- صعوبة الربط بين هاتين المعلومتين
- قد لا يتم رصد العلاقات الضمنية
ما يحدث في نهج GraphRAG:
MATCH (youtube:Company {name: "YouTube"})-[:COMPETES_WITH]->(competitor:Company)
MATCH (investor:Investor)-[:INVESTED_IN]->(youtube)
MATCH (investor)-[:INVESTED_IN]->(competitor)
RETURN youtube, competitor, investor
يمثّل الرسم البياني العلاقات بشكل طبيعي، ما يجعل طلبات البحث المتعددة الخطوات بسيطة وفعّالة.
الأنظمة المتعددة الوكلاء في "حزمة تطوير التطبيقات"
حزمة تطوير الوكلاء (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 لقواعد البيانات
بروتوكول سياق النموذج (MCP) هو معيار مفتوح لربط أنظمة الذكاء الاصطناعي بمصادر وأدوات البيانات الخارجية. MCP Toolbox for Databases هي إحدى أدوات Google التي تتيح إدارة طلبات البحث في قواعد البيانات بشكل تعريفي، ما يسمح لك بتحديد طلبات بحث تم التحقّق من صحتها مسبقًا وأنشأها خبراء كأدوات قابلة لإعادة الاستخدام. بدلاً من السماح لنماذج اللغات الكبيرة بإنشاء طلبات بحث قد تكون غير آمنة، تقدّم "أداة MCP" طلبات بحث معتمَدة مسبقًا مع التحقّق من صحة المَعلمات، ما يضمن الأمان والأداء والموثوقية مع الحفاظ على المرونة لبرامج الذكاء الاصطناعي.
النهج التقليدي:
# 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. تعرَّف على كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع .
- ستستخدم Cloud Shell، وهي بيئة سطر أوامر تعمل في Google Cloud. انقر على "تفعيل Cloud Shell" في أعلى "وحدة تحكّم Google Cloud". يمكنك التبديل بين "نافذة 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 عقدة تمثّل:
- المؤسسات (الشركات)
- الأشخاص (المدراء التنفيذيون والموظفون)
- المقالات (الأخبار والإشارات)
- المجالات
- التكنولوجيات
- المستثمرون
- العلاقات، بما في ذلك:
-
INVESTED_IN- حسابات الاستثمار المرتبطة -
COMPETES_WITH- علاقات تنافسية -
MENTIONS- مراجع المقالات WORKS_AT- علاقات العمل-
IN_INDUSTRY- تصنيفات المجالات
الوصول إلى قاعدة البيانات التجريبية
في هذا الدرس التطبيقي، سنستخدم نسخة تجريبية مستضافة. أضِف بيانات الاعتماد هذه إلى ملاحظاتك:
URI: neo4j+s://demo.neo4jlabs.com
Username: companies
Password: companies
Database: companies
الوصول إلى المتصفّح:
يمكنك استكشاف البيانات بشكل مرئي على الرابط: https://demo.neo4jlabs.com:7473
سجِّل الدخول باستخدام بيانات الاعتماد نفسها وحاوِل تنفيذ ما يلي:
// Sample query to explore the graph
MATCH (o:Organization)-[:HAS_COMPETITOR]->(competitor:Organization)
RETURN o.name, competitor.name
LIMIT 10
عرض بنية الرسم البياني
جرِّب طلب البحث هذا في Neo4j Browser للاطّلاع على أنماط العلاقات:
// Find investors and their portfolio companies
MATCH (investor:Organization)-[:HAS_INVESTOR]->(company:Organization)
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
إنشاء بيئة Python افتراضية وتفعيلها باستخدام 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
تشمل التبعيات الرئيسية ما يلي:
google-adk>=1.21.0 # Agent Development Kit
neo4j>=6.0.3 # Neo4j Python driver
python-dotenv>=1.0.0 # Environment variables
ضبط متغيرات البيئة
- أنشئ ملف
.envباتّباع الخطوات التالية:
cp example.env .env
- عدِّل ملف
.env:
في حال استخدام Cloud Shell، انقر على "فتح المحرِّر" في شريط الأدوات، ثم انتقِل إلى .env وعدِّل ما يلي:
# Neo4j Configuration (Demo Database)
NEO4J_URI=neo4j+ssc://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-pro-preview # or gemini-3-flash-preview
# MCP Toolbox Configuration
MCP_TOOLBOX_URL=https://toolbox-990868019953.us-central1.run.app/mcp/sse
- إعدادات MCP Toolbox (تم ضبطها مسبقًا - لا حاجة إلى تشغيلها):
في هذا الدرس العملي، تتم استضافة "مجموعة أدوات MCP" وإعدادها مسبقًا، لذلك لن تحتاج إلى إنشاء ملف tools.yaml أو إدارته محليًا.
عادةً، عليك تنفيذ الأمر التالي لإنشاء ملف tools.yaml من متغيّرات البيئة بعد تعديل investment_agent/.adk/tools.yaml.template حسب الحاجة:
python setup_tools_yaml.py
سيؤدي ذلك إلى إنشاء investment_agent/.adk/tools.yaml مع ضبط بيانات اعتماد Neo4j بشكل صحيح لأداة MCP Toolbox.
يجب تنفيذ النص البرمجي أعلاه فقط في الحالات التالية:
- تستضيف بنفسك أداة MCP Toolbox
- أنت بصدد الربط بقاعدة بيانات أو مجموعة بيانات مختلفة من Neo4j
- تريد تحديد أدوات أو بيانات اعتماد مخصّصة
في هذه الحالات، يجب تعديل عنوان URL الخاص بـ "أدوات MCP" وإعدادات tools.yaml وفقًا لذلك.
التحقّق من الإعدادات
تأكَّد من إعداد كل شيء بشكل صحيح:
# 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 عن العلاقات المرتبطة بالمستثمرين.
- وكيل أبحاث الاستثمار:
يستفيد "الوكيل الذكي لأبحاث الاستثمار" من "مجموعة أدوات بروتوكول Model Context" للوصول إلى طلبات بحث تم التحقّق من صحتها مسبقًا وأنشأها خبراء. يمكنه استرداد جميع المجالات المتاحة، واسترداد الشركات ضمن مجالات معيّنة، والعثور على مقالات تتضمّن تحليل المشاعر، واكتشاف الإشارات إلى المؤسسات في الأخبار، والحصول على معلومات عن الأشخاص العاملين في الشركات. على عكس 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)
بعد ظهور رسالة تفيد ببدء تشغيل الخادم بنجاح، افتح المتصفّح وانتقِل إلى http://127.0.0.1:8000 للوصول إلى التطبيق.
طلبات البحث التجريبية والسلوك المتوقّع
لنتعرّف على إمكانات النظام من خلال استعلامات تزداد تعقيدًا تدريجيًا:
طلبات البحث الأساسية (وكيل واحد)
طلب البحث 1: استكشاف الصناعات
What industries are available in the database?
السلوك المتوقّع:
- توجيه طلبات Root Agent إلى Investment Research Agent
- استخدام أداة MCP:
get_industries() - تعرض هذه السمة قائمة منسَّقة بجميع المجالات.
ما يجب مراقبته:
في واجهة مستخدم "حزمة تطوير التطبيقات على Android"، وسِّع تفاصيل التنفيذ للاطّلاع على ما يلي:
- قرار اختيار الوكيل
- استدعاء الأداة:
get_industries() - نتائج أولية من Neo4j
- الردّ المنسَّق
طلب البحث 2: العثور على مستثمرين
Who invested in ByteDance?
السلوك المتوقّع:
- يحدّد Root Agent هذا الطلب على أنّه طلب ذو صلة بالمستثمرين
- طُرق الوصول إلى "وكيل البحث عن المستثمرين"
- الأداة المستخدَمة:
find_investor_by_name("ByteDance") - تعرض هذه الطريقة المستثمرين مع أنواعهم (شخص/مؤسسة)
التوقّعات:
- قائمة بالمستثمرين المرتبطين بشركة ByteDance
- يتم عرض اسم كل مستثمر ونوع الجهة (شخص أو مؤسسة).
- ملخّص موجز للنتائج يمكن لشخص عادي قراءته
- طلب متابعة يقترح استكشاف استثمارات أو محافظ مستثمرين ذات صلة (قد يكون)
طلب البحث 3: الشركات حسب المجال
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: 2023month: 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 46,088 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 وتنسيقه
التوقّعات:
- قائمة بالمستثمرين الذين استثمروا في شركة ByteDance
- لكل مستثمر:
- اسمهم ونوع الكيان (شخص أو مؤسسة)
- قائمة بالشركات الأخرى التي استثمرت فيها، استنادًا إلى البيانات المتاحة
- ملخّص منظَّم وسهل القراءة ومجمَّع حسب المستثمر
ما يجب مراقبته:
- استدعاء أدوات متعددة بالتسلسل
- الحفاظ على السياق بين الخطوات
- نتائج مجمّعة بذكاء
طلب البحث 7: البحث في عدة نطاقات
What are 5 AI companies mentioned in positive articles, and who are their CEOs?
السلوك المتوقّع:
يتطلّب هذا الاستعلام المعقّد عدة وكلاء وأدوات:
- الخطوة 1: وكيل أبحاث الاستثمار
get_companies_in_industry("Artificial Intelligence")- عرض قائمة بشركات الذكاء الاصطناعي
- الخطوة 2: وكيل أبحاث الاستثمار
get_articles_with_sentiment(0.8)- عرض مقالات إيجابية
- الخطوة 3: فلاتر Root Agent
- تحديد شركات الذكاء الاصطناعي التي تظهر في مقالات إيجابية
- اختيار أبرز 5
- الخطوة 4: Investment Research Agent
get_people_in_organizations([company_names], "CEO")- عرض معلومات الرئيس التنفيذي
- الخطوة 5: ينسّق Root Agent الردّ
التوقّعات:
- قائمة بخمس شركات في مجال الذكاء الاصطناعي
- الشركات التي تظهر في المقالات التي حصلت على تقييم إيجابي فقط
- لكل شركة:
- اسم الشركة
- صناعية
- اسم الرئيس التنفيذي
- نتيجة مجمّعة أو تمثيلية للانطباع
ما يجب مراقبته:
- استدعاء أدوات متعددة من خلال وكلاء مختلفين
- فلترة البيانات ومنطق الدمج
طلب البحث 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 وكل منافس، يمكنك العثور على المستثمرين
- تحديد المستثمرين الذين يظهرون في شركات متعددة
التوقّعات:
- يستخدم النظام سياق المحادثة الحالي (YouTube والمنافسون)
- قائمة بالمستثمرين الذين استثمروا في أكثر من شركة واحدة ضمن هذه البيئة التنافسية
- لكل مستثمر:
- اسم المستثمر
- قائمة مجمّعة بالشركات ذات الصلة التي استثمروا فيها
- ملخّص تفسيري قصير يسلّط الضوء على التداخل أو الأنماط الاستراتيجية (ربما)
طلب البحث 10: ملخّص البحث
Summarize our research findings so far
السلوك المتوقّع:
- يراجع Root Agent سجلّ المحادثات
- تجميع النتائج الرئيسية من طلبات البحث السابقة
- تقديم ملخّص متماسك
التوقّعات:
- ملخّص موجز ومنظّم بشكل جيد للأفكار التي تم جمعها من طلبات البحث السابقة
- النتائج الرئيسية مجمّعة حسب المواضيع (نظرة عامة على المجال، وتحليل الشركة، والمشاعر، والمنافسة، والقيادة)
- نقاط تعداد واضحة تبرز ما يلي:
- المجالات التي تم استكشافها
- الشركات والمستثمرون البارزون
- أنماط الاستثمار بين الشركات
- مؤشرات معنويات السوق
- سرد متّسق يعكس التجميع المراعي للسياق على مستوى الجلسة
فهم تفاعلات الوكيل في "طريقة العرض المخصّصة لتصحيح الأخطاء"
توفّر واجهة الويب الخاصة بـ 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.
🚀 هل أنت مستعد لإنشاء نظام وكيل ذكي جديد؟