Como projetar ferramentas para agentes de IA: boas práticas e erros comuns

A qualidade de um agente de IA depende da capacidade do modelo de linguagem, mas também do cuidado com que suas ferramentas foram projetadas. O Machine Learning Mastery analisou o que torna as tools de agentes eficazes e quais erros transformam um agente inteligente em um agente caótico.

Nome e descrição definem tudo

O modelo de linguagem não enxerga o código-fonte da ferramenta. Ele vê apenas o nome, a descrição e o schema de parâmetros. É com base nisso que decide quando chamá-la e com quais argumentos.

Um exemplo de ferramenta fraca: `get_data()`, com a descrição "obtém dados". Um exemplo de ferramenta forte: `get_user_purchase_history(user_id)`, com a descrição "retorna a lista de compras dos últimos 90 dias, ordenada por data. Use quando precisar analisar gastos ou criar personalização". A segunda opção explica o que a ferramenta faz e também quando chamá-la. Para o agente, são níveis de utilidade fundamentalmente diferentes.

O nome carrega semântica. `process_file` é amplo demais. Com `extract_invoice_line_items`, o modelo entende de imediato o contexto e a aplicação. Uma boa fórmula é verbo + objeto + especificação.

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

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

Uma ferramenta, uma responsabilidade

O erro mais frequente é o "canivete suíço": uma função com uma dezena de parâmetros que faz cinco coisas diferentes, dependendo da combinação de flags.

Sinais de uma ferramenta mal projetada:

• Um parâmetro `mode` ou `action` com um conjunto de valores em string
• Mais de 5–6 parâmetros em uma única função
• A descrição contém a conjunção "ou": "busca um contato ou cria um novo"
• Retorna tipos de dados diferentes conforme os argumentos de entrada
• Parâmetros opcionais que mudam radicalmente o comportamento

Se a ferramenta faz várias coisas, divida-a em ferramentas separadas. Para o agente, é mais fácil escolher entre `search_contact` e `create_contact` do que adivinhar a combinação certa de flags em `manage_contact`. Com mais de 20 ferramentas no contexto, a precisão dos modelos ao escolher a correta cai visivelmente. Por isso, mantenha o conjunto enxuto.

Parâmetros e valores de retorno

O tipo do parâmetro afeta a qualidade da geração. Uma `string` sem descrição é fonte de alucinações. Um `enum` com uma lista explícita de valores permitidos, não. Para parâmetros numéricos, informe o intervalo e a unidade de medida: em vez de `timeout`, use `timeout_seconds: integer, 1–30`.

O valor de retorno deve ser previsível e compacto, porque o agente adiciona toda a saída da ferramenta ao contexto. Se a ferramenta devolver milhares de tokens de HTML bruto, isso vira um gargalo para toda a cadeia de chamadas.

Princípios de um bom return value:

• JSON com estrutura fixa: o modelo faz parsing melhor de formatos previsíveis
• Erros como dados estruturados, e não como exceções não tratadas
• Metacampos: `total_results`, `truncated: true`, `next_cursor`
• Apenas o que o agente precisa para o próximo passo, nada além disso
• Em caso de erro, uma mensagem clara com instruções sobre o que fazer em seguida

O que isso significa

Ferramentas para agentes não são simples wrappers de API. Elas são a interface entre o modelo de linguagem e o mundo real e exigem a mesma atenção dada a uma API pública: documentação, tipos bem pensados e testes isolados. O agente não vai corrigir uma ferramenta mal projetada. Ele vai chamá-la de forma errada repetidas vezes.