Seu Agente Está Chamando a Ferramenta Errada (E Aqui Está o Porquê)

Um guia para os modos de falha no uso de ferramentas que matam agentes de produção — e como preveni-los.

A maioria dos agentes falha no uso de ferramentas. Não porque o LLM é ruim em raciocínio. Mas porque os esquemas de ferramentas são ruins.

Eu passei meses construindo agentes que usam ferramentas para sistemas de produção e coletando modos de falha. Aqui estão os que vão te afetar e o que fazer a respeito.

Modo de Falha 1: Nomes de Ferramentas Ambíguos

Se você tem get_user e get_customer, seu agente vai confundi-los. Garantido. Não às vezes — consistentemente.

A solução é cirúrgica: nomeie as ferramentas pelo que elas FAZEM em nível semântico e adicione desambiguação explícita às descrições.

# Ruim
{"name": "get_user", "description": "Obter dados do usuário."}

# Bom
{
    "name": "get_user_account",
    "description": (
        "Buscar detalhes da conta interna do usuário (funcionários, membros da equipe). "
        "Usar para consultas de funcionários. "
        "NÃO para clientes externos — use get_customer_profile para isso."
    )
}

A frase-chave: "NÃO para X — use Y para isso." Exemplos negativos são mais úteis do que positivos.

Modo de Falha 2: O Modelo Ignora Sua Ferramenta

Você tem uma ferramenta get_current_weather. O usuário pergunta "como está o tempo em Chicago?" O modelo diz "Normalmente está frio em Chicago em março!" e não chama a ferramenta.

Isso acontece porque o treinamento do modelo diz que ele sabe disso. Você precisa substituir isso.

Duas soluções:

1. Adicione linguagem de gatilho à descrição: ""

"Use quando o usuário perguntar sobre as condições climáticas atuais, temperatura agora ou a previsão de hoje para qualquer local. SEMPRE use esta ferramenta — não use dados de treinamento para condições atuais."

2. Force a chamada da ferramenta:

response = client.chat(
    messages=messages,
    tools=tools,
    tool_choice={"type": "function", "function": {"name": "get_current_weather"}}
)

Modo de Falha 3: Execução Sequencial Quando Você Deveria Ir em Paralelo

Este é o mais comum killer de desempenho e o mais fácil de perder porque funciona — apenas lentamente.

# Isso leva 3x mais tempo do que precisa
weather = call_tool("get_weather", {"city": "NYC"})
news = call_tool("get_news", {"topic": "NYC"})
events = call_tool("get_events", {"city": "NYC"})

# Isso leva o mesmo tempo que a chamada única mais lenta
import asyncio
weather, news, events = await asyncio.gather(
    call_tool_async("get_weather", {"city": "NYC"}),
    call_tool_async("get_news", {"topic": "NYC"}),
    call_tool_async("get_events", {"city": "NYC"})
)

Os LLMs modernos (GPT-4, Claude 3+, Gemini 1.5+) emitir múltiplas chamadas de ferramentas em uma única resposta quando podem. Sua camada de execução deve estar pronta para executá-las em paralelo.

O padrão: