Visão Geral da Arquitetura¶

O que é o iFriend Agents?¶

Plataforma de atendimento automatizado para turismo que utiliza múltiplos agentes de IA especializados, coordinados por um orquestrador central.

Componentes Principais¶

1. Orquestrador (`root_agent`)¶

O root_agent é o cérebro da operação. Ele: - Recebe todas as mensagens primeiro - Decide qual sub-agent deve tratar a requisição - Mantém o contexto da conversa - Gerencia transferência entre agentes

Arquivo: ifriend_agent/agent.py

2. Sub-Agentes¶

Cada sub-agente é especializado em um domínio:

Agente	Domínio	Ferramentas
`discovery_agent`	Busca de experiências	6 tools
`itinerary_agent`	Roteiros multi-destino	5 tools
`quote_agent`	Cotação de preços	4 tools
`booking_agent`	Reservas	8 tools
`payment_agent`	Pagamentos	3 tools
`support_agent`	Atendimento humano	0 tools
`custom_tour_agent`	Tours personalizados	2 tools

3. Messaging Layer¶

Responsável por receber e enviar mensagens em diferentes canais.

Arquivos: - messaging/processor.py — Processador principal - messaging/adapters/* — Adaptadores por canal - messaging/loop_guard.py — Proteção anti-loop

4. Session & Memory¶

Session — Contexto da conversa atual (CloudSQL)
Memory — Histórico entre sessões (CloudSQL)

Fluxo de uma Mensagem¶

1. Usuário envia mensagem (WhatsApp/Webchat/Telegram)
           ↓
2. Adapter converte para IncomingMessage
           ↓
3. LoopGuard verifica se é mensagem válida
           ↓
4. SessionService carrega contexto anterior
           ↓
5. PreloadMemoryTool carrega memórias relevantes
           ↓
6. Root agent processa com callbacks
           ↓
7. Sub-agent é invoked conforme intent
           ↓
8. Ferramentas são chamadas conforme necessidade
           ↓
9. Resposta é convertida para OutgoingMessage
           ↓
10. Adapter envia para o canal original

Segurança¶

JWT Authentication — Todas as requisições via API
PII Sanitization — Dados sensíveis são filtrados das tools
Role-based Access — Diferentes roles para diferentes funcionalidades

Scaling¶

O projeto pode escalar horizontalmente: - Múltiplas instâncias do FastAPI - Redis para session cache - CloudSQL para persistência - Load balancer para distribuir requisições