Esquemas de ferramentas e funções

A chamada de funções permite que um modelo solicite que seu código execute uma ação. Cada ferramenta é declarada com um nome, uma descrição, que indica quando usá-la, e um Esquema JSON para seus parâmetros.

O modelo nunca executa código; ele emite uma solicitação de chamada estruturada que seu ambiente de execução usa para dispatch. O esquema é o que torna os argumentos analisáveis.

Uma definição de ferramenta é uma declaração de capacidade envolvida por um esquema.

Com muitas ferramentas disponíveis, o modelo escolhe principalmente com base na descrição. Escreva descrições como regras de decisão:

• Indique quando usá-la e quando não usá-la.
• Distinga-a das ferramentas semelhantes.
• Mencione as pré-condições necessárias.

Descrições ruins causam a seleção da ferramenta errada com mais frequência do que esquemas ruins causam erros nos argumentos.

A chamada de funções ocorre em várias rodadas. O modelo emite uma chamada, você a executa, faz append do resultado e o modelo continua.

Os modelos modernos podem solicitar várias chamadas de ferramentas em uma única rodada quando as ações são independentes. Seu ambiente de execução deve iterar sobre todas as tool_calls, executá-las, idealmente em simultâneo, e retornar uma mensagem de ferramenta para cada tool_call_id.

Nunca presuma que haverá uma única chamada; sempre use um ciclo.

Controle a seleção com tool_choice:

• auto — o modelo decide.
• required — deve chamar alguma ferramenta.
• {name: ...} — força uma ferramenta específica.
• none — desabilita as ferramentas nesta rodada.

Forçar uma ferramenta específica transforma a chamada de funções em pura extração estruturada.

Mesmo com esquemas rigorosos, trate os argumentos das ferramentas como entrada não confiável. Faça uma nova validação em relação ao esquema e aplique regras de negócio antes de tocar em sistemas reais, como bancos de dados, pagamentos e exclusões de arquivos.

Quando uma ferramenta falha, retorne um erro estruturado como resultado da ferramenta, em vez de lançar uma exceção. O modelo pode então pedir desculpas, tentar novamente com argumentos corrigidos ou escolher outra ferramenta.

Faça com que os erros indiquem como agir: inclua um motivo e, quando for seguro, uma dica para recuperação.

Dezenas de ferramentas prejudicam a precisão da seleção e aumentam o custo de tokens, pois todo esquema fica no contexto a cada rodada. Medidas:

• Agrupe ações relacionadas em uma ferramenta com uma enumeração action.
• Exponha dinamicamente apenas as ferramentas relevantes para o estado atual.
• Use espaços de nomes para reduzir a confusão entre ferramentas semelhantes.

Para ações destrutivas, incorpore a segurança ao próprio esquema: exija um campo de confirmação explícita, restrinja os intervalos e evite identificadores de texto livre, dando preferência a enumerações ou padrões validados.

Trate a seleção de ferramentas como um comportamento mensurável. Crie um conjunto de avaliação de instruções associado à ferramenta e aos argumentos esperados e, em seguida, verifique se o modelo faz a escolha correta. Monitore regressões ao reformular descrições ou adicionar novas ferramentas.

Um modelo emite duas chamadas de ferramentas independentes em uma única resposta do assistente. O que seu ambiente de execução deve fazer?

Esquemas de ferramentas e funções na prática:

• As descrições orientam a seleção; os esquemas orientam argumentos que podem ser analisados.
• Percorra todas as chamadas de ferramentas; ofereça suporte à execução em paralelo.
• Controle o comportamento com a escolha de ferramenta; force uma ferramenta para extração pura.
• Valide novamente os argumentos; retorne erros estruturados.
• Mantenha pequena a superfície de ferramentas e reforce a proteção de ações destrutivas.

A seguir: ciclos de reparo e validação para quando a saída ainda apresentar problemas.