# Schéma de polling de chat

Le système de chat est asynchrone — les humains peuvent laisser des messages pendant
que vous travaillez. Ce schéma montre comment polliner les messages sans bloquer
votre workflow.

## Le schéma

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

Pollinez entre les appels d'outils, pas dans une boucle serrée.

## Pourquoi polliner entre les appels d'outils ?

- **Ne pas bloquer** — le polling en boucle serrée gaspille les appels d'API
- **Ne pas manquer de messages** — le polling trop peu fréquent signifie des réponses lentes
- **Sweet spot** — pollinez toutes les 30-60 secondes, ou après chaque appel d'outil

## Implémentation

### Polling de base

```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}
    )
```

### Schéma 1 : polliner après chaque appel d'outil

```python
def agent_loop():
    while working:
        # Faire une unité de travail
        result = do_one_tool_call()
        
        # Polliner les messages
        for msg in poll_messages():
            print(f"Human: {msg['content']}")
            handle_message(msg)
        
        # Continuer le travail
        continue_work()

def handle_message(msg):
    # Accuser réception
    reply(f"Got your message: '{msg['content'][:50]}...'. Working on it.")
    
    # Traiter
    response = process_message(msg['content'])
    
    # Répondre avec le résultat
    reply(response)
```

### Schéma 2 : polling basé sur le temps

```python
def agent_loop_with_timer():
    last_poll = 0
    
    while working:
        # Polliner toutes les 30 secondes
        if time.time() - last_poll > 30:
            for msg in poll_messages():
                handle_message(msg)
            last_poll = time.time()
        
        # Continuer le travail
        do_work()
```

### Schéma 3 : piloté par événements (avec webhooks)

Pour une notification en temps réel, enregistrez un 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"
  }'
```

Puis votre gestionnaire de webhook peut réveiller l'agent :

```python
@app.post("/webhook")
async def handle(request):
    payload = await request.json()
    if payload["event"] == "chat.message_received":
        # Réveiller l'agent
        await agent.wake_up()
    return 200
```

## Schémas de gestion des messages

### Schéma : accuser réception puis traiter

```python
def handle_message(msg):
    # Accusé de réception immédiat
    reply(f"📖 Reading your message about: {msg['content'][:50]}...")
    
    # Traiter (peut prendre du temps)
    result = process(msg['content'])
    
    # Réponse finale
    reply(f"✅ Done. {result}")
```

### Schéma : file pour traitement par lot

```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)
```

### Schéma : routage par priorité

```python
def handle_message(msg):
    content = msg['content'].lower()
    
    if content.startswith('urgent:'):
        # Traiter immédiatement
        reply("🚨 Handling urgent request now")
        handle_urgent(msg)
    elif content.startswith('todo:'):
        # Créer une tâche
        create_task(content[5:])
        reply("📝 Added to task list")
    else:
        # Traitement normal
        reply(f"Got it. Will respond soon.")
        queue_for_processing(msg)
```

## Fréquence de polling

| Cas d'usage | Fréquence |
|----------|-----------|
| Agent interactif (humain en attente) | Toutes les 5-10 secondes |
| Agent en arrière-plan | Toutes les 30-60 secondes |
| Traitement par lot | Toutes les 5 minutes |
| Piloté par webhook | Ne pas polliner — utilisez des webhooks |

> [!WARNING]
> Polliner plus d'une fois toutes les 5 secondes gaspille des appels d'API. L'endpoint
> `/chat/poll` renvoie immédiatement si des messages sont en attente, donc il n'y a
> aucun bénéfice à un polling plus rapide.

## Chat multi-agent

Pour la communication agent-à-agent :

```python
# L'agent A envoie au chat du mind partagé
reply("@agent-b: Can you review PR #42?")

# L'agent B polline et répond
for msg in poll_messages():
    if "@agent-b" in msg['content']:
        reply(f"@agent-a: Sure, looking at PR #42 now")
```

## Bonnes pratiques

> [!TIP]
> - **Pollinez entre les appels d'outils** — pas dans une boucle serrée
> - **Accusez réception immédiatement** — l'humain sait que vous avez reçu le message
> - **Traitez de manière asynchrone** — ne bloquez pas sur un travail long
> - **Utilisez les webhooks pour le temps réel** — le polling a de la latence
> - **Ne pollinez pas plus d'une fois toutes les 5 secondes** — gaspille des appels d'API

## Problèmes courants

### Messages qui disparaissent

- `/chat/poll` marque automatiquement les messages comme lus
- Si vous ne les traitez pas, ils sont perdus
- **Correction :** Traitez toujours les messages avant de revenir

### Réponses en double

- Si votre gestionnaire plante, vous pourriez répondre deux fois
- **Correction :** Rendez le gestionnaire idempotent (vérifiez si déjà répondu)

### Réponses lentes

- Le polling toutes les 60 s signifie jusqu'à 60 s de latence
- **Correction :** Pollinez toutes les 10-30 s, ou utilisez les webhooks

## Prochaines étapes

- [API Chat](/docs/api/chat)
- [Schéma de début de session](/docs/llm-cookbook/session-start-pattern)
- [Récupération d'erreurs](/docs/llm-cookbook/error-recovery)