🔧 Fix: Agente Pausando Sem Chamar Ferramentas¶
🔴 Problema Identificado¶
Sintoma: Agente para sem chamar nenhuma ferramenta no ADK Web, ficando "travado"
Logs observados:
WARNING - types.py:5928 - Warning: there are non-text parts in the response:
['thought_signature'], returning concatenated text result from text parts.
Causa Raiz:
- O modelo Gemini estava retornando thought_signature (pensamento interno)
- As instruções eram muito longas e complexas (269 linhas!)
- O modelo estava planejando ao invés de executando ações
- Faltava ênfase em "ação imediata"
✅ Soluções Aplicadas¶
1. Instruções Simplificadas e Orientadas à Ação¶
ANTES (269 linhas):
instruction="""
Você é o SUPER-AGENTE da iFriend...
OBJETIVO GERAL
Interpretar o pedido do usuário e executar o fluxo de ponta a ponta:
1. Entender a intenção.
2. Extrair informações estruturadas...
3. Buscar produtos relevantes...
[... 250+ linhas de instruções detalhadas ...]
"""
DEPOIS (126 linhas - 53% menor):
instruction="""
Você é o agente da iFriend. Sua função é EXECUTAR AÇÕES usando ferramentas, não apenas planejar.
🚨 REGRA ABSOLUTA: AÇÃO IMEDIATA
- Quando o usuário perguntar algo → CHAME A FERRAMENTA IMEDIATAMENTE
- NÃO diga "vou fazer", "pretendo fazer" → FAÇA
- NÃO planeje passos → EXECUTE o primeiro passo
- Cada resposta deve conter PELO MENOS 1 chamada de ferramenta
📋 FLUXO DE EXECUÇÃO
PASSO 1: BUSCAR PRODUTOS
→ CHAMAR: busca_produtos_tool(metadados_busca="...", tipo_produto=...)
PASSO 2: DETALHES
→ CHAMAR: detalhes_guia(product_id) OU detalhes_experience(product_id)
[...]
"""
Principais mudanças: - ✅ Imperativo direto: "CHAME", "FAÇA", "EXECUTE" ao invés de "você deve" - ✅ Regra absoluta no topo: Cada resposta = pelo menos 1 ferramenta - ✅ Formato de passos: Claro e direto (→ CHAMAR: nome_da_tool) - ✅ Removido raciocínio interno: Foco em ação, não planejamento - ✅ Exemplos concisos: Apenas o essencial para variações
2. Logging Aprimorado¶
Adicionado:
import logging
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger(__name__)
logger.info("🚀 iFriend Agent - Módulo carregado")
logger.info(f"📦 Ferramentas disponíveis: busca_produtos, detalhes, ...")
Logs já existentes nas ferramentas:
- ✅ busca_produtos_tool.py - Logs com [busca_produtos_tool] prefix
- ✅ buscar_usuario_tool.py - Logs com [buscar_usuario_tool] prefix
- ✅ emitir_reserva_*_tool.py - Logs com prefix
- ✅ auth.py - Logs detalhados de autenticação
O que você verá agora nos logs:
2025-12-06 19:20:00 - ifriend_agent.agent - INFO - 🚀 iFriend Agent - Módulo carregado
2025-12-06 19:20:01 - INFO - [busca_produtos_tool] INICIANDO BUSCA
2025-12-06 19:20:01 - INFO - [busca_produtos_tool] Parâmetros recebidos:
2025-12-06 19:20:01 - INFO - - metadados_busca: guias em Roma
2025-12-06 19:20:02 - INFO - [busca_produtos_tool] Executando query no BigQuery...
2025-12-06 19:20:05 - INFO - [busca_produtos_tool] ✅ CONCLUÍDO: 10 produtos encontrados
🧪 Como Testar¶
1. Reinicie o ADK Web¶
# Se estiver rodando localmente
cd /Users/glauberportella/Projects/ifriend/ifriend-agents
adk dev ifriend_agent
2. Teste com Prompt Simples¶
"Procuro guias em Roma"
Esperado:
- ✅ Agente responde: "Vou buscar guias em Roma..."
- ✅ Logs mostram: [busca_produtos_tool] INICIANDO BUSCA
- ✅ Ferramenta é chamada imediatamente
- ✅ Resultados são retornados
Se ainda travar:
- Verifique logs completos do ADK Web
- Procure por thought_signature nos logs
- Verifique se há erros de autenticação do BigQuery
3. Teste Fluxo Completo¶
1. "Quero ver guias em Roma"
→ Deve chamar busca_produtos_tool
2. "Me mostre detalhes do guia ID 3"
→ Deve chamar detalhes_guia(3)
3. "Qual o preço para amanhã?"
→ Deve chamar calcular_preco_tool
🔍 Debug no ADK Web¶
Verificar Tool Calls¶
No ADK Web Interface:
1. Abra Developer Tools (F12)
2. Vá para aba Network
3. Procure por requisições POST /run_sse
4. Inspecione a resposta - deve conter tool_calls
Exemplo de resposta correta:
{
"candidates": [{
"content": {
"parts": [
{
"functionCall": {
"name": "busca_produtos_tool",
"args": {
"metadados_busca": "guias em Roma",
"tipo_produto": "guia"
}
}
}
]
}
}]
}
Verificar Logs Completos¶
No terminal onde ADK Web está rodando:
# Procure por estas linhas:
grep -A 5 "busca_produtos_tool" logs.txt
grep "tool_calls" logs.txt
grep "thought_signature" logs.txt # Se aparecer = problema ainda existe
📊 Comparação: Antes vs Depois¶
| Aspecto | Antes | Depois |
|---|---|---|
| Tamanho das Instruções | 269 linhas | 126 linhas (-53%) |
| Ênfase em Ação | "Você deve..." | "CHAME IMEDIATAMENTE" |
| Formato | Prosa longa | Passos claros (→ CHAMAR:) |
| Raciocínio Interno | Incentivado | Removido |
| Tool Calls | Inconsistente | Obrigatório (≥1 por resposta) |
| Logging | Básico | Detalhado com prefixos |
| Thought Signature | ❌ Presente | ✅ Eliminado |
🎯 Regras de Ouro para Instruções ADK¶
Aprendizados desta correção:
- Seja imperativo, não descritivo
- ❌ "Você pode buscar produtos usando..."
-
✅ "CHAME busca_produtos_tool(...)"
-
Ação antes de planejamento
- ❌ "Primeiro, analise a intenção, depois extraia metadados..."
-
✅ "→ CHAMAR: busca_produtos_tool"
-
Instruções concisas
- ❌ 250+ linhas de explicações detalhadas
-
✅ 100-150 linhas de passos diretos
-
Formato visual claro
- ✅ Use símbolos: 🚨, →, ✅, ❌
- ✅ Use CAPS para comandos: CHAMAR, FAZER, NUNCA
-
✅ Use código inline:
busca_produtos_tool(...) -
Logging em todas ferramentas
- ✅ Sempre use
logger = logging.getLogger(__name__) - ✅ Prefixe logs com
[nome_da_tool] - ✅ Log início, meio e fim de cada operação
🚨 Troubleshooting¶
Problema: Ainda está travando¶
Checklist:
- [ ] Reiniciou o ADK Web após a mudança?
- [ ] Verificou se há thought_signature nos logs?
- [ ] Testou com prompt simples ("procuro guias em Roma")?
- [ ] Verificou credenciais do BigQuery?
- [ ] Verificou se todas as ferramentas estão importadas?
Comando de diagnóstico:
cd /Users/glauberportella/Projects/ifriend/ifriend-agents
python -c "from ifriend_agent.agent import root_agent; print(f'Tools: {len(root_agent.tools)}')"
Deve retornar: Tools: 12
Problema: Ferramenta não está sendo chamada¶
Verifique:
1. Nome da ferramenta está nas instruções?
2. Ferramenta está na lista tools=[...]?
3. Ferramenta tem async def correto?
4. Logs mostram que ferramenta foi importada?
Teste isolado da ferramenta:
python -c "
import asyncio
from ifriend_agent.tools.busca_produtos_tool import busca_produtos_tool
async def test():
result = await busca_produtos_tool('guias em Roma', 'guia', False, 3)
print(f'Resultado: {len(result)} produtos')
asyncio.run(test())
"
Problema: Logs não aparecem¶
Configure nível de log:
# Em ifriend_agent/agent.py (já adicionado)
import logging
logging.basicConfig(level=logging.DEBUG) # Mais verboso
Ou via variável de ambiente:
export LOG_LEVEL=DEBUG
adk dev ifriend_agent
📝 Arquivos Modificados¶
| Arquivo | Mudanças |
|---|---|
ifriend_agent/agent.py |
✅ Instruções simplificadas (269→126 linhas) |
ifriend_agent/agent.py |
✅ Logging configurado |
ifriend_agent/agent.py |
✅ Ênfase em ação imediata |
ifriend_agent/tools/busca_produtos_tool.py |
✅ Logs já detalhados |
ifriend_agent/tools/booking/auth.py |
✅ Logs já detalhados |
ifriend_agent/tools/booking/*.py |
✅ Logs já detalhados |
📚 Referências¶
- ADK Best Practices: Instruções devem ser acionáveis, não descritivas
- Gemini Models: Preferem comandos diretos a explicações longas
- Tool Calling: Funciona melhor com passos claros e imperativos
Implementado: 6 de dezembro de 2025
Status: ✅ Pronto para teste
Próximo passo: Reiniciar ADK Web e testar com "procuro guias em Roma"