1. Visão Geral do Projeto¶
O que é o iFriend Agents?¶
O iFriend Agents é um bot de atendimento inteligente para o setor de turismo. Ele permite que viajantes, agências e operadoras de turismo conversem por linguagem natural para:
- Buscar experiências turísticas, guias e passeios
- Solicitar orçamentos com preços, disponibilidade e câmbio
- Realizar reservas completas (dados do viajante, emissão)
- Efetuar pagamentos (tokenização de cartão, processamento)
- Enviar e-mails de confirmação
Tudo isso funciona em múltiplas plataformas: Slack, WhatsApp (Evolution API e Official API), Telegram, WebChat e SSE (Server-Sent Events).
Stack Tecnológica¶
┌─────────────────────────────────────────────────┐
│ Linguagem │
│ Python 3.11 │
├─────────────────────────────────────────────────┤
│ Framework de IA │
│ Google ADK (Agent Dev Kit) │
│ Modelo: Gemini 2.5 Flash │
├─────────────────────────────────────────────────┤
│ Framework Web │
│ FastAPI + Uvicorn (ASGI) │
├─────────────────────────────────────────────────┤
│ Infraestrutura │
│ GCP: Cloud Run · Cloud SQL (MySQL) · Redis │
│ BigQuery · Secret Manager · Vertex AI │
├─────────────────────────────────────────────────┤
│ Containerização │
│ Docker · Cloud Build │
└─────────────────────────────────────────────────┘
Estrutura de Pastas¶
ifriend-agents/
│
├── unified_bot.py ← Entry point FastAPI (todas as routes)
├── AGENTS.md ← Documentação técnica da arquitetura multi-agent
│
├── ifriend_agent/ ← Core do agente de IA
│ ├── agent.py ← Ponto de entrada (chama AgentBuilder.build())
│ ├── agent_builder.py ← Composição dinâmica do root_agent com feature flags
│ ├── agents/ ← Sub-agentes especializados:
│ │ ├── discovery_agent ← Busca de produtos (6 tools)
│ │ ├── quote_agent ← Cotação e preços (4 tools)
│ │ ├── booking_agent ← Reservas (8 tools, condicional)
│ │ ├── payment_agent ← Pagamentos (3 tools, condicional)
│ │ ├── utils_agent ← Email e CSV (2 tools)
│ │ ├── support_agent ← Atendimento humano (0 tools)
│ │ ├── research_agent ← Pesquisa web — AgentTool (1 tool)
│ │ └── faq_agent ← FAQ da plataforma — AgentTool
│ ├── prompts/ ← Prompt dinâmico do orquestrador
│ │ └── orchestrator_prompt.py ← build_orchestrator_instruction()
│ ├── tools/ ← 24 tools do ADK (uma por arquivo)
│ │ ├── client/ ← HTTP client centralizado (retry, circuit breaker)
│ │ ├── context/ ← Enriquecimento de contexto (headers, preços, whitelabel)
│ │ ├── blocks/ ← Generative UI blocks (experience_cards, guide_cards)
│ │ └── providers/ ← Integrações externas (Tiqets)
│ ├── callbacks/ ← Hooks before/after do agente (JWT, memória)
│ ├── config/ ← Configurações:
│ │ ├── app_config.py ← Cache de contexto + compactação de eventos
│ │ ├── feature_flags.py ← Feature flags (ENABLE_BOOKING, ENABLE_PAYMENT)
│ │ └── llm_config.py ← Parâmetros LLM + retry automático
│ ├── session/ ← Session services (Redis, CloudSQL, JWT)
│ ├── memory/ ← Memory services (CloudSQL com FULLTEXT search)
│ ├── infra/ ← Schema SQL, migrations, K8s
│ ├── evaluations/ ← Testes de qualidade do agente
│ └── tests/ ← Testes unitários (200+ testes)
│
├── messaging/ ← Framework de mensageria multi-plataforma
│ ├── base.py ← Interface abstrata (MessagingAdapter)
│ ├── factory.py ← AdapterFactory (registro e resolução)
│ ├── processor.py ← ConversationProcessor (orquestra o fluxo)
│ ├── whitelabel.py ← Detecção whitelabel via Origin/Referer
│ ├── adapters/ ← Implementações: Slack, WhatsApp, Telegram, etc.
│ └── sse/ ← Stream Manager para Server-Sent Events
│
├── carrani_agent/ ← Agente separado (catálogo Carrani Tours)
├── tests/ ← Testes de integração e E2E
├── docs/ ← Documentação do projeto
├── examples/ ← Exemplos HTML de chat
├── scripts/ ← Scripts utilitários
│
├── Dockerfile ← Build da imagem Docker
├── docker-compose.yml ← PostgreSQL + OpenMemory (dev local)
├── cloudbuild.yaml ← Pipeline CI/CD para Cloud Run
├── requirements-dev.txt ← Dependências de desenvolvimento
└── requirements-messaging.txt← Dependências de mensageria
Conceitos-chave que você precisa saber¶
| Conceito | O que é | Onde fica |
|---|---|---|
| ADK | Google Agent Development Kit — framework para criar agentes de IA com tools, prompts e callbacks | ifriend_agent/agent.py + agent_builder.py |
| Tool | Função Python decorada que o agente pode chamar (ex: buscar produto, emitir reserva) | ifriend_agent/tools/ |
| Callback | Hook que roda antes/depois do agente processar (ex: injetar JWT, salvar memória) | ifriend_agent/callbacks/ |
| Adapter | Classe que traduz mensagens de uma plataforma (Slack, WhatsApp...) para formato interno | messaging/adapters/ |
| Processor | Orquestrador que conecta adapter → session → agente ADK → resposta | messaging/processor.py |
| Session | Estado da conversa de um usuário (histórico, contexto JWT, metadata) | ifriend_agent/session/ |
| Memory | Memória de longo prazo do usuário (persiste entre sessões) | ifriend_agent/memory/ |
Versão atual¶
A versão atual do projeto está no arquivo VERSION na raiz: v2.5.0
Próximo: Arquitetura e Fluxo de Dados →