Skip to content

Changelog

Todas as mudanças notáveis neste projeto serão documentadas neste arquivo.

O formato é baseado em Keep a Changelog, e este projeto adere ao Semantic Versioning.

[3.7.0] - 2026-06-29

🎉 Adicionado

  • A2A Protocol (Agent-to-Agent) via runtime/a2a/: expõe o agente via JSON-RPC 2.0
  • Endpoints: message/send, message/stream, tasks/get, tasks/cancel
  • Agent Card público em /.well-known/agent-card.json
  • Autenticação JWT com role ROLE_A2A_USER
  • Streaming SSE via ENABLE_A2A_STREAMING
  • OAuth2 server alternativo (create_a2a_app_oauth2)
  • CLI de teste: examples/a2a_test_cli.py
  • Task persistence em CloudSQL
  • LoopGuard (runtime/messaging/loop_guard.py): proteção anti-loop bot-to-bot (4 camadas: dedup, circuit breaker, repetição textual, hard turn limit)

🔄 Modificado

  • Refatoração da estrutura de diretórios: separação clara entre ifriend_agent/ (core do agente) e runtime/ (plataforma e infraestrutura)
  • Paths corrigidos em Dockerfile, avaliações e documentação

🐛 Corrigido

  • A2A: import faltante de Starlette em server.py
  • A2A: rotas registradas via add_routes_to_app() em vez de startup event (incompatível com app.mount())
  • CLI de teste A2A: compatibilidade com artifacts/messageId da spec

[3.6.1] - 2026-06-27

🎉 Adicionado

  • Geo-filtering para busca de guias por país de destino
  • Inferência de país via nearest 50 products para fallback geo

🐛 Corrigido

  • Busca: supressão de blocks quando fallback é usado
  • Busca: geo-filter fallback que retornava resultados globais silenciosamente

[3.6.0] - 2026-06-26

🎉 Adicionado

  • Geo-filtering via embedding: filtragem geográfica por threshold de similaridade entre embeddings de destino e produto
  • Pre-população de session state com datas e itinerary hint (otimização de context cache ADK)
  • Audio transcription via Gemini 2.5 Flash (14x mais barato que GCP Speech-to-Text)
  • File support: PDF, imagens, CSV, DOCX passados diretamente ao Gemini como Part.from_bytes()

🔄 Modificado

  • Busca: peso de localização no ranking usando embedding do destino
  • Threshold geo reduzido para 0.30
  • WebChat adapter: suporte a audio_data e file_data via base64

📚 Documentação

  • Preenchidas 11 lacunas em architecture, config, onboarding e messaging docs

[3.5.6] - 2026-06-16

🐛 Corrigido

  • Bug na detecção de horário de atendimento (out-of-hours)

[3.5.5] - 2026-05-25

🐛 Corrigido

  • Template padrão de mensagem out-of-hours

[3.5.4] - 2026-05-25

🐛 Corrigido

  • Ajustes no fluxo de suporte out-of-hours

[3.5.3] - 2026-05-23

🎉 Adicionado

  • Out-of-business-hours detection: gerar_formulario_suporte detecta automaticamente horário de atendimento e redireciona para WhatsApp de emergência
  • Env vars: SUPPORT_START_HOUR, SUPPORT_END_HOUR, SUPPORT_TIMEZONE, SUPPORT_EMERGENCY_WHATSAPP, SUPPORT_OUT_OF_HOURS_MESSAGE

[3.5.2] - 2026-05-23

🐛 Corrigido

  • pool_pre_ping desabilitado para evitar TypeError no aiomysql

[3.5.1] - 2026-05-23

🐛 Corrigido

  • Substituição de descrição vaga por literal no mensagem_amigavel do support_agent e custom_tour_agent

[3.5.0] - 2026-05-22

🎉 Adicionado

  • custom_tour_agent: concierge consultivo para qualificação de tours personalizados
  • custom_affiliate_booking_agent: reserva via URL de afiliado (transform_product_url)
  • ENABLE_MEMORY: feature flag para memória cross-session (PreloadMemoryTool + CloudSQL)
  • Sanitize module (tools/sanitize.py): strip_sensitive, safe_booking_summary, safe_user_summary, safe_agencia_summary — filtragem de PII em todas as tools
  • Memory: FULLTEXT search com sumarização LLM
  • Prompt guardrails em todos os agentes para proteção de dados de contato

🔄 Modificado

  • AgentBuilder: composição dinâmica com feature flags + geração automática de prompt
  • Feature flags: centralizadas em config/feature_flags.py com validação de dependências
  • Economia de tokens: ~70% menos tokens por turno (prompt dinâmico ~60 linhas vs 336)

📚 Documentação

  • AGENTS.md: documentação completa da arquitetura multi-agent (11 agentes)
  • Onboarding docs (6 documentos) criados

[3.0.0] - 2026-04-XX

🎉 Adicionado

  • Agentes: itinerary_agent (roteiros), booking_info_agent (consulta reservas)
  • Suporte a afiliados: whitelabel via partner_code no JWT, branding de email dinâmico
  • Booking: static_instruction com payloads JSON (cacheável pelo Gemini)
  • Support: pré-qualificação de tópico + busca de produto (ENABLE_SUPPORT_PRE_QUALIFY)
  • Avaliações de qualidade do agente (runtime/evaluations/)

🔄 Modificado

  • ADK atualizado para v1.25.1
  • ContextCacheConfig e EventsCompactionConfig habilitados
  • Email branding: cadeia de fallback (Affiliate → Whitelabel → Default)

[2.5.0] - 2026-03-XX

🎉 Adicionado

  • itinerary_agent: roteiros multi-destino (5 tools compartilhadas com discovery)
  • booking_info_agent: consulta de reservas read-only (always-on, independente de ENABLE_BOOKING)
  • Celular de emergência: suporte para WhatsApp de emergência fora do horário

🔄 Modificado

  • Discovery agent: fluxo alternativo de recomendação (rank eia até 5 produtos)
  • Quote agent: regra crítica de mapeamento de agePolicies[].id

[2.0.0] - 2026-01-02

🎉 Adicionado - Multi-Platform Support

Messaging Framework

  • Criado framework extensível em runtime/messaging/ para suporte a múltiplas plataformas
  • Implementado MessagingAdapter (interface abstrata) com padrão Strategy
  • Implementado AdapterFactory com auto-detecção de plataformas via env vars
  • Implementado ConversationProcessor agnóstico de plataforma
  • Criado IncomingMessage e OutgoingMessage como DTOs universais

Adaptadores

  • SlackAdapter ✅ (Produção) - Migrado de slack_bot.py
  • TelegramAdapter ⚠️ (Exemplo funcional)
  • WhatsAppAdapter ✅ (Produção via Evolution API)

Bot Unificado

  • Criado unified_bot.py com webhook único (/webhook/*)
  • Roteamento automático para adapter correto baseado no path
  • Health check endpoint (/) com informações de plataformas
  • Auto-configuração via variáveis de ambiente

Documentação

  • MESSAGING_ARCHITECTURE.md: Arquitetura completa (600 linhas)
  • MESSAGING_EXAMPLES.md: Exemplos práticos e deploy (400 linhas)
  • MIGRATION_GUIDE.md: Guia passo-a-passo de migração (300 linhas)
  • MESSAGING_DIAGRAMS.md: Diagramas visuais em Mermaid (300 linhas)
  • QUICK_REFERENCE.md: Referência rápida (200 linhas)
  • REFACTORING_SUMMARY.md: Sumário executivo (400 linhas)
  • runtime/messaging/README.md: API reference do framework (250 linhas)
  • README.md: README principal atualizado

Testes

  • Criado tests/test_messaging_examples.py com ~15 testes exemplo
  • Fixtures para SlackAdapter, AdapterFactory e mock Runner
  • Exemplos de testes unitários e de integração

Configuração

  • Atualizado .env.example com variáveis de messaging
  • Criado requirements-messaging.txt para dependências opcionais
  • Suporte a configuração via MESSAGING_PLATFORMS ou auto-detecção

🔄 Modificado

Backend Services

  • Mantida integração com ADK Runner (inalterada)
  • Mantida integração com SessionService e MemoryService (inalteradas)
  • Preservada lógica de auto-save de memória após resposta

Logs

  • Logs estruturados com emojis para melhor legibilidade
  • Identificação clara de plataforma em cada log

♻️ Refatorado

De slack_bot.py para unified_bot.py

  • Extraída lógica Slack-específica para SlackAdapter
  • Separada lógica de processamento em ConversationProcessor
  • Removido código duplicado de webhook handling
  • Webhook path mudou de /slack/events para /webhook/slack/events

Separação de Responsabilidades

  • Adapter: Parse webhook ↔ Envio de mensagem
  • Factory: Criação e gerenciamento de adapters
  • Processor: Orquestração do fluxo de conversa
  • Bot: Roteamento de webhooks

🔒 Segurança

  • Validação de retries do Slack mantida
  • Filtro de mensagens de bot mantido
  • Signature validation delegada aos adapters

🐛 Corrigido

  • Removido acoplamento forte com Slack
  • Eliminado código duplicado para formatação de texto
  • Padronizado tratamento de threads/conversas

📦 Dependências

Novas (Opcionais)

  • python-telegram-bot>=20.7 (para Telegram)
  • httpx já incluído (para WhatsApp via Evolution API)

Mantidas

  • slack-bolt>=1.18.0 (para Slack)
  • slack-sdk>=3.27.0
  • Todas as dependências do ADK e iFriend Agent

⚠️ Breaking Changes

Path do Webhook Slack

  • Antes: https://dominio.com/slack/events
  • Depois: https://dominio.com/webhook/slack/events
  • Migração: Atualizar webhook no painel do Slack

Arquivo Principal

  • Antes: slack_bot.py
  • Depois: unified_bot.py
  • Nota: slack_bot.py mantido para compatibilidade

📊 Métricas

  • Código adicionado: ~2.400 linhas (código + testes)
  • Documentação: ~2.800 linhas
  • Total: ~5.200 linhas
  • Tempo de desenvolvimento: ~16 horas
  • Complexidade reduzida: 60% ↓
  • Tempo para nova plataforma: 87.5% ↓ (de 16h para 2h)

🔮 Deprecations

Nenhuma. O slack_bot.py original é mantido para compatibilidade.

[1.0.0] - 2025-12-XX

Versão Original

Adicionado

  • Bot Slack básico em slack_bot.py
  • Integração com ADK Runner
  • SessionService e MemoryService
  • Suporte a Redis e CloudSQL
  • Tools de booking, produtos, FAQ, etc.
  • Documentação básica

Convenções de Versionamento

  • Major (X.0.0): Breaking changes
  • Minor (0.X.0): Novas features (compatível)
  • Patch (0.0.X): Bug fixes