Fluxo de Mensagens¶

Arquitetura de Messaging¶

┌─────────────────────────────────────────────────────────────┐
│                    unified_bot.py                          │
│                    (FastAPI app)                           │
└─────────────────────────────────────────────────────────────┘
                              │
         ┌────────────────────┼────────────────────┐
         │                    │                    │
         ▼                    ▼                    ▼
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│ WhatsApp    │      │ Webchat     │      │ Telegram    │
│ Adapter     │      │ Adapter     │      │ Adapter     │
└─────────────┘      └─────────────┘      └─────────────┘
         │                    │                    │
         └────────────────────┼────────────────────┘
                              │
                              ▼
                 ┌─────────────────────┐
                 │  Adapter Factory   │
                 │ (messaging/factory)│
                 └──────────┬──────────┘
                            │
                            ▼
                 ┌─────────────────────┐
                 │ConversationProcessor│
                 │ (messaging/processor)│
                 └──────────┬──────────┘
                            │
                            ▼
                 ┌─────────────────────┐
                 │   LoopGuard         │
                 │ (anti-loop bot)     │
                 └──────────┬──────────┘
                            │
                            ▼
                 ┌─────────────────────┐
                 │   Session Service  │
                 │ + Memory Service   │
                 └──────────┬──────────┘
                            │
                            ▼
                 ┌─────────────────────┐
                 │   ADK Runner        │
                 │  (root_agent)       │
                 └─────────────────────┘

Loop Guard¶

Proteção contra loops infinitos quando outro agente IA conversa com a iFriend.

4 Camadas de Proteção¶

Camada	Nome	Trigger	Ação
1	Message ID Dedup	`message_id` duplicado	Ignora silenciosamente
2	Circuit Breaker	>5 msgs em 10s	Cooldown de 30s
3	Repetição Textual	≥3 msgs idênticas	Trip circuit breaker
4	Hard Turn Limit	>200 turnos/sessão	Escala para humano

Adapters¶

Cada adapter implementa a interface MessagingAdapter:

class MessagingAdapter(ABC):
    @abstractmethod
    async def setup(self): ...

    @abstractmethod
    async def send_message(self, message: OutgoingMessage): ...

    @abstractmethod
    async def send_text(self, phone: str, text: str): ...

    @abstractmethod
    async def send_image(self, phone: str, image_url: str, caption: str): ...

Adapters Disponíveis¶

whatsapp_official_adapter.py — WhatsApp Official API
whatsapp_evolution_adapter.py — Evolution API
webchat_adapter.py — Webchat HTTP
telegram_adapter.py — Telegram Bot API
slack_adapter.py — Slack
sse_adapter.py — Server-Sent Events