Feature Flags¶

Visão Geral¶

As feature flags controlam quais agentes e funcionalidades estão ativos no sistema. Todas são configuradas via variáveis de ambiente.

O registry central fica em ifriend_agent/config/feature_flags.py e o consumo no AgentBuilder em ifriend_agent/agent_builder.py.

Flags Disponíveis¶

Flag	Default	Descrição	Dependências
`ENABLE_BOOKING`	`true`	Habilita `booking_agent` (reservas)	—
`ENABLE_PAYMENT`	`true`	Habilita `payment_agent` (pagamentos)	`ENABLE_BOOKING`
`ENABLE_ITINERARY`	`true`	Habilita `itinerary_agent` (roteiros multi-destino)	—
`ENABLE_CUSTOM_TOUR`	`true`	Habilita `custom_tour_agent` (orçamento de viagem personalizado, catálogo iFriend)	—
`ENABLE_PROPOSAL`	`true`	Habilita `proposal_agent` (propostas comerciais em PDF para grupos, restrito a affiliate/admin)	—
`ENABLE_MEMORY`	`true`	Habilita memória cross-session (CloudSQL + PreloadMemoryTool + save callback)	—
`ENABLE_CUSTOM_AFFILIATE_BOOKING`	`false`	Habilita `custom_affiliate_booking_agent` (URL-only para afiliados)	—
`ENABLE_SUPPORT_PRE_QUALIFY`	`true`	Habilita pré-qualificação no `support_agent` (tópico → produto)	—
`ENABLE_A2A`	`false`	Habilita exposição do agente via protocolo A2A (requer ROLE_A2A_USER no JWT)	—
`ENABLE_A2A_STREAMING`	`false`	Habilita streaming SSE no A2A	`ENABLE_A2A`
`ENABLE_ANALYTICS`	`true`	Habilita tracking de analytics para billing por processo	—
`ENABLE_ANALYTICS_DEDUP`	`false`	Ativa deduplicação de eventos por sessão	`ENABLE_ANALYTICS`
`ENABLE_ANALYTICS_ITINERARY_HEURISTIC`	`true`	Habilita heurística P2 (itinerary_built via after_model)	`ENABLE_ANALYTICS`
`ENABLE_AGENTFORCE_HANDOFF`	`false`	Handoffs humanos do site passam pelo agente SDR do Agentforce (modo relay); adiciona `escalar_agentforce` a support/discovery/custom_tour — ver Handoff Trip → Agentforce	—
`ENABLE_KNOWLEDGE_BASE`	`false`	Habilita `knowledge_base_agent` (FAQ via base de conhecimento do affiliate no Qdrant) — ver Knowledge Base	—

Configurações Inválidas

ENABLE_PAYMENT=true requer ENABLE_BOOKING=true — não faz sentido pagar sem reserva.
ENABLE_ANALYTICS_DEDUP=true requer ENABLE_ANALYTICS=true.
ENABLE_ANALYTICS_ITINERARY_HEURISTIC=true requer ENABLE_ANALYTICS=true.

Cenários de Configuração¶

Tabela assume ENABLE_PROPOSAL=true (default) exceto na última linha, que mostra o efeito de desligá-la.

ENABLE_ITINERARY	ENABLE_BOOKING	ENABLE_PAYMENT	ENABLE_CUSTOM_TOUR	ENABLE_PROPOSAL	Sub-agents	Tools	Modo
true	true	true	true	true	10	53	Completo
true	true	true	false	true	9	44	Completo sem tour personalizado
true	true	false	true	true	9	50	Reserva sem pagamento online
true	false	false	true	true	8	42	Orçamento + tour
true	false	false	false	true	7	33	Orçamento puro
false	true	true	true	true	9	50	Completo sem roteiros
false	false	false	true	true	7	39	Orçamento + tour sem roteiros
false	false	false	false	true	6	30	Orçamento puro sem roteiros
true	true	true	true	false	9	49	Completo sem propostas comerciais B2B

Como Usar¶

Via Environment Variable¶

# Desabilitar reservas
export ENABLE_BOOKING=false

# Habilitar A2A
export ENABLE_A2A=true

Via .env¶

# Configuração completa
ENABLE_BOOKING=true
ENABLE_PAYMENT=true
ENABLE_ITINERARY=true
ENABLE_CUSTOM_TOUR=true
ENABLE_PROPOSAL=true
ENABLE_MEMORY=true
ENABLE_CUSTOM_AFFILIATE_BOOKING=false
ENABLE_SUPPORT_PRE_QUALIFY=true
ENABLE_A2A=false
ENABLE_A2A_STREAMING=false
ENABLE_ANALYTICS=true
ENABLE_ANALYTICS_DEDUP=false
ENABLE_AGENTFORCE_HANDOFF=false

Implementação¶

from ifriend_agent.config.feature_flags import get_flag, get_active_flags, validate_flags

# Verificar flag individual
if get_flag("ENABLE_BOOKING"):
    # booking_agent está disponível
    pass

# Obter todas as flags ativas
flags = get_active_flags()

# Validar dependências (levanta FeatureFlagError se inválido)
validate_flags()

Adicionar Nova Flag¶

Editar ifriend_agent/config/feature_flags.py
Adicionar ao _FLAG_REGISTRY:

_FLAG_REGISTRY = {
    ...
    "ENABLE_NOVA_FLAG": (True, "Descrição da nova funcionalidade", ["ENABLE_BOOKING"]),
}

O tuple segue o formato: (default_value, description, [dependencies]).

Se o novo agente deve ser montado condicionalmente no root_agent, adicionar ao _FLAG_TO_AGENT em agent_builder.py:

_FLAG_TO_AGENT = {
    ...
    "ENABLE_NOVA_FLAG": meu_novo_agent,
}

Usar no código:

if get_flag("ENABLE_NOVA_FLAG"):
    ...