Minha tool custom não é chamada pelo agente ou retorna erro. Como investigar?
1 Answers
6 pontos comuns de falha, em ordem:
1. Tool não está habilitada no agente
Workspace → edição do agente → seção Ferramentas → marque a tool.
2. Usuário sem permissão de leitura da tool
Anexar ao agente não bypassa RBAC. O usuário precisa ter acesso à tool também.
3. Function calling no modo errado
Try: Advanced Params → Function Calling = native (precisa modelo compatível).
4. Docstring pobre
Modelo decide quando chamar lendo a docstring. Se está genérica ('faz algo'), modelo ignora. Escreva de forma específica.
5. Type hints ausentes
Sem type hints, o schema JSON sai pobre e o modelo não confia. Tipo em TODOS os parâmetros.
6. Erro na execução
Veja logs em Admin → Tools → [sua tool] → Execuções. Erros comuns: timeout, 401, import faltando.
Debug tool:
Crie uma tool de debug que emite o contexto para ver o que está chegando:
async def debug(self, __user__=None, __metadata__=None) -> dict:
"""Debug - retorna contexto recebido."""
return {'user': __user__, 'metadata': __metadata__}
📖 Documentação completa na Wiki:
Related