🔧 Troubleshooting: Agente não mostra chamadas de ferramentas no ADK Web

🔴 Problema Relatado

Ao testar no ADK Web, o agente disse que iria buscar produtos, mas: - ❌ Não mostrou as chamadas de ferramentas sendo executadas - ❌ Não retornou resultados - ❌ Não apresentou erros nos logs

🔍 Causas Possíveis Identificadas

1. Instrução do Agente Não Explícita o Suficiente

O agente pode tentar "adivinhar" respostas sem chamar ferramentas se as instruções não forem claras.

Solução Aplicada:

# ❌ ANTES
instruction="""
    3. Buscar produtos relevantes.
"""

# ✅ DEPOIS
instruction="""
    ⚠️ REGRA CRÍTICA: SEMPRE USE AS FERRAMENTAS - NUNCA INVENTE RESPOSTAS

    - NUNCA responda sobre produtos sem PRIMEIRO chamar busca_produtos_tool
    - NUNCA invente IDs, preços, disponibilidades ou detalhes de produtos
    - SEMPRE mostre ao usuário que está buscando (ex: "Vou buscar produtos em Roma...")

    3. BUSCA DE PRODUTOS
    - **CRÍTICO:** Use a ferramenta busca_produtos SEMPRE que o usuário pedir sugestões
    - NUNCA pule esta etapa
    - Antes de chamar, diga: "Deixe-me buscar..."
"""

2. Parâmetro tipo_produto Mal Tipado

O parâmetro estava como Optional[str] mas sem valor default, causando confusão.

Solução Aplicada:

# ❌ ANTES
async def busca_produtos_tool(
    metadados_busca: str, 
    tipo_produto: Optional[str],  # Sem default!
    ...
)

# ✅ DEPOIS
async def busca_produtos_tool(
    metadados_busca: str, 
    tipo_produto: Optional[str] = None,  # Com default None
    ...
)

3. Falta de Logs Detalhados

O ADK Web pode não mostrar logs internos das ferramentas.

Solução Aplicada: Adicionamos logs verbosos em TODAS as etapas:

print(f"[busca_produtos_tool] INICIANDO BUSCA")
print(f"[busca_produtos_tool] Parâmetros recebidos:")
print(f"  - metadados_busca: {metadados_busca}")
print(f"  - tipo_produto: {tipo_produto}")

# Durante execução
print(f"[busca_produtos_tool] Executando query no BigQuery...")
print(f"[busca_produtos_tool] Query submetida, aguardando resultados...")
print(f"[busca_produtos_tool] Resultados recebidos!")

# Ao finalizar
print(f"[busca_produtos_tool] CONCLUÍDO: {len(produtos)} produtos encontrados")

Esses logs aparecerão no console do ADK Web e ajudarão a debugar.

4. Suporte para Tipos de Produto Incompleto

O código só tratava guia explicitamente, mas não experience, ticket, transfer.

Solução Aplicada:

# ✅ AGORA
if tipo_produto in ["guia", "ifriend", "guide", "virtual_guide"]:
    where_clauses.append("p.product_type = 'guia'")
elif tipo_produto in ["experience", "ticket", "transfer"]:
    where_clauses.append(f"p.product_type = '{tipo_produto}'")
elif tipo_produto:
    print(f"[busca_produtos_tool] AVISO: tipo '{tipo_produto}' não reconhecido")

🧪 Como Testar Localmente

Execute o script de teste:

cd /Users/glauberportella/Projects/ifriend/ifriend-agents
python test_busca_local.py

Saída Esperada:

================================================================================
TESTE: busca_produtos_tool
================================================================================

🔍 TESTE 1: Busca por 'guias em Roma'
--------------------------------------------------------------------------------
[busca_produtos_tool] INICIANDO BUSCA
[busca_produtos_tool] Parâmetros recebidos:
  - metadados_busca: guias em Roma
  - tipo_produto: guia
  - guia_pro: False
  - limit: 3
[busca_produtos_tool] Query text limpo: 'guias em Roma'
[busca_produtos_tool] Filtro adicionado: product_type = 'guia'
[busca_produtos_tool] Executando query no BigQuery...
[busca_produtos_tool] Query submetida, aguardando resultados...
[busca_produtos_tool] Resultados recebidos!
[busca_produtos_tool] Processando resultados...
[busca_produtos_tool] CONCLUÍDO: 3 produtos encontrados
✅ SUCESSO: 3 produtos encontrados

📊 Verificação no ADK Web

O que você DEVE ver agora:

1. Console Logs:
2. [busca_produtos_tool] INICIANDO BUSCA

3. [busca_produtos_tool] CONCLUÍDO: X produtos encontrados

4. Tool Calls Panel:

5. Nome da ferramenta: busca_produtos_tool
6. Parâmetros enviados

7. Status: Success/Error

8. Resposta do Agente:

9. "Deixe-me buscar produtos em [localidade]..."
10. Lista formatada com os produtos encontrados

Se AINDA NÃO aparecer:

Checklist de Debug:

• [ ] Verifique credenciais do BigQuery:

  echo $GOOGLE_APPLICATION_CREDENTIALS
  gcloud auth application-default print-access-token
  

• [ ] Verifique se o projeto está correto:

  echo $GOOGLE_CLOUD_PROJECT
  # Deve ser: ifriend-platform
  

• [ ] Rode teste local primeiro:

  python test_busca_local.py
  

• [ ] Verifique variáveis de ambiente no ADK Web:

• GOOGLE_CLOUD_PROJECT=ifriend-platform
• DATASET=Ifriend_produto
• TABLE=mv_product_search_flat_embeddings

• EMBEDDING_MODEL_NAME=mte002

• [ ] Verifique se a ferramenta está no tools list:

  # Em agent.py
  tools=[
      busca_produtos_tool,  # ✅ Deve estar aqui
      ...
  ]
  

🎯 Próximos Passos

1. Teste Local Primeiro

python test_busca_local.py

Se funcionar localmente → problema é no ADK Web (credenciais/env vars).
Se NÃO funcionar → problema é na ferramenta/BigQuery.

2. Deploy no ADK Web

# Se estiver usando ADK CLI deploy
adk deploy cloud_run \
  --project=ifriend-platform \
  --region=us-central1 \
  --service_name=ifriend-agent-test \
  --app_name=ifriend_agent \
  --with_ui \
  ./ifriend_agent

3. Monitore os Logs

No ADK Web, abra o Console e procure por: - [busca_produtos_tool] - logs da ferramenta - [root_agent] - logs do agente - Erros do BigQuery - Erros de autenticação

4. Teste Conversacional

Exemplos de prompts:

"Procuro guias em Roma"
"Me mostre experiências em Paris"
"Quero ver tickets para o Cristo Redentor"

Resposta Esperada:

Deixe-me buscar guias em Roma...
[logs aparecem]
Encontrei 10 guias em Roma:

1. Nome do Guia
   ID: 123
   Preço: $50/hora
   Link: [...]

📝 Resumo das Alterações

Arquivo	Mudanças
busca_produtos_tool.py	✅ Adicionados logs verbosos em todas etapas
busca_produtos_tool.py	✅ Parâmetro tipo_produto agora tem default None
busca_produtos_tool.py	✅ Suporte explícito para experience, ticket, transfer
busca_produtos_tool.py	✅ Melhor tratamento de erros com logs
agent.py	✅ Instruções CRÍTICAS para SEMPRE usar ferramentas
agent.py	✅ Instruções para informar usuário antes de buscar
test_busca_local.py	✅ Script de teste local criado

🆘 Se o Problema Persistir

1. Compartilhe o log completo do ADK Web
2. Execute python test_busca_local.py e compartilhe a saída

3. Verifique se há erro de autenticação:

   gcloud auth list
   gcloud config get-value project
   

4. Teste direto no BigQuery:

   SELECT COUNT(*) 
   FROM `ifriend-platform.Ifriend_produto.mv_product_search_flat_embeddings`
   

---

Data: 6 de dezembro de 2025
Status: ✅ Melhorias aplicadas - pronto para teste