🔄 Refactor: Agente Monolítico (Opção 1)¶
Data: 6 de dezembro de 2025
Status: ✅ Concluído
📊 Problema Identificado¶
Arquitetura Anterior (Problemática)¶
┌─────────────────────────────────────────────┐
│ ROOT_AGENT │
│ ├─ busca_produtos_tool │
│ ├─ detalhes_*_tool │
│ ├─ disponibilidade_*_tool │
│ ├─ calcular_preco_tool │
│ ├─ faq_tool (agent) │
│ └─ booking_tool (agent) ← PROBLEMA │
│ └─ booking_agent │
│ ├─ buscar_usuario_tool │
│ ├─ validar_dados_reserva_tool │
│ ├─ emitir_reserva_*_tool │
│ ❌ NÃO TEM: busca_produtos │
│ ❌ NÃO TEM: detalhes_* │
└─────────────────────────────────────────────┘
Problemas:
1. ❌ booking_agent não conseguia buscar produtos por nome
2. ❌ booking_agent não tinha acesso às ferramentas de busca/detalhes
3. ❌ Não existia comunicação entre agentes no ADK
4. ❌ Contexto não fluía entre root_agent → booking_agent
5. ❌ Agente inventava respostas quando não tinha ferramentas necessárias
Sintomas observados: - Usuário: "Quero reservar Jantar-cruzeiro Romântico pelo Seine para 20/01/2026" - Agente: "O processo de reserva foi iniciado. Nosso time entrará em contato." ← INVENTADO - Real: Nenhuma ferramenta foi chamada, nenhuma reserva foi criada
✅ Solução Implementada¶
Arquitetura Nova (Monolítica)¶
┌─────────────────────────────────────────────┐
│ ROOT_AGENT (Agente Único) │
│ ├─ busca_produtos_tool │
│ ├─ detalhes_experience │
│ ├─ detalhes_guia │
│ ├─ disponibilidade_calendario_tool │
│ ├─ disponibilidade_horarios_tool │
│ ├─ tem_variacao_tool │
│ ├─ listar_variacoes_tool │
│ ├─ calcular_preco_tool │
│ ├─ cotacao_moeda │
│ ├─ gerar_csv_tool │
│ ├─ faq_tool (sub-agent) │
│ ├─ buscar_usuario_tool ← NOVO │
│ ├─ validar_dados_reserva_tool ← NOVO │
│ ├─ emitir_reserva_guia_tool ← NOVO │
│ └─ emitir_reserva_experience_tool ← NOVO │
└─────────────────────────────────────────────┘
TOTAL: 16 ferramentas no mesmo agente
Vantagens: - ✅ Agente tem TODAS as ferramentas necessárias - ✅ Contexto sempre disponível (busca → detalhes → preço → reserva) - ✅ Não precisa transferir entre agentes - ✅ Mais simples de debugar - ✅ Funciona com ADK atual (sem mudanças arquiteturais)
🔧 Mudanças Implementadas¶
1. Imports Adicionados (agent.py)¶
# Import booking tools (previously in booking_agent)
from ifriend_agent.tools.booking.buscar_usuario_tool import buscar_usuario_tool
from ifriend_agent.tools.booking.validar_dados_reserva_tool import validar_dados_reserva_tool
from ifriend_agent.tools.booking.emitir_reserva_guia_tool import emitir_reserva_guia_tool
from ifriend_agent.tools.booking.emitir_reserva_experience_tool import emitir_reserva_experience_tool
2. Tools Array Atualizado¶
Antes:
tools=[
busca_produtos_tool,
# ... outras 10 ferramentas
faq_tool,
booking_tool # ← Sub-agente
]
Depois:
tools=[
# Ferramentas de busca (11 ferramentas)
busca_produtos_tool,
tem_variacao_tool,
listar_variacoes_tool,
detalhes_experience,
detalhes_guia,
disponibilidade_calendario_tool,
disponibilidade_horarios_tool,
calcular_preco_tool,
cotacao_moeda,
gerar_csv_tool,
faq_tool,
# Ferramentas de reserva (4 ferramentas)
buscar_usuario_tool,
validar_dados_reserva_tool,
emitir_reserva_guia_tool,
emitir_reserva_experience_tool,
]
# TOTAL: 15 ferramentas (faq_tool é um sub-agente)
3. Instruções Combinadas¶
Tamanho anterior:
- root_agent: 126 linhas
- booking_agent: 120 linhas
- Total: 246 linhas (separados)
Tamanho novo:
- root_agent: ~250 linhas (combinado)
- Redução: Manteve-se similar, mas agora é UM ÚNICO agente
Seções das instruções:
- 🚨 REGRA ABSOLUTA: Ação imediata, proibições
- 🎯 ANÁLISE DE CONTEXTO: Verificar contexto antes de perguntar
- 📋 FLUXO DE EXECUÇÃO (7 passos):
- 1️⃣ Buscar produtos
- 2️⃣ Detalhes
- 3️⃣ Disponibilidade
- 4️⃣ Preço
- 5️⃣ Reserva (A→E: identificar cliente → confirmar → PAX → validar → emitir)
- 6️⃣ CSV
- 7️⃣ FAQ
- ⚙️ REGRAS DE VARIAÇÕES: variation_id ≠ agePolicy.id
- 📦 ESTRUTURA DOS PAYLOADS: Guias, Experiences exclusivas, Experiences com variação
- 🎯 FORMATAÇÃO: Markdown Slack
- ❌ NUNCA FAZER: Lista de proibições
- 🔧 FERRAMENTAS DISPONÍVEIS: Lista completa
📦 Arquivos Modificados¶
Modificados:¶
/ifriend_agent/agent.py- Adicionados imports de 4 ferramentas de booking
- Removido import de
booking_tool - Adicionadas 4 ferramentas ao
tools=[] - Combinadas instruções de root_agent + booking_agent
- Atualizada description do agente
Não Modificados (mantidos para referência):¶
/ifriend_agent/agents/booking_agent.py- DEPRECADO (não mais usado)/ifriend_agent/tools/booking/*.py- Ferramentas continuam funcionando normalmente
🧪 Testes Recomendados¶
1. Busca Simples¶
Prompt: "Procuro guias em Roma"
Esperado: ✅ Chama busca_produtos_tool imediatamente
2. Fluxo Completo (Busca → Reserva)¶
Passo 1: "Procuro experiências em Paris"
Passo 2: "Quero detalhes do produto ID 40324"
Passo 3: "Quanto custa para 2 adultos no dia 20/01/2026?"
Passo 4: "Quero reservar! Meu email é teste@ifriend.com"
Esperado: ✅ Contexto mantido, agente lembra produto/data/preço
3. Reserva Direta (Sem Busca Prévia)¶
Prompt: "Quero reservar a experiência ID 40324 para 20/01/2026, 2 adultos. Email: qa@theifriend.com"
Esperado:
✅ Chama buscar_usuario_tool(email)
✅ Pede dados dos passageiros
✅ Valida com validar_dados_reserva_tool
✅ Emite com emitir_reserva_experience_tool
✅ Retorna booking_id
4. FAQ (Sub-agente Continua Funcionando)¶
Prompt: "Como funciona o pagamento na iFriend?"
Esperado: ✅ Chama faq_tool normalmente
🎯 Resultados Esperados¶
Antes (Problema):¶
Usuário: "Quero reservar Jantar Seine para 20/01"
Agente: "Processo iniciado. Receberá email." ← INVENTADO
Logs: WARNING - thought_signature
Depois (Solução):¶
Usuário: "Quero reservar Jantar Seine para 20/01"
Agente: [CHAMA buscar_usuario_tool]
[CHAMA detalhes_experience se necessário]
[Pede dados dos passageiros]
[CHAMA validar_dados_reserva_tool]
[CHAMA emitir_reserva_experience_tool]
"✅ Reserva #12345 criada com sucesso!"
Logs: INFO - [buscar_usuario_tool] Buscando...
INFO - [emitir_reserva_experience_tool] Emitindo...
⚠️ Pontos de Atenção¶
1. Tamanho das Instruções¶
- Status: ~250 linhas (aceitável)
- Limite ADK: Não documentado, mas 250 linhas é razoável
- Fallback: Se ficar muito grande, pode ser dividido em seções
2. Número de Ferramentas¶
- Status: 15 ferramentas + 1 sub-agente
- ADK Suporta: Sim, não há limite documentado
- Comparação: Outros projetos ADK usam 20+ ferramentas
3. Context Window¶
- Risco: Com mais ferramentas, descrições podem consumir tokens
- Mitigação: Descrições das ferramentas são concisas
- Monitoring: Verificar se model não atinge context limit
4. Booking Agent Deprecado¶
- Arquivo mantido: Para referência histórica
- Não importado: Não causa conflito
- Pode deletar: Após validação que tudo funciona
🔄 Alternativas Consideradas¶
Opção 2: Supervisor + Roteamento¶
Descartada porque:
- Mais complexa de implementar
- Supervisor pode errar roteamento
- Contexto precisa ser passado entre agentes
- ADK não tem transfer_to_agent nativo
Opção 3: Ferramentas Compostas¶
Descartada porque: - Muito complexa - Risco de loops infinitos - Não é padrão ADK - Contexto difícil de gerenciar
📊 Métricas de Sucesso¶
- ✅ Sintaxe: 0 erros (validado com
get_errors) - ✅ Imports: Todos resolvidos
- ✅ Ferramentas: 15 funcionais
- ⏳ Testes funcionais: A validar
- ⏳ Performance: A monitorar
📝 Próximos Passos¶
- ✅ Commit das mudanças
- ⏳ Testar no ADK Web
- ⏳ Validar fluxo completo de reserva
- ⏳ Monitorar logs (sem
thought_signature) - ⏳ Documentar casos de uso
- ⏳ Deletar
booking_agent.py(após validação)
🔗 Referências¶
- Commit de Backup:
6669d5d- "Backup antes de refactor: agente monolítico (opção 1)" - Documentação ADK: Google Agentic Development Kit
- Análise Original:
/docs/ifriend_agent/FIX_AGENT_PAUSING.md - Sistema de Reservas:
/docs/ifriend_agent/SISTEMA_RESERVA.md
Autor: GitHub Copilot
Revisão: Pendente
Aprovação: Pendente