📊 DIAGRAMA DE FLUXO - AGENTE DE RESERVAS¶
Visão Geral do Sistema¶
┌─────────────────────────────────────────────────────────────┐
│ USUÁRIO │
│ (Slack / API) │
└─────────────────┬───────────────────────────────────────────┘
│
│ "Quero fazer uma reserva"
▼
┌─────────────────────────────────────────────────────────────┐
│ ROOT AGENT │
│ - Detecta intenção de reserva │
│ - Delega ao booking_agent │
└─────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ BOOKING AGENT │
│ Fluxo conversacional para emitir reserva │
└─────────────────┬───────────────────────────────────────────┘
│
▼
[Fluxo Detalhado Abaixo]
Fluxo Detalhado do Booking Agent¶
┌──────────────────────────────────────────────────────────────┐
│ 1. IDENTIFICAR CLIENTE │
└──────────────┬───────────────────────────────────────────────┘
│
│ "Qual é o seu email?"
│
▼
┌──────────────────────────────────────────────────────────────┐
│ buscar_usuario_tool(email) │
│ GET /users?userEmail={email} │
└──────────────┬───────────────────────────────────────────────┘
│
┌─────┴─────┐
│ │
found=True found=False
│ │
▼ ▼
┌─────────┐ ┌────────────────┐
│ Usar │ │ Coletar dados │
│ user.id │ │ completos do │
│ │ │ customer │
└────┬────┘ └────────┬───────┘
│ │
└────────┬───────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ 2. IDENTIFICAR PRODUTO E TIPO │
│ "Qual produto deseja reservar? (ID)" │
│ "Tipo: guia, experience, ticket, transfer?" │
└──────────────┬───────────────────────────────────────────────┘
│
┌─────┴─────────┐
│ │
Tipo: GUIA Tipo: EXPERIENCE
│ │
│ ▼
│ ┌────────────────────┐
│ │ tem_variacao_tool? │
│ └────────┬───────────┘
│ │
│ ┌─────┴─────┐
│ │ │
│ Sim=True Não=False
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ Listar │ │
│ │ Variações│ │
│ └────┬─────┘ │
│ │ │
│ ▼ │
│ [Usuário │
│ escolhe] │
│ │ │
└─────────┴───────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ 3. COLETAR DADOS DA RESERVA │
│ - Data(s): YYYY-MM-DD │
│ - Horário: HH:MM (ou M/T/N para guias) │
│ - Participantes: num_adult, num_child │
│ - Outros: isIfriendCar, hours, etc │
└──────────────┬───────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ 4. COLETAR DADOS DOS PASSAGEIROS (PAX) │
└──────────────┬───────────────────────────────────────────────┘
│
┌─────┴──────────┐
│ │
1 Adulto Apenas Múltiplos
│ │
▼ ▼
┌──────────┐ ┌──────────────┐
│ PAX = │ │ Loop para │
│ Customer │ │ cada pessoa: │
│ │ │ - fullname │
│ │ │ - doc │
│ │ │ - gender │
│ │ │ - birthday │
│ │ │ - email │
│ │ │ - phone │
└────┬─────┘ └──────┬───────┘
│ │
└─────────┬────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ 5. VALIDAR DADOS │
│ validar_dados_reserva_tool(...) │
└──────────────┬───────────────────────────────────────────────┘
│
┌─────┴─────┐
│ │
valid=True valid=False
│ │
│ ▼
│ ┌──────────────┐
│ │ Solicitar │
│ │ correções │
│ └──────┬───────┘
│ │
│ [Loop até válido]
│ │
└─────────┬───┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ 6. EMITIR RESERVA │
└──────────────┬───────────────────────────────────────────────┘
│
┌─────┴─────────┐
│ │
Tipo: GUIA Tipo: EXPERIENCE
│ │
▼ ▼
┌────────────────┐ ┌─────────────────────┐
│ emitir_reserva │ │ emitir_reserva │
│ _guia_tool │ │ _experience_tool │
│ │ │ │
│ POST /bookings │ │ POST /bookings │
└────────┬───────┘ └─────────┬───────────┘
│ │
└──────────┬─────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ API Response │
└──────────────┬───────────────────────────────────────────────┘
│
┌─────┴─────┐
│ │
success=True success=False
│ │
▼ ▼
┌──────────┐ ┌────────────┐
│ ✅ OK │ │ ❌ Erro │
│ │ │ │
│ Retorna: │ │ Retorna: │
│ booking_ │ │ error msg │
│ id │ │ │
└────┬─────┘ └─────┬──────┘
│ │
└──────┬───────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ 7. RESPOSTA AO USUÁRIO │
│ │
│ Se sucesso: │
│ "✅ Reserva #123 criada com sucesso!" │
│ "Próximo passo: realizar o pagamento" │
│ │
│ Se erro: │
│ "❌ Não foi possível criar a reserva: {erro}" │
│ "Por favor, verifique: {detalhes}" │
└──────────────────────────────────────────────────────────────┘
Fluxo de Dados - Estrutura¶
┌─────────────────────────────────────────────────────────────┐
│ ENTRADA: Intenção do Usuário │
│ "Quero reservar o guia ID 3 para 10/09/2026 às 12h" │
└─────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ PROCESSAMENTO: Extração de Informações │
│ │
│ product_id: 3 │
│ product_type: "guia" │
│ day: "2026-09-10" │
│ period: "12:00" │
│ num_adult: 1 (inferido) │
│ num_child: 0 (inferido) │
└─────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ COLETA INTERATIVA: Dados Faltantes │
│ │
│ 1. Email → busca usuário │
│ ├─ Se existe: customer_id │
│ └─ Se não: firstname, lastname, phone, birthday │
│ │
│ 2. PAX (para cada pessoa): │
│ ├─ fullname │
│ ├─ doc (CPF/Passaporte) │
│ ├─ gender (m/f/o) │
│ ├─ birthday (YYYY-MM-DD) │
│ ├─ email │
│ └─ phone (+5531...) │
└─────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ VALIDAÇÃO: Todos os Campos │
│ │
│ ✓ Email válido │
│ ✓ Telefone com código país │
│ ✓ Data futura │
│ ✓ Formato de data correto │
│ ✓ Todos campos obrigatórios preenchidos │
└─────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ PAYLOAD FINAL: JSON para API │
│ │
│ { │
│ "type": "normal", │
│ "ifriend": {"id": 3}, │
│ "customer": {"id": 7}, │
│ "dates": [{ │
│ "day": "2026-09-10", │
│ "hours": 4, │
│ "period": "12:00", │
│ "numAdult": 1, │
│ "numChild": 0, │
│ "isIfriendCar": false │
│ }], │
│ "pax": [{ │
│ "fullname": "João Silva", │
│ "doc": "123.456.789-00", │
│ "gender": "m", │
│ "birthday": "1990-01-15", │
│ "email": "joao@exemplo.com", │
│ "phone": "+5531999999999" │
│ }] │
│ } │
└─────────────────┬───────────────────────────────────────────┘
│
▼ POST /bookings
┌─────────────────────────────────────────────────────────────┐
│ API iFriend │
│ https://api.theifriend.com/bookings │
└─────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ RESPOSTA: Booking Criado │
│ │
│ { │
│ "id": 41, │
│ "confirmStatus": 0, │
│ "paymentStatus": 0, │
│ "price": "64.000000", │
│ "currencyCode": "USD", │
│ "paymentToken": "3c4d...", │
│ ... │
│ } │
└─────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ SAÍDA: Mensagem ao Usuário │
│ │
│ "✅ Reserva #41 criada com sucesso!" │
│ │
│ Detalhes: │
│ • Guia: Kyla Russel (#3) │
│ • Data: 10/09/2026 às 12:00 │
│ • Duração: 4 horas │
│ • Participantes: 1 adulto │
│ • Valor: USD 64.00 │
│ │
│ Próximo passo: Realizar pagamento │
│ Token de pagamento: 3c4d... │
└─────────────────────────────────────────────────────────────┘
Arquitetura de Componentes¶
┌─────────────────────────────────────────────────────────────┐
│ ROOT AGENT │
│ (Orquestrador Principal) │
│ │
│ Tools disponíveis: │
│ ├─ busca_produtos_tool │
│ ├─ detalhes_experience │
│ ├─ detalhes_guia │
│ ├─ disponibilidade_* │
│ ├─ calcular_preco_tool │
│ ├─ faq_tool │
│ └─ 📌 booking_agent ◄─── NOVO! │
└──────────────────┬──────────────────────────────────────────┘
│
│ Delega quando detecta
│ "quero reservar"
▼
┌─────────────────────────────────────────────────────────────┐
│ BOOKING AGENT │
│ (Agente Especializado em Reservas) │
│ │
│ Tools disponíveis: │
│ ├─ 📧 buscar_usuario_tool │
│ │ └─ GET /users?userEmail={email} │
│ │ │
│ ├─ ✅ validar_dados_reserva_tool │
│ │ └─ Validações locais (email, CPF, datas, etc) │
│ │ │
│ ├─ 🎯 emitir_reserva_guia_tool │
│ │ └─ POST /bookings (type: normal/virtual_guide) │
│ │ │
│ ├─ 🎫 emitir_reserva_experience_tool │
│ │ └─ POST /bookings (type: experience/ticket/transfer) │
│ │ │
│ └─ Acesso às tools do root_agent: │
│ ├─ detalhes_guia │
│ ├─ detalhes_experience │
│ ├─ tem_variacao_tool │
│ ├─ listar_variacoes_tool │
│ └─ calcular_preco_tool │
└─────────────────┬───────────────────────────────────────────┘
│
│ Chamadas HTTP
▼
┌─────────────────────────────────────────────────────────────┐
│ API iFriend │
│ https://api.theifriend.com │
│ │
│ Endpoints utilizados: │
│ ├─ GET /users?userEmail={email} │
│ ├─ GET /ifriends/{id} │
│ ├─ GET /experiences/{id} │
│ ├─ GET /experiences/{id}/availability/{month} │
│ ├─ POST /bookings/price │
│ └─ POST /bookings ◄─── PRINCIPAL! │
└─────────────────────────────────────────────────────────────┘
Fluxo de Experiências com Variação¶
┌──────────────────────────────────────────────────────────────┐
│ Usuário: "Quero reservar experiência 38" │
└──────────────┬───────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ tem_variacao_tool(38) │
│ Retorna: True │
└──────────────┬───────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ listar_variacoes_tool(38, "2026-03-20") │
│ │
│ Retorna: │
│ [ │
│ { │
│ "id": 13, │
│ "name": "Tour Privativo", │
│ "agePolicies": [ │
│ {"id": 34, "name": "Adulto", "minAge": 18, ...}, │
│ {"id": 35, "name": "Criança", "minAge": 3, ...} │
│ ] │
│ }, │
│ { │
│ "id": 14, │
│ "name": "Tour Compartilhado", │
│ "agePolicies": [...] │
│ } │
│ ] │
└──────────────┬───────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Agente apresenta ao usuário: │
│ │
│ "Esta experiência tem as seguintes opções: │
│ │
│ *Opção 1: Tour Privativo* (Variação ID: 13) │
│ Participantes aceitos: │
│ • Adulto (18-99 anos) - Política ID: 34 │
│ • Criança (3-17 anos) - Política ID: 35 │
│ │
│ *Opção 2: Tour Compartilhado* (Variação ID: 14) │
│ Participantes aceitos: │
│ • Adulto (18-99 anos) - Política ID: 36 │
│ │
│ Qual opção prefere? E quantas pessoas?" │
└──────────────┬───────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Usuário responde: "Opção 1, 2 adultos e 1 criança" │
└──────────────┬───────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Agente extrai: │
│ - variation_id: 13 (Opção 1) │
│ - age_policies: [ │
│ {"id": 34, "quantity": 2}, // 2 adultos │
│ {"id": 35, "quantity": 1} // 1 criança │
│ ] │
└──────────────┬───────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Coleta PAX para 3 pessoas (2 adultos + 1 criança) │
└──────────────┬───────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Monta payload com providerData: │
│ │
│ { │
│ "type": "experience", │
│ "experience": {"id": 38}, │
│ "customer": {"id": 7}, │
│ "dates": [{...}], │
│ "pax": [{...}, {...}, {...}], // 3 pessoas │
│ "providerData": { │
│ "provider": "platform", │
│ "variations": [{ │
│ "id": 13, │
│ "quantity": 1, │
│ "agePolicies": [ │
│ {"id": 34, "name": "Adulto", "quantity": 2}, │
│ {"id": 35, "name": "Criança", "quantity": 1} │
│ ] │
│ }] │
│ } │
│ } │
└──────────────┬───────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ POST /bookings │
│ ✅ Reserva #47 criada! │
└──────────────────────────────────────────────────────────────┘
Legenda: - 📧 = Busca/Consulta - ✅ = Validação - 🎯 = Ação (Guia) - 🎫 = Ação (Experience) - ▼ = Fluxo sequencial - ┌─┴─┐ = Decisão/Ramificação