# تنسيق الوكلاء المتعددين

عندما لديك عدة وكلاء LLM يعملون على مهام ذات صلة، يوفّر Synapse
طبقة التنسيق — الذاكرة المشتركة، إسناد المهام، والدردشة غير المتزامنة.

## الأنماط

### النمط 1: العقل المشترك (مصدر واحد للحقيقة)

جميع الوكلاء يشاركون Mind Key واحد. يقرؤون/يكتبون نفس مخزن الذاكرة.

```
┌──────────┐  ┌──────────┐  ┌──────────┐
│ Agent A  │  │ Agent B  │  │ Agent C  │
└────┬─────┘  └────┬─────┘  └────┬─────┘
     │             │             │
     └─────────────┼─────────────┘
                   ▼
           ┌──────────────┐
           │ Shared Mind  │
           │  (one key)   │
           └──────────────┘
```

**حالة الاستخدام:** فريق صغير من الوكلاء يعملون على مشروع واحد.

**الإعداد:**

```bash
# جميع الوكلاء يستخدمون نفس Mind Key
export SYNAPSE_MIND_KEY=mk_shared_key...
```

**التنسيق عبر المهام:**

```python
# الوكيل A ينشئ مهمة
create_task("Review PR #42", priority="high")

# الوكيل B يلتقطها
tasks = list_tasks(status="pending")
if tasks:
    task = tasks[0]
    update_task(task["id"], status="in_progress")
    # ... نفّذ العمل ...
    update_task(task["id"], status="done")
```

### النمط 2: عقول متخصصة (سياقات معزولة)

كل وكيل له عقله الخاص. يتواصلون عبر عقل "تنسيق" مشترك.

```
┌──────────┐  ┌──────────┐  ┌──────────┐
│ Coder    │  │ Reviewer │  │ Deployer │
│ Agent    │  │ Agent    │  │ Agent    │
└────┬─────┘  └────┬─────┘  └────┬─────┘
     │             │             │
     ▼             ▼             ▼
┌─────────┐  ┌─────────┐  ┌─────────┐
│ Mind C  │  │ Mind R  │  │ Mind D  │
└─────────┘  └─────────┘  └─────────┘
     │             │             │
     └─────────────┼─────────────┘
                   ▼
           ┌──────────────────┐
           │ Coordination Mind│
           │ (shared)         │
           └──────────────────┘
```

**حالة الاستخدام:** وكلاء بتخصصات مختلفة (برمجة، مراجعة، نشر).

**الإعداد:**

```bash
# وكيل البرمجة
SYNAPSE_MIND_KEY=mk_coder... MCP_TRANSPORT=stdio npx synapse-mcp-api@latest

# وكيل المراجعة
SYNAPSE_MIND_KEY=mk_reviewer... MCP_TRANSPORT=stdio npx synapse-mcp-api@latest

# وكيل النشر
SYNAPSE_MIND_KEY=mk_deployer... MCP_TRANSPORT=stdio npx synapse-mcp-api@latest
```

**التنسيق عبر العقل المشترك:**

```python
# المبرمج يخزّن "جاهز للمراجعة"
COORDINATION_KEY = "mk_coordination..."
requests.post(f"{URL}/memory",
    headers={"Authorization": f"Bearer {COORDINATION_KEY}"},
    json={
        "category": "project",
        "key": "pr_42_ready",
        "content": "PR #42 is ready for review. Branch: feature/docs-system",
        "tags": ["review", "pr-42"],
        "priority": "high"
    })

# المراجع يستطلع طلبات المراجعة
r = requests.get(f"{URL}/memory/search?q=ready+for+review",
    headers={"Authorization": f"Bearer {COORDINATION_KEY}"})
```

### النمط 3: المحور والأقطاب (المنسّق)

وكيل منسّق مركزي يُسند المهام لوكلاء العمل.

```
        ┌──────────────┐
        │ Orchestrator │
        │    Agent     │
        └──────┬───────┘
               │
    ┌──────────┼──────────┐
    ▼          ▼          ▼
┌──────┐  ┌──────┐  ┌──────┐
│Worker│  │Worker│  │Worker│
│  A   │  │  B   │  │  C   │
└──────┘  └──────┘  └──────┘
```

**حالة الاستخدام:** سير عمل معقد بعمل متوازٍ.

**التنفيذ:**

```python
# المنسّق
class Orchestrator:
    def assign_task(self, worker_id, task_description):
        # خزّن المهمة في عقل العامل (أو عقل التنسيق المشترك)
        create_task(task_description, priority="high")
        # أبلغ العامل عبر الدردشة
        reply(f"@{worker_id}: New task — {task_description}")
    
    def check_progress(self):
        tasks = list_tasks(status="in_progress")
        for t in tasks:
            print(f"{t['title']}: {t['status']}")

# العمال يستطلعون المهام المُسندة
class Worker:
    def run(self):
        while True:
            tasks = list_tasks(status="pending")
            for t in tasks:
                if assigned_to_me(t):
                    update_task(t["id"], status="in_progress")
                    result = do_work(t)
                    update_task(t["id"], status="done")
                    reply(f"Completed: {t['title']}")
            time.sleep(60)
```

## التنسيق عبر الدردشة

يستطيع الوكلاء التواصل عبر نظام الدردشة:

```python
# الوكيل A يرسل إلى الوكيل B
reply("@agent-b: Can you review my PR?")

# الوكيل B يستطلع ويرد
for msg in poll_messages():
    if "@agent-b" in msg["content"]:
        reply(f"@agent-a: Sure, looking at it now.")
```

> [!NOTE]
> رسائل الدردشة موسومة بالدور. عيّن role=agent لرسائل الوكيل-إلى-الوكيل،
> role=human للإنسان-إلى-الوكيل.

## التنسيق عبر المتغيرات

استخدم المتغيرات للتنسيق الخفيف (أقفال، أعلام):

```python
# الحصول على قفل
def acquire_lock(name):
    r = requests.post(f"{URL}/var",
        headers={"Authorization": f"Bearer {KEY}"},
        json={"key": f"lock_{name}", "value": "acquired"})
    return True

def release_lock(name):
    requests.delete(f"{URL}/var/lock_{name}",
        headers={"Authorization": f"Bearer {KEY}"})

# الاستخدام
if acquire_lock("deploy"):
    try:
        deploy_to_production()
    finally:
        release_lock("deploy")
```

## أفضل الممارسات

> [!TIP]
> - **استخدم عقولًا منفصلة للاهتمامات المنفصلة** — لا تخلط ذاكرة المبرمج والمراجع
> - **وسم الوكلاء في الدردشة** — `@agent-name` لعنوان واضح
> - **استخدم المهام لإسناد العمل** — لا الدردشة (الدردشة للنقاش)
> - **نفّذ الـ idempotency** — قد يعيد الوكلاء محاولة العمليات الفاشلة
> - **سجّل كل شيء** — خزّن القرارات في الذاكرة للقابلية للتدقيق

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

- [وكيل LLM الدائم](/docs/guides/persistent-llm-agent)
- [كتاب طبخ LLM](/docs/llm-cookbook/session-start-pattern)
- [أتمتة الـ Webhooks](/docs/guides/webhook-automation)