Agentes¶

Root Agent (Orquestrador)¶

O root_agent é o ponto de entrada de todas as conversas. Ele utiliza o padrão Coordinator/Dispatcher do Google ADK.

Estrutura¶

root_agent = LlmAgent(
    name="root_agent",
    model="gemini-2.5-flash",
    tools=[PreloadMemoryTool(), AgentTool(research_agent), faq_tool],
    sub_agents=[
        discovery_agent,
        quote_agent,
        utils_agent,
        support_agent,
        booking_info_agent,
        # ... (via feature flags: booking, payment, itinerary, custom_tour, custom_affiliate_booking)
    ],
    before_agent_callback=before_agent_callback_combined,
    after_agent_callback=save_session_to_memory_callback,
)

Responsabilidades¶

Roteamento — Identificar qual sub-agent deve tratar
Prompt dinâmico — Gerar instruções baseadas nas flags ativas
Transferência — Passar contexto entre sub-agents
Resposta direta — Para saudações e perguntas gerais

Sub-Agentes¶

Padrão de Delegação¶

Padrão	Mecanismo	Quando Usar
LLM-driven transfer	`sub_agents` + `transfer_to_agent`	Fluxos multi-turn (resposta volta ao usuário)
Call-and-return	`AgentTool`	Invocação pontual (resultado volta ao orquestrador)

Discovery Agent¶

Busca experiências e guias turísticos. Fluxo: busca → lista numerada → seleção → detalhes + disponibilidade → transfere para cotação.

Tools (8): busca_produtos, detalhes_experience, detalhes_guia, disponibilidade_calendario, disponibilidade_horarios, listar_guias_experience, get_affiliate_config, transform_product_url (+ escalar_agentforce com ENABLE_AGENTFORCE_HANDOFF: busca vazia → oferece o especialista → handoff M1)

Itinerary Agent¶

Planejamento de roteiros multi-destino. Monta roteiros dia a dia com respostas textuais em Markdown (sem cards/blocks visuais — sempre passa suppress_blocks=True).

Tools (3): busca_produtos, detalhes_experience, detalhes_guia

Quote Agent¶

Calcula preços com variações e faixas etárias. Converte moeda se necessário. Também atende o "MODO ORÇAMENTO": busca produtos no catálogo (buscar_produtos_orcamento) e gera documento PDF do orçamento (gerar_proposta) — restrito a affiliate/admin (ver Feature Flags e a seção de controle de acesso em AGENTS.md). Aberto a qualquer usuário para cotação/busca; sem acesso ao PDF, avisa sem jargão técnico e encaminha a um consultor humano.

Tools (11): tem_variacao, listar_variacoes, calcular_preco, cotacao_moeda, get_affiliate_config, transform_product_url, build_options_block_tool, buscar_produtos_orcamento, perguntar_anexo, gerar_proposta, verificar_acesso_orcamento

Booking Agent¶

Emite reservas no sistema. Fluxo: buscar/criar usuário → validar dados → emitir → verificar allowCheckout → transfere para pagamento.

Tools (8): buscar_usuario, buscar_agencia, criar_conta_agencia, criar_conta_viajante, validar_dados_reserva, emitir_reserva_guia, emitir_reserva_experience, obter_reserva

Booking Info Agent¶

Consulta de reservas existentes (read-only). Sempre ativo (não depende de feature flag). Solicita booking ID + email e retorna status, voucher, datas, participantes.

Tools (1): obter_reserva

Payment Agent¶

Processa pagamentos via cartão tokenizado. Token expira em 60s. Valor sempre em BRL.

Tools (3): verificar_parcelas, gerar_token_cartao, processar_pagamento

Support Agent¶

Pré-qualifica atendimentos e escala para consultor humano via WhatsApp. Quando ENABLE_SUPPORT_PRE_QUALIFY=true, faz pré-qualificação com seleção de tópico e busca de produto. A ferramenta gerar_formulario_suporte detecta automaticamente horário de atendimento (out-of-hours).

Tools (4): gerar_formulario_suporte, busca_produtos, detalhes_experience, build_options_block_tool

Com ENABLE_AGENTFORCE_HANDOFF=true (fora de whitelabel), ganha escalar_agentforce e escala ao agente SDR no Agentforce em vez de gerar o formulário — ver Handoff Trip → Agentforce.

Custom Tour Agent¶

Orçamento de viagem personalizado, aberto a qualquer usuário. Busca produtos reais do catálogo (buscar_produtos_orcamento) → usuário seleciona cards → qualifica perfil + moeda → pergunta anexo → gera orçamento em PDF (gerar_proposta). Sem acesso ao PDF (não-affiliate), pula moeda/anexo/geração e vai direto para o handoff humano (gerar_briefing_tour + gerar_formulario_suporte), automaticamente — sem esperar o usuário pedir.

Tools (9): buscar_produtos_orcamento, busca_produtos, exibir_opcoes_produtos, perguntar_anexo, cotacao_moeda, gerar_proposta, gerar_briefing_tour, gerar_formulario_suporte, verificar_acesso_orcamento

Com ENABLE_AGENTFORCE_HANDOFF=true (fora de whitelabel), o handoff usa escalar_agentforce com o briefing estruturado — nunca para quem tem acesso ao PDF (affiliate/admin gera a proposta sozinho).

Proposal Agent¶

Gera propostas comerciais estruturadas em PDF para grupos/eventos (empresa/parceiro, evento, seções, condições de pagamento) — o caso de uso típico é um affiliate montando uma proposta B2B formal para um cliente. Busca produtos no catálogo iFriend como ponto de partida (preços prontos) e também aceita itens externos ao catálogo (já negociados com outro fornecedor) com preço informado manualmente. Exclusivo para affiliate/admin autenticado — checa acesso como primeira ação sempre que ativado, independente de como foi acionado.

Tools (4): verificar_acesso_orcamento, buscar_produtos_orcamento, perguntar_anexo, gerar_proposta

Custom Affiliate Booking Agent¶

Gera URL de reserva customizada para afiliados com bookingUrlTemplate. Coleta data, horário, passageiros, chama listar_variacoes para obter agePolicies IDs, gera URL final com transform_product_url. Feature flag: ENABLE_CUSTOM_AFFILIATE_BOOKING (default: false).

Tools (3): get_affiliate_config, listar_variacoes, transform_product_url

Único agente hoje que lê affiliate_config (ver Affiliate → Configuração). A customização é limitada aos templates de URL — não há branding, prompt ou seleção de sub-agentes por affiliate.

Research Agent (AgentTool — call-and-return)¶

Pesquisa web via Google Search integrado do ADK. Invocado pelo orquestrador para dados em tempo real (clima, eventos, informações turísticas). Nunca retorna concorrentes (GetYourGuide, Viator).

Tools (1): google_search (built-in ADK)

FAQ Agent (AgentTool — call-and-return)¶

Responde perguntas sobre a plataforma iFriend (como funciona, políticas, FAQ) via LLM com knowledge inline.

Tools (0): Nenhuma — respostas via LLM

Genérico e sempre ativo (não depende de feature flag, não lê affiliate_config). O conteúdo é fixo no prompt (URLs do help-center público da iFriend) — é o fallback usado quando não há knowledge_base_agent configurado/relevante para o affiliate.

Knowledge Base Agent (AgentTool — call-and-return)¶

Responde FAQ usando a base de conhecimento própria do affiliate (documentos customizados indexados em vetores no Qdrant). Feature flag: ENABLE_KNOWLEDGE_BASE (default: false) — kill-switch global; o gate por affiliate (tem KB configurada ou não) é feito dentro da tool, lendo affiliate_config.get("knowledgeBaseCollection"). Se não houver KB configurada ou nenhum resultado relevante (threshold de similaridade), o orquestrador usa faq_agent a seguir. Ver Affiliate → Knowledge Base.

Tools (1): knowledge_base_search

Handoff para o Agentforce (tool + relay)¶

Com ENABLE_AGENTFORCE_HANDOFF=true, os handoffs humanos do site passam primeiro pelo agente SDR no Agentforce (Salesforce Agent API). Não é um sub-agente: é a tool escalar_agentforce (usada por support_agent, discovery_agent e custom_tour_agent) + o agentforce_relay_callback no before_agent_callback do root_agent, que repassa as mensagens seguintes ao Agentforce sem rodar o LLM do Trip até a sessão ser encerrada.

Momento	Agente	`handoff_reason`
M1 — produto não encontrado	`discovery_agent`, `custom_tour_agent`	`produto_nao_encontrado`
M2 — pedido explícito de humano	`support_agent`	`pedido_humano` / `orcamento`
M3 — tour/orçamento sem acesso ao PDF	`custom_tour_agent` (quote via support)	`tour_personalizado` / `orcamento`

Antes de escalar, o Trip identifica a conta (viajante ou agência; agência exige empresa + CNPJ) e monta o Case "Fluxo de Vendas" já no formato do Composite Upsert do Salesforce (variável Sales_Case_Payload). Quando a conversa chega via A2A (o Agentforce chamando o Trip), não há handoff.

Detalhes (identificação, Case, contrato, ciclo de vida, fallback, A2A): Handoff Trip → Agentforce.

Adicionando Novo Agente¶

Consulte Como Adicionar Novo Agente