Milestone Q1 2026 — iFriend AI Agent Platform

Período: Janeiro – Abril 2026
Release Final: 3.1.0
Versões entregues: 2.0.0 → 3.1.0 (31 releases)
Responsável: Glauber Portella

---

Sumário Executivo

No primeiro trimestre de 2026, a plataforma de agentes inteligentes da iFriend evoluiu de um bot Slack monolítico (v1.0) para uma plataforma multi-agente, multi-canal e multi-tenant, rodando em produção no Google Cloud Run com cobertura de 682 testes automatizados.

As entregas abrangeram 4 pilares estratégicos: arquitetura multi-agente, integração multi-canal, segurança (JWT) e experiência do usuário (Generative UI). O resultado é uma plataforma capaz de operar em 6 canais simultâneos, com 10 agentes especializados e 25+ tools, suportando whitelabel e escalável para novos mercados.

---

Indicadores do Trimestre

Métrica	Valor
Releases entregues	31 (2.0.0 → 3.1.0)
Commits (Q1)	233
Linhas de código Python	~26.500
Linhas adicionadas (delta)	+55.172
Arquivos modificados	281
Testes automatizados	682 (42 arquivos)
Agentes IA especializados	10 + 1 orquestrador
Tools de domínio	25
Canais de atendimento	6 (Slack, WhatsApp Evolution, WhatsApp Official, Telegram, WebChat, SSE)
Documentação técnica	117 arquivos (~45.600 linhas)

---

Timeline de Releases

gantt
    title Releases iFriend Agent — Q1 2026
    dateFormat YYYY-MM-DD
    axisFormat %d/%m

    section Janeiro
    v2.0.0 Multi-Platform         :milestone, m1, 2026-01-03, 0d
    v2.1.0 Email + Booking        :milestone, m2, 2026-01-04, 0d

    section Fevereiro
    v2.2.0 SSE + Search + Telegram :milestone, m3, 2026-01-31, 0d
    v2.3.0 JWT + OpenWebUI        :milestone, m4, 2026-02-24, 0d
    v2.4.0 SendGrid + CORS        :milestone, m5, 2026-02-26, 0d

    section Março
    v2.5.0 Whitelabel + Temporal  :milestone, m6, 2026-03-11, 0d
    v3.0.0 Multi-Agent Architecture :milestone, m7, 2026-03-30, 0d

    section Abril
    v3.0.11 Discovery + Itinerary :milestone, m8, 2026-04-01, 0d
    v3.1.0 Custom Tour + Perf     :milestone, m9, 2026-04-06, 0d

---

Entregas por Release

v2.0.0 — Multi-Platform Messaging Framework (03/Jan)

Refatoração completa do bot monolítico Slack para uma arquitetura extensível multi-canal.

graph LR
    subgraph "v1.0 (Antes)"
        A[slack_bot.py<br/>Monolítico] --> B[ADK Runner]
    end

    subgraph "v2.0 (Depois)"
        C[unified_bot.py] --> D[AdapterFactory]
        D --> E[SlackAdapter]
        D --> F[WhatsAppAdapter]
        D --> G[TelegramAdapter]
        D --> H[WebChatAdapter]
        D --> I[SSEAdapter]
        E & F & G & H & I --> J[ConversationProcessor]
        J --> K[ADK Runner]
    end

    style A fill:#ff6b6b,color:#fff
    style C fill:#51cf66,color:#fff

Entregas: - Framework de messaging extensível (messaging/) com padrão Strategy - AdapterFactory com auto-detecção de plataformas via env vars - ConversationProcessor agnóstico de plataforma - DTO universal: IncomingMessage / OutgoingMessage - Webhook unificado (/webhook/*) com roteamento automático - Adaptadores: Slack (produção), WhatsApp Evolution API, Telegram

---

v2.1.0 — Email, Booking e Avaliação (04/Jan)

• Ferramenta de envio de email via Gmail SMTP e Gmail API (OAuth 2.0)
• MailerSend como provedor alternativo de email
• Tools de booking para agências (buscar_agencia, emitir_reserva)
• Link de voucher e pagamento em obter_reserva
• Plano de avaliação de agentes com evaluation tests
• Ajustes de top_p, top_k, max_output_tokens

---

v2.2.0 — SSE Streaming, Search Agent e Telegram (31/Jan)

sequenceDiagram
    participant U as Usuário (Browser)
    participant S as Cloud Run (SSE)
    participant A as Agente IA
    participant T as Tool (ex: busca)

    U->>S: POST /sse/chat
    S-->>U: { stream_id }
    U->>S: GET /sse/stream/{id} (EventSource)
    S->>A: run_async()
    A->>T: busca_produtos()
    S-->>U: event: tool_call_start
    T-->>A: resultados
    S-->>U: event: tool_call_complete
    A-->>S: texto em chunks
    S-->>U: event: text_chunk (1)
    S-->>U: event: text_chunk (2)
    S-->>U: event: complete

Entregas: - SSE (Server-Sent Events) para streaming em tempo real — feedback de tool calls, text chunks progressivos - StreamManager com TTL, cleanup automático e reconexão - Research Agent com Google Search (busca web em tempo real) - Tiqets Integration — tools para produtos de atrações - Adaptador Telegram funcional - WebChat widget HTML de demonstração (sse-chat.html) - Melhorias de prompt para pagamento e variações de preço

---

v2.3.0 — JWT Authentication e OpenWebUI (24/Fev)

Entregas de segurança (JWT em 5 fases):

graph TB
    subgraph "Autenticação JWT"
        A[Fase 1: API Base] --> B[Fase 2: WebChat + JWT]
        B --> C[Fase 3: SSE + JWT]
        C --> D[Fase 4: WhatsApp + JWT]
        D --> E[Fase 5: Documentação + Audit]
    end

    subgraph "Per-Channel JWT Flow"
        F[Header: Authorization Bearer] --> G[JWTContextManager]
        G --> H{Válido?}
        H -->|Sim| I[Injeta jwt_context<br/>no session.state]
        H -->|Não| J[Continua sem JWT]
        I --> K[Tools acessam<br/>user_id, roles, email]
    end

• JWTContextManager — decode, validação e injeção de contexto em todas as plataformas
• SessionContextHelper — persistência de JWT no session.state
• JWT Lookup Service — mapeamento WhatsApp phone → JWT (Redis)
• Security Audit Report completo
• OpenWebUI Integration (5 fases) — API compatível com OpenAI para uso com interface OpenWebUI
• SendGrid como provedor de email (substituindo SMTP direto)
• IFriendAPIClient — client HTTP centralizado com connection pooling
• Enrich de produtos com status de integração de catálogo
• CORS regex para subdomínios (*.theifriend.com)
• Suporte a MySQL local para desenvolvimento

---

v2.4.0 — Refatoração de Tools e CORS (26/Fev)

• Remoção de wrappers FunctionTool desnecessários
• Renomeação padronizada de funções de tools
• Middleware CORS com regex para origens dinâmicas
• Correções de email SendGrid (templates, corpo de mensagem)

---

v2.5.0 — Whitelabel e Lógica Temporal (11/Mar)

graph LR
    subgraph "Whitelabel Detection"
        A[Request HTTP] --> B{Origin Header}
        B -->|quickly.theifriend.com| C[is_whitelabel: true<br/>base_url: quickly...]
        B -->|theifriend.com| D[is_whitelabel: false]
        C --> E[URLs de produto<br/>substituídas pelo<br/>domínio whitelabel]
    end

Entregas: - Whitelabel — detecção automática via Origin/Referer + substituição de URLs de produto - Propagação de message_metadata para session.state (acessível por tools) - Lógica temporal — injeção de current_date, current_year, current_weekday no state - Mudança de persona do orquestrador - Documentação de arquitetura GCP

---

v3.0.0 — Arquitetura Multi-Agent (30/Mar)

A maior entrega do trimestre: refatoração completa de single-agent para arquitetura Coordinator/Dispatcher com 10 agentes especializados.

graph TB
    ROOT["root_agent<br/>(Orquestrador)"]

    ROOT -->|transfer| DISC["discovery_agent<br/>Busca de Produtos<br/>6 tools"]
    ROOT -->|transfer| ITIN["itinerary_agent<br/>Roteiros Multi-Destino<br/>5 tools"]
    ROOT -->|transfer| QUOT["quote_agent<br/>Cotação e Preços<br/>4 tools"]
    ROOT -->|transfer| BOOK["booking_agent<br/>Reservas<br/>8 tools"]
    ROOT -->|transfer| PAY["payment_agent<br/>Pagamentos<br/>3 tools"]
    ROOT -->|transfer| UTIL["utils_agent<br/>Email e CSV<br/>2 tools"]
    ROOT -->|transfer| SUPP["support_agent<br/>Atendimento Humano<br/>1 tool"]
    ROOT -->|transfer| CTOUR["custom_tour_agent<br/>Tours Personalizados<br/>2 tools"]

    ROOT -.->|AgentTool| RES["research_agent<br/>Google Search<br/>1 tool"]
    ROOT -.->|AgentTool| FAQ["faq_agent<br/>FAQ iFriend<br/>0 tools"]

    style ROOT fill:#4263eb,color:#fff,stroke-width:2px
    style DISC fill:#51cf66,color:#fff
    style ITIN fill:#51cf66,color:#fff
    style QUOT fill:#fcc419,color:#333
    style BOOK fill:#ff922b,color:#fff
    style PAY fill:#ff6b6b,color:#fff
    style UTIL fill:#845ef7,color:#fff
    style SUPP fill:#20c997,color:#fff
    style CTOUR fill:#f06595,color:#fff
    style RES fill:#868e96,color:#fff
    style FAQ fill:#868e96,color:#fff

Entregas: - AgentBuilder — composição dinâmica do root_agent com feature flags - Feature Flags — ENABLE_BOOKING, ENABLE_PAYMENT, ENABLE_CUSTOM_TOUR, ENABLE_MEMORY - CloudSQLMemoryService v2 — sumarização LLM (gemini-2.0-flash) + TTL de 15 dias + FULLTEXT search - PreloadMemoryTool — carregamento automático de memórias cross-session - Generative UI — blocks visuais (cards de produto, formulários de suporte) - Support Agent — escalação para WhatsApp com link wa.me + hashtag #agente-ia - Anti-flood / Anti-loop guardrails - Retry automático para 429 RESOURCE_EXHAUSTED - EventsCompactionConfig — compactação de histórico em conversas longas - ContextCacheConfig — cache de static_instruction (economia de tokens) - Regra genérica de transfer-to-root em todos os sub-agentes - Extração de callbacks para módulo dedicado (callbacks/agent_callbacks.py) - Filtro de produtos: apenas salable=true e published=true - ~70% redução de tokens por turno vs single-agent

---

v3.0.1 – v3.0.11 — Estabilização e Discovery Agent (30/Mar – 01/Abr)

• Discovery Agent com fluxo de recomendação inteligente (pre-filtra, rankeia por relevância)
• Experience Cards e Guide Cards — blocks visuais com photo_url, currency_code, first_name
• Itinerary Agent — roteiros multi-destino 100% textuais (suppress_blocks=True)
• Correções de schema, whitelabel URL, currency code
• Email com itinerário integrado

---

v3.1.0 — Custom Tour Agent, Performance e Feature Flags (06/Abr)

Entregas: - Custom Tour Agent — qualificação de leads para tours personalizados com handoff via WhatsApp - Feature Flag ENABLE_ITINERARY — controle de acesso ao itinerary_agent por JWT role - Otimização de performance: static_instruction por agente, model tiers por agente, tuning de cache/compaction - Mudança de persona do orquestrador - Plano de integração Salesforce Einstein Bot ↔ Cloud Run

---

Arquitetura Final (v3.1.0)

graph TB
    subgraph "Canais de Entrada"
        WA[WhatsApp<br/>Evolution API]
        WA2[WhatsApp<br/>Official Meta]
        SL[Slack]
        TG[Telegram]
        WC[WebChat Widget]
        SSE_C[SSE Streaming]
    end

    subgraph "Cloud Run — unified_bot.py"
        WEBHOOK["/webhook/*"]
        WEBCHAT_EP["/webchat/message"]
        SSE_EP["/sse/chat + /sse/stream"]

        WA & WA2 & SL & TG --> WEBHOOK
        WC --> WEBCHAT_EP
        SSE_C --> SSE_EP

        AF[AdapterFactory]
        WEBHOOK --> AF
        AF --> CP[ConversationProcessor]
        WEBCHAT_EP --> CP
        SSE_EP --> SM[StreamManager]
        SM --> CP
    end

    subgraph "Google ADK Runner"
        CP --> RUNNER[Runner]
        RUNNER --> ROOT[root_agent]
        ROOT --> AGENTS["10 sub-agents<br/>25 tools"]
    end

    subgraph "Infra"
        RUNNER --> SESS[(CloudSQL<br/>Sessions)]
        RUNNER --> MEM[(CloudSQL<br/>Memory v2)]
        RUNNER --> REDIS[(Redis<br/>Cache + JWT Lookup)]
    end

    subgraph "Serviços Externos"
        AGENTS --> API[iFriend API]
        AGENTS --> GS[Google Search]
        AGENTS --> SG[SendGrid]
    end

    style ROOT fill:#4263eb,color:#fff
    style RUNNER fill:#4263eb,color:#fff

---

Evolução da Arquitetura no Trimestre

graph LR
    subgraph "v1.0 (Dez/2025)"
        A1[1 Bot Slack<br/>1 Agente<br/>24 Tools<br/>336 linhas prompt]
    end

    subgraph "v2.0 (Jan/2026)"
        A2[Unified Bot<br/>6 Canais<br/>1 Agente<br/>Framework Messaging]
    end

    subgraph "v2.3 (Fev/2026)"
        A3[+ JWT Auth<br/>+ OpenWebUI<br/>+ API Client<br/>+ SendGrid]
    end

    subgraph "v2.5 (Mar/2026)"
        A4[+ Whitelabel<br/>+ Temporal Logic<br/>+ Metadata Propagation]
    end

    subgraph "v3.0 (Mar/2026)"
        A5[Multi-Agent<br/>10 Agentes<br/>25 Tools<br/>Feature Flags<br/>Memory v2<br/>Generative UI]
    end

    subgraph "v3.1 (Abr/2026)"
        A6[+ Custom Tour<br/>+ Itinerary Agent<br/>+ Perf Optimization<br/>+ Salesforce Plan]
    end

    A1 --> A2 --> A3 --> A4 --> A5 --> A6

    style A1 fill:#ff6b6b,color:#fff
    style A2 fill:#ff922b,color:#fff
    style A3 fill:#fcc419,color:#333
    style A4 fill:#94d82d,color:#333
    style A5 fill:#51cf66,color:#fff
    style A6 fill:#4263eb,color:#fff

---

Feature Flags — Configurabilidade por Cliente

graph TD
    FF[Feature Flags Engine]
    FF --> EB["ENABLE_BOOKING<br/>(default: true)"]
    FF --> EP["ENABLE_PAYMENT<br/>(default: true)"]
    FF --> EM["ENABLE_MEMORY<br/>(default: true)"]
    FF --> ECT["ENABLE_CUSTOM_TOUR<br/>(default: true)"]
    FF --> EI["ENABLE_ITINERARY<br/>(JWT role-based)"]

    EB --> BOOK[booking_agent]
    EP --> PAY[payment_agent]
    EM --> MEM[CloudSQL Memory v2<br/>+ PreloadMemoryTool]
    ECT --> CT[custom_tour_agent]
    EI --> IT[itinerary_agent]

    EP -.->|requer| EB

    style FF fill:#4263eb,color:#fff

Cenário	Sub-agents	Tools	Uso
Completo	8	31	Operação full (B2C)
Sem payment	7	28	Reserva offline
Sem booking/payment	6	20	Orçamento puro (Whitelabel)
Mínimo	5	18	Vitrine + atendimento

---

Economia de Tokens (Antes vs Depois)

pie title Tokens por Turno — v1.0 (Single-Agent)
    "Prompt (336 linhas)" : 40
    "24 Tool schemas" : 35
    "Histórico" : 25

pie title Tokens por Turno — v3.1 (Multi-Agent)
    "Prompt orquestrador (~60 linhas)" : 15
    "Prompt agente ativo (~40 linhas)" : 10
    "2-8 Tool schemas" : 10
    "Histórico (compactado)" : 15
    "Cache (static_instruction)" : 0
    "Economia" : 50

Resultado: ~70% de redução em tokens por turno em fluxos focados.

---

Qualidade e Testes

Categoria	Arquivos	Testes
Sub-agentes	test_sub_agents.py	60+
Orquestrador	test_orchestrator.py	45+
Feature flags	test_feature_flags.py	26
AgentBuilder	test_agent_builder.py	30
Memory Service	test_memory_service.py	52
App Config	test_app_config.py	20
Session Service	test_cloudsql_session_service.py	—
API Client	test_api_client.py	—
Tools (diversos)	múltiplos	—
Total	42 arquivos	682 testes

---

Canais de Atendimento Suportados

graph LR
    subgraph "Produção"
        S1[Slack ✅]
        S2[WhatsApp Evolution ✅]
        S3[SSE Streaming ✅]
        S4[WebChat Widget ✅]
    end

    subgraph "Disponível"
        S5[WhatsApp Official Meta]
        S6[Telegram]
    end

    subgraph "Planejado"
        S7[Salesforce Einstein Bot]
    end

    style S1 fill:#51cf66,color:#fff
    style S2 fill:#51cf66,color:#fff
    style S3 fill:#51cf66,color:#fff
    style S4 fill:#51cf66,color:#fff
    style S5 fill:#fcc419,color:#333
    style S6 fill:#fcc419,color:#333
    style S7 fill:#868e96,color:#fff

---

Stack Tecnológico

Tecnologia	Versão	Uso
Google ADK	1.25.1	Framework de agentes
Gemini	2.5 Flash	Modelo LLM principal
Python	3.11	Runtime
FastAPI	—	Servidor HTTP
Google Cloud Run	—	Hosting (serverless containers)
CloudSQL (MySQL)	5.7+	Sessions + Memory
Redis	—	Cache + JWT Lookup
SendGrid	—	Email transacional
pytest	7.4+	Testes

---

Próximos Passos (Q2 2026 — Planejado)

Iniciativa	Descrição
Salesforce Integration	Einstein Bot ↔ Cloud Run via Apex Action (plano detalhado)
Usage Tracking	Métricas de uso por cliente/canal/agente
SkillToolset	Carregamento lazy de skills (L1/L2/L3) para escalabilidade
Vector Search	Embeddings para memória semântica (BigQuery/Vertex AI)
Whitelabel v2	Personalização de persona, idioma e catálogo por tenant

---

Documento gerado em 06 de abril de 2026 — Release 3.1.0