Como Projetar Ferramentas para Agentes de IA: Práticas de Trabalho e Erros Comuns

A qualidade de um agente de IA é determinada não apenas pelo poder do modelo de linguagem, mas também por quão bem suas ferramentas são projetadas. Machine Learning Mastery analisou o que exatamente torna as ferramentas de agente eficazes — e quais erros transformam um agente inteligente em um caótico.

Nome e descrição decidem tudo

O modelo de linguagem não vê o código-fonte da ferramenta. Ele só vê seu nome, descrição e esquema de parâmetros — e com base nesses, decide quando e com quais argumentos chamá-la. Exemplo de uma ferramenta fraca: `get_data()` com descrição "obtém dados". Exemplo de uma ferramenta forte: `get_user_purchase_history(user_id)` — "retorna uma lista de compras nos últimos 90 dias, classificadas por data. Use quando precisar analisar gastos ou construir personalização". A segunda opção explica não apenas o que a ferramenta faz, mas quando chamá-la — esses são níveis fundamentalmente diferentes de utilidade para o agente.

Um nome carrega semântica: `process_file` — muito amplo. `extract_invoice_line_items` — o modelo entende imediatamente o contexto e a aplicabilidade. Boa fórmula: verbo + objeto + esclarecimento.

"A descrição da ferramenta é um prompt para a própria ferramenta.

Se for vaga, o agente alucinará argumentos ou chamará a ferramenta errada."

Uma ferramenta — uma responsabilidade

O erro mais comum é uma "faca suíça": uma função com uma dúzia de parâmetros que faz cinco coisas diferentes dependendo de uma combinação de sinalizadores. Sinais de uma ferramenta mal projetada:

• Parâmetro `mode` ou `action` com um conjunto de valores de string
• Mais de 5–6 parâmetros em uma única função
• A descrição contém "ou" — "procura por contato ou cria um novo"
• Retorna tipos de dados diferentes dependendo dos argumentos de entrada
• Parâmetros opcionais que mudam drasticamente o comportamento

Se uma ferramenta faz várias coisas — divida-a em ferramentas separadas. Um agente escolherá mais facilmente entre `search_contact` e `create_contact` do que adivinhar a combinação certa de sinalizadores em `manage_contact`. Com mais de 20 ferramentas no contexto, a precisão dos modelos em escolher a certa cai visivelmente — mantenha o conjunto compacto.

Parâmetros e valores de retorno

O tipo de parâmetro afeta a qualidade da geração. `string` sem descrição — uma fonte de alucinações. `enum` com uma lista explícita de valores permitidos — não. Para parâmetros numéricos, especifique o intervalo e as unidades de medida: não `timeout`, mas `timeout_seconds: integer, 1–30`. O valor de retorno deve ser previsível e compacto: o agente adiciona toda a saída da ferramenta ao contexto. Se uma ferramenta retorna milhares de tokens de HTML bruto — este é um gargalo para toda a cadeia de chamadas. Princípios de um bom valor de retorno:

• JSON com estrutura fixa — o modelo analisa melhor formatos previsíveis
• Erros — dados estruturados, não exceções não capturadas
• Campos meta: `total_results`, `truncated: true`, `next_cursor`
• Apenas o que o agente precisa para a próxima etapa — nada mais
• Em caso de erro — uma mensagem clara com instruções para ação futura

O que isso significa

As ferramentas para agentes não são apenas wrappers em torno de APIs. Esta é uma interface entre o modelo de linguagem e o mundo real, exigindo a mesma atenção que uma API pública: documentação, tipos bem pensados, testes em isolamento. Um agente não corrigirá uma ferramenta mal projetada — ele a chamará incorretamente repetidamente.