Skip to content

Capacidades — O que você pode construir com o iFriend Agents

Esta página é o ponto de partida para quem chega no projeto: um mapa de tudo que a plataforma já sabe fazer hoje, com o que está pronto/ligado em produção e o que existe no código mas ainda precisa ser conectado. Cada seção linka para a documentação detalhada correspondente.

Agentes disponíveis

O root_agent (orquestrador) delega para sub-agentes especializados conforme a intenção do usuário. Alguns estão sempre ativos; outros dependem de feature flags.

A coluna Produção / stage reflete os valores dos cloudbuild.yaml / cloudbuild.stage.yaml; a coluna Flag (default no código) é o que vale quando a env var não está definida (ex: ambiente local).

Agente O que faz Flag (default no código) Produção / stage
discovery_agent Busca produtos/experiências/guias no catálogo e consulta disponibilidade Sempre ativo ✅ / ✅
quote_agent Calcula preços, variações, faixas etárias e conversão de moeda; monta orçamento de vários produtos (o PDF exige affiliate/admin) Sempre ativo ✅ / ✅
utils_agent Envia emails e gera relatórios CSV Sempre ativo ✅ / ✅
support_agent Escala para atendimento humano via WhatsApp (com pré-qualificação) Sempre ativo ✅ / ✅
booking_info_agent Consulta reservas existentes (status, voucher) Sempre ativo ✅ / ✅
research_agent Pesquisa na web em tempo real (clima, eventos) via Google Search Sempre ativo (tool) ✅ / ✅
faq_agent FAQ genérico da plataforma iFriend Sempre ativo (tool) ✅ / ✅
itinerary_agent Monta roteiros de viagem dia a dia, multi-destino ENABLE_ITINERARY (ligado) ✅ / ✅ (aberto a todos — ver nota abaixo)
custom_tour_agent Monta orçamento de viagem personalizado com produtos reais do catálogo; sem acesso ao PDF, encaminha para um consultor ENABLE_CUSTOM_TOUR (ligado) ✅ / ✅
proposal_agent Gera propostas comerciais em PDF para grupos — só affiliate/admin (ou integrador OAuth no A2A) ENABLE_PROPOSAL (ligado) ✅ / ✅
booking_agent Identifica/cria contas e emite reservas ENABLE_BOOKING (ligado) ❌ / ❌
payment_agent Processa pagamento com cartão (tokenização, parcelas) ENABLE_PAYMENT (ligado, requer ENABLE_BOOKING) ❌ / ❌
custom_affiliate_booking_agent Gera link de reserva que redireciona para o fluxo próprio do affiliate ENABLE_CUSTOM_AFFILIATE_BOOKING (desligado) ❌ / ❌
knowledge_base_agent Responde FAQ usando a base de conhecimento própria do affiliate ENABLE_KNOWLEDGE_BASE (desligado) + affiliate com KB configurada ❌ / ✅

Com booking e pagamento desligados em produção, o agente cota e monta orçamentos, mas não emite reservas nem cobra — o fechamento vai para o atendimento humano.

Acesso por usuário: a geração de PDF (gerar_proposta) e o proposal_agent exigem role de affiliate/admin no JWT — ou um integrador autenticado via OAuth no A2A. O itinerary_agent segue o mesmo modelo, mas quando ENABLE_ITINERARY está definida explicitamente (como em produção e stage) ela vira override estático e o roteiro fica aberto a qualquer usuário. Detalhes em Agentes e na seção "Controle de Acesso Dinâmico" do AGENTS.md.

Ver Agentes para detalhes de cada um, e Como Adicionar Novo Agente para criar o seu.

Canais de mensageria

Todos os canais implementam a mesma interface (MessagingAdapter) e passam pelo mesmo pipeline (ConversationProcessor) — áudio, arquivos, anti-loop e sessão funcionam igual em qualquer canal.

Canal Status
Slack ✅ Produção
WhatsApp (Evolution API, self-hosted) ✅ Produção
WhatsApp Official (Meta Cloud API) ✅ Produção
WebChat (REST puro) ✅ Produção
SSE (Server-Sent Events, streaming) ✅ Produção
Telegram ⚠️ Exemplo/referência — o próprio código indica passos pendentes para produção

Ver Fluxo de Mensagens e Mensageria (inclui como criar um novo adapter).

Customização por Affiliate (multi-tenant)

Cada affiliate (agência de turismo) pode ter, hoje:

  • Markups de preço próprios (por tipo de produto: guia, experiência, ingresso, transfer, pacote).
  • Branding em emails e no atendimento (logo, contato, WhatsApp).
  • Whitelabel: domínio e visual próprios, com o agente embutido no site do affiliate.
  • URL de reserva customizada: em vez do fluxo de booking padrão, gera um link que redireciona para o sistema do affiliate (ENABLE_CUSTOM_AFFILIATE_BOOKING).
  • Knowledge base / FAQ customizado: upload de documentos próprios (PDF/DOCX/TXT), indexados em vetores, respondidos pelo knowledge_base_agent em vez do FAQ genérico.

Ver Affiliate → Configuração, Whitelabel, Knowledge Base e o guia para adicionar novas customizações por affiliate, Estendendo a Configuração do Agente.

Integração com outros agentes (A2A)

  • Como provedor (✅ ligado em produção e stage): o root_agent é exposto via A2A (JSON-RPC 2.0, com streaming SSE) para que outros agentes/sistemas o chamem, publicando um Agent Card com 8 skills (discovery, itinerary, quote, booking, payment, support, custom_tour, booking_info). Dois modos de autenticação:
    • API client iFriend (OAuth): o integrador manda client_id, client_secret e integrator_id em headers, e o agente chama a API iFriend com o token dele (X-API-TOKEN) — ENABLE_A2A_OAUTH.
    • JWT de conta de serviço com a role ROLE_A2A_USER.
  • Como cliente: o iFriend pode chamar agentes externos (parceiros) via protocolo A2A — descoberta por Agent Card, chamadas síncronas ou streaming, e acompanhamento de tasks longas. As tools entram no root_agent com ENABLE_A2A_CLIENT (desligada por padrão e em produção), com os agentes configurados em A2A_EXTERNAL_AGENTS.

Ver Integração A2A → Para Parceiros e Para Desenvolvedores.

Memória entre sessões

Controlada por ENABLE_MEMORY (ligada por padrão no código, mas desligada em produção e stage hoje). O backend é escolhido por MEMORY_BACKEND (cloudsql nos deploys):

Backend Status Melhor para
CloudSQL (padrão) ✅ Suportado Produção — baixa latência, custo previsível
Redis ✅ Suportado Cache rápido de memórias recentes
In-memory ✅ Suportado Desenvolvimento/testes (perde tudo ao reiniciar)
Firestore ⚠️ Implementado, não conectado à fábrica Zero manutenção de servidor, escala automática
OpenMemory ⚠️ Implementado, não conectado à fábrica Busca semântica avançada sobre embeddings

Ver Memória e Session/Memória/Auth.

Outras capacidades de plataforma

Capacidade O que faz
Transcrição de áudio Mensagens de voz transcritas via Gemini 2.5 Flash antes de chegar ao agente
Arquivos/documentos PDF, imagens, CSV, DOCX processados nativamente pelo Gemini
Envio de email Confirmações e propostas via SendGrid
Busca de produtos Busca semântica no Qdrant (embedding local, catálogo sincronizado do CloudSQL por um job) com filtro geográfico e por idioma do guia — ver Busca de Produtos
Orçamentos e propostas em PDF Gera o documento a partir de produtos reais do catálogo (gerar_proposta), com gate de acesso por role
Analytics/billing Tracking de uso por processo, com fan-out para PostHog e BigQuery
Escalação humana Formulário de contato + WhatsApp, com detecção de horário comercial; opcionalmente passando antes pelo agente SDR do Agentforce (ENABLE_AGENTFORCE_HANDOFF, ver Handoff Trip → Agentforce)
Proteção de dados (PII) Remove campos sensíveis das respostas de API antes do LLM ver
Anti-loop 4 camadas de proteção contra loops bot-a-bot
Autenticação JWT identifica o usuário/affiliate em qualquer canal; no A2A, também OAuth de integrador da API iFriend
Observabilidade Tracing de agentes e chamadas ao Gemini no Braintrust (com BRAINTRUST_API_KEY)

O que existe no código mas ainda não está "ligado"

Para não gerar expectativa errada — estas capacidades têm implementação completa, mas estão desligadas em produção ou não estão conectadas a nenhum fluxo ativo hoje. Vale saber que existem antes de reimplementar do zero:

  • Reservas e pagamento (booking_agent, payment_agent) — completos, mas ENABLE_BOOKING/ENABLE_PAYMENT estão desligadas em produção e stage.
  • Memória entre sessões — ENABLE_MEMORY desligada em produção e stage.
  • Tools de A2A client (listar_agentes_a2a, chamar_agente_a2a, consultar_task_a2a) — funcionam de ponta a ponta e entram no root_agent com ENABLE_A2A_CLIENT=true, mas a flag está desligada até haver um agente externo real em A2A_EXTERNAL_AGENTS.
  • Knowledge base por affiliate — ligada só em stage (ENABLE_KNOWLEDGE_BASE).
  • Email via Gmail e MailerSend — implementações completas, mas só o SendGrid está de fato conectado ao utils_agent.
  • Memória via Firestore/OpenMemory — implementadas, mas a fábrica (MEMORY_BACKEND) hoje só resolve redis/cloudsql/inmemory.
  • Write-back do knowledgeBaseCollection no affiliate_config — o worker de indexação faz o PATCH na iFriend API, mas só com IFRIEND_API_KB_WRITEBACK_ENABLED=true, que está false nos deploys do worker (produção e stage); por enquanto a collection é configurada à mão (ver Knowledge Base).
  • Busca de produtos via BigQuery — continua no código como alternativa ao Qdrant, usada só com ENABLE_QDRANT_PRODUCT_SEARCH desligada.

Onde ir a partir daqui