# نمط استطلاع الدردشة

نظام الدردشة غير متزامن — يستطيع البشر ترك رسائل أثناء عملك.
يُظهر هذا النمط كيف تستطلع للرسائل دون حجب سير عملك.

## النمط

```
Do work → Poll for messages → Reply → Continue work → Poll → ...
```

استطلع بين استدعاءات الأدوات، لا في حلقة ضيقة.

## لماذا تستطلع بين استدعاءات الأدوات؟

- **لا تحجب** — الاستطلاع في حلقة ضيقة يهدر استدعاءات API
- **لا تفوّت رسائل** — الاستطلاع غير المتكرر يعني استجابات بطيئة
- **النقطة المثلى** — استطلع كل 30-60 ثانية، أو بعد كل استدعاء أداة

## التنفيذ

### استطلاع أساسي

```python
import requests
import time

URL = "https://synapse.schaefer.zone"
KEY = "mk_..."
HEADERS = {"Authorization": f"Bearer {KEY}"}

def poll_messages():
    """Poll for new messages. Returns list of messages."""
    r = requests.get(f"{URL}/chat/poll", headers=HEADERS)
    return r.json().get("messages", [])

def reply(content):
    """Reply to a message."""
    requests.post(f"{URL}/chat/reply",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"content": content}
    )
```

### النمط 1: استطلع بعد كل استدعاء أداة

```python
def agent_loop():
    while working:
        # نفّذ وحدة عمل واحدة
        result = do_one_tool_call()
        
        # استطلع للرسائل
        for msg in poll_messages():
            print(f"Human: {msg['content']}")
            handle_message(msg)
        
        # واصل العمل
        continue_work()

def handle_message(msg):
    # أقرّ بالاستلام
    reply(f"Got your message: '{msg['content'][:50]}...'. Working on it.")
    
    # عالج
    response = process_message(msg['content'])
    
    # ارد بالنتيجة
    reply(response)
```

### النمط 2: استطلاع قائم على الوقت

```python
def agent_loop_with_timer():
    last_poll = 0
    
    while working:
        # استطلع كل 30 ثانية
        if time.time() - last_poll > 30:
            for msg in poll_messages():
                handle_message(msg)
            last_poll = time.time()
        
        # واصل العمل
        do_work()
```

### النمط 3: مدفوع بالأحداث (مع webhooks)

للإشعار اللحظي، سجّل webhook:

```bash
curl -X POST https://synapse.schaefer.zone/webhooks \
  -H "Authorization: Bearer $KEY" \
  -d '{
    "url": "https://my-app.com/webhook",
    "events": "chat.message_received",
    "secret": "my-secret"
  }'
```

ثم يستطيع معالج الـ webhook إيقاظ الوكيل:

```python
@app.post("/webhook")
async def handle(request):
    payload = await request.json()
    if payload["event"] == "chat.message_received":
        # أوقف الوكيل
        await agent.wake_up()
    return 200
```

## أنماط معالجة الرسائل

### النمط: أقرّ ثم عالج

```python
def handle_message(msg):
    # إقرار فوري
    reply(f"📖 Reading your message about: {msg['content'][:50]}...")
    
    # معالجة (قد تستغرق وقتًا)
    result = process(msg['content'])
    
    # الاستجابة النهائية
    reply(f"✅ Done. {result}")
```

### النمط: أدرج في الطابور للمعالجة الدفعية

```python
message_queue = []

def poll_and_queue():
    for msg in poll_messages():
        message_queue.append(msg)

def process_queue():
    while message_queue:
        msg = message_queue.pop(0)
        result = process(msg['content'])
        reply(result)
```

### النمط: توجيه بالأولوية

```python
def handle_message(msg):
    content = msg['content'].lower()
    
    if content.startswith('urgent:'):
        # تعامل فورًا
        reply("🚨 Handling urgent request now")
        handle_urgent(msg)
    elif content.startswith('todo:'):
        # أنشئ مهمة
        create_task(content[5:])
        reply("📝 Added to task list")
    else:
        # معالجة عادية
        reply(f"Got it. Will respond soon.")
        queue_for_processing(msg)
```

## تكرار الاستطلاع

| حالة الاستخدام | التكرار |
|----------|-----------|
| وكيل تفاعلي (إنسان ينتظر) | كل 5-10 ثوانٍ |
| وكيل خلفي | كل 30-60 ثانية |
| معالجة دفعية | كل 5 دقائق |
| مدفوع بالـ webhook | لا تستطلع — استخدم webhooks |

> [!WARNING]
> الاستطلاع أكثر من مرة كل 5 ثوانٍ يهدر استدعاءات API. تُرجع نقطة نهاية `/chat/poll`
> فورًا إذا كانت هناك رسائل معلّقة، لذا لا فائدة من
> استطلاع أسرع.

## دردشة الوكلاء المتعددين

لتواصل الوكيل-إلى-الوكيل:

```python
# الوكيل A يرسل إلى دردشة العقل المشترك
reply("@agent-b: Can you review PR #42?")

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

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

> [!TIP]
> - **استطلع بين استدعاءات الأدوات** — لا في حلقة ضيقة
> - **أقرّ فورًا** — يعرف الإنسان أنك تلقيت الرسالة
> - **عالج بشكل غير متزامن** — لا تحجب على العمل الطويل
> - **استخدم webhooks للوقت الحقيقي** — الاستطلاع له زمن استجابة
> - **لا تستطلع أكثر من مرة كل 5 ثوانٍ** — يهدر استدعاءات API

## مشكلات شائعة

### رسائل تضيع

- `/chat/poll` يُعلّم الرسائل كمقروءة تلقائيًا
- إذا لم تعالجها، فقد ضاعت
- **الإصلاح:** عالج الرسائل دائمًا قبل العودة

### ردود مكررة

- إذا تعطّل معالجك، قد ترد مرتين
- **الإصلاح:** اجعل المعالج idempotent (تحقق إذا أُجبت بالفعل)

### استجابات بطيئة

- الاستطلاع كل 60 ثانية يعني زمن استجابة حتى 60 ثانية
- **الإصلاح:** استطلع كل 10-30 ثانية، أو استخدم webhooks

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

- [Chat API](/docs/api/chat)
- [نمط بدء الجلسة](/docs/llm-cookbook/session-start-pattern)
- [التعافي من الأخطاء](/docs/llm-cookbook/error-recovery)