Ir para conteúdo
be-human.ai
← Voltar ao blog

Ferramentas e integrações

Esquema de ferramentas para agentes de IA: campos tipados e erros claros

Regras práticas para campos tipados e mensagens de erro explícitas em esquemas de ferramentas para agentes de IA, para que falhas sejam fáceis de corrigir.

Capa tipográfica do Be Human com o título: Esquema de ferramentas para agentes de IA: campos tipados e erros claros
Ilustração conceitual criada com IA · Be Human

Um esquema de ferramenta diz ao agente de IA o que ele pode enviar a um sistema e o que pode esperar de volta. Esquemas fortes usam campos tipados, com listas fechadas de valores, e devolvem erros que apontam o campo, a regra que falhou e o próximo passo seguro. Assim o agente corrige a chamada em vez de adivinhar. As regras abaixo são práticas o suficiente para serem verificadas antes que qualquer ferramenta chegue à produção.

Principais pontos

  • Defina tipo, formato e obrigatoriedade para cada campo, e recuse qualquer valor fora disso antes de a chamada ser executada.
  • Use listas fechadas para escolhas como status, moeda e tipo de documento, em vez de texto livre.
  • Escreva mensagens de erro que nomeiem o campo, informem a regra e digam o que o agente pode fazer em seguida.
  • Mantenha falhas de validação, negações de permissão e indisponibilidade do sistema em códigos de erro separados.
  • Teste cada ferramenta com entradas malformadas, vazias, grandes demais e ambíguas antes de um agente usá-la.

O que um esquema de ferramenta precisa fazer para um agente

Um agente não enxerga o seu ERP, a sua caixa de entrada ou a sua planilha. Ele enxerga um nome de ferramenta, uma descrição curta e um esquema que lista as entradas que pode preencher. Quando esse esquema é frouxo, o agente completa as lacunas com a sua melhor leitura do pedido, e uma leitura que parece plausível ainda pode gravar o registro errado no lugar errado.

Trate o esquema como um contrato com três partes: o que a ferramenta faz, o que cada entrada significa e como é um resultado válido ou inválido. Um teste útil é imaginar um novo integrante da equipe lendo apenas o esquema. Se essa pessoa não conseguisse prever o que acontece com um campo em branco, uma data em formato incomum ou um valor sem moeda, o agente também não conseguirá prever.

Para nomes de campos e tipos mais detalhados, veja esquema de ferramentas para agentes de IA: nomes e tipos que funcionam.

Tipe cada campo e diga o que ele não é

Comece pelo tipo e depois acrescente as restrições que o tipo sozinho não expressa. A maioria das falhas vem de campos que eram tecnicamente texto ou número, mas carregavam um significado não declarado.

  • Datas: aceite um único formato, a data no padrão ISO 8601, e informe na descrição a qual fuso horário a data se refere.
  • Valores monetários: envie o valor e o código da moeda em dois campos, e diga se o valor inclui impostos.
  • Identificadores: informe o sistema de origem e o formato exato, para que o agente passe o identificador do contato no CRM e não o nome do contato.
  • Status: use um valor de uma lista, nunca um campo de sim ou não que esconda o estado real.
  • Listas: defina um tamanho máximo, porque uma lista sem limite transforma uma entrada ruim em um lote grande.
  • Campos opcionais: marque-os explicitamente e diga o que a ferramenta faz quando eles são omitidos.

A descrição de cada campo deve cobrir o que ele não é. “valor é o total com impostos, não o valor líquido” evita um desencontro comum entre o que o agente acredita e o que o sistema armazena.

Use listas fechadas para toda escolha

Texto livre é a forma mais rápida de criar variantes invisíveis. Um campo de status que aceita texto vai receber “pago”, “Pago”, “quitado” e “pagamento recebido” do mesmo processo, e cada um pode ser gravado de um jeito ou tratado por um ramo diferente da sua lógica.

Escreva a lista completa de valores permitidos dentro do esquema. Se o negócio precisar de um valor novo, inclua-o por meio de uma mudança na ferramenta, e não deixe o agente inventar um. Evite a opção “outros” a menos que ela venha acompanhada de um campo de observação obrigatório, porque “outros” absorve silenciosamente todos os casos que ninguém previu. O mesmo raciocínio vale para tipos de documento, moedas, níveis de prioridade e canais.

Escreva erros que o agente consiga usar

Um erro faz parte da interface. Muitas ferramentas devolvem mensagens genéricas como “entrada inválida” ou “falha na requisição”, o que deixa o agente com duas opções: repetir a mesma chamada ou adivinhar uma correção. Ambas desperdiçam tempo e podem gerar efeitos colaterais.

Uma mensagem de erro legível tem cinco partes:

  • Um código de erro estável, como invalid_field_value, que não muda entre versões.
  • O caminho do campo, como lines[2].quantity, para que o agente e quem lê o log vejam a localização exata.
  • A regra que falhou, descrita em uma frase.
  • Uma descrição curta do valor recebido, com dados pessoais e financeiros mascarados.
  • A próxima ação: corrigir e repetir, pedir a uma pessoa ou parar.

Compare duas mensagens. “Error: invalid input” não diz a ninguém o que mudar. “invalid_field_value em lines[2].quantity: deve ser um número inteiro de 1 a 500, recebido um decimal. Corrija o valor e repita esta chamada uma vez” oferece ao agente um reparo preciso e ao operador uma linha de log clara.

Mantenha três famílias de erro separadas. Uma falha de validação significa que a requisição estava malformada, então o agente deve corrigi-la e repetir. Uma negação de permissão significa que a requisição não é permitida para este papel, então o agente deve parar e reportar. Um erro de sistema significa que o serviço está indisponível ou lento, então valem as regras de nova tentativa e espera. Quando essas famílias compartilham um só código, agentes repetem coisas que nunca deveriam repetir, e quem lê os logs não consegue distinguir se a falha está na requisição, nas permissões ou no fornecedor. Diretrizes de segurança como o OWASP Top 10 for LLM Applications tratam chamadas de ferramenta geradas por modelos como entradas que precisam ser validadas antes de um sistema agir, e mensagens de erro claras fazem parte desse ciclo de validação.

Cenário ilustrativo: uma consulta de reembolso que deixa de adivinhar

Cenário ilustrativo: um agente de suporte precisa localizar um pedido antes de redigir uma proposta de reembolso. Na primeira versão, o campo order_ref aceitava qualquer texto, e a ferramenta devolvia “não encontrado” para toda consulta que falhava, seja porque a referência tinha formato errado, seja porque o pedido não existia, seja porque o agente não tinha permissão para ler aquela loja. O agente testou várias variações da referência, o que encheu o log de ruído e escondeu o problema real, uma lacuna de permissão.

Depois que o esquema foi reescrito, order_ref passou a ter um formato declarado. Uma referência malformada devolvia order_ref_format_invalid com o padrão esperado. Um pedido inexistente devolvia order_not_found. Uma leitura negada devolvia permission_denied e indicava quem podia conceder o acesso. O agente parou de repetir no último caso e pediu a uma pessoa. O reembolso em si continuou atrás de uma aprovação separada, como descrito em permissões de pagamento para agentes de IA, começando pela leitura.

Checklist antes de qualquer ferramenta chegar a um agente

Orientações de fornecedores sobre como escrever ferramentas para agentes e como rodar avaliações apontam na mesma direção: teste as ferramentas com entradas realistas, leia as falhas e altere o esquema antes de alterar o prompt. Use a lista abaixo na revisão.

  • Cada entrada tem tipo, formato, indicação de obrigatoriedade e, quando for o caso, uma lista fechada de valores.
  • Cada descrição de campo diz o que o campo não é, com a confusão mais provável explicitada.
  • Cada erro tem código estável, caminho do campo, regra que falhou e próxima ação.
  • Negações de permissão, falhas de validação e erros de sistema devolvem códigos diferentes.
  • Ferramentas de escrita aceitam uma referência estável ou uma chave de idempotência, para que uma nova tentativa não crie um segundo registro.
  • Entradas malformadas, vazias, grandes demais, ambíguas e de limite foram executadas, e o erro esperado foi registrado.
  • Os logs guardam a chamada, o resultado da validação e o código de erro, com valores sensíveis mascarados.
  • Um responsável nomeado revisa cada mudança de esquema antes da publicação, e as mudanças acrescentam campos opcionais em vez de renomear os existentes.

O item sobre ferramentas de escrita se sobrepõe às regras em ações idempotentes em agentes de IA, e a lista inteira pode ser incorporada ao seu checklist de aceitação de integração.

Como a Be Human trata esquemas de ferramentas em operações gerenciadas

Be Human desenha o primeiro papel em torno de uma tarefa útil e depois escreve os esquemas das ferramentas que essa tarefa precisa. As entradas são extraídas dos sistemas de registro, as listas de valores são combinadas com o responsável pelo negócio, e cada código de erro é escrito para que a equipe de operações consiga lê-lo no log de monitoramento sem abrir o código. Negações de permissão são encaminhadas ao aprovador nomeado, falhas de validação voltam ao agente para correção, e erros de sistema seguem as regras de nova tentativa definidas para aquela integração.

Depois da publicação, avaliações recorrentes reexecutam um conjunto fixo de entradas, incluindo os casos malformados e de limite do checklist. Quando um fornecedor altera um campo ou uma resposta, o replay mostra a mudança antes que ela chegue a um cliente ou a um colega, e a revisão de permissões verifica se o escopo da ferramenta ainda corresponde ao trabalho. As mudanças de esquema são versionadas, para que o responsável veja o que mudou e por quê. O serviço é entregue remotamente, em inglês ou em português.

Se você não sabe qual das suas ferramentas merece primeiro uma revisão de esquema, o diagnóstico gratuito de IA da Be Human pode ajudar a encontrar a primeira tarefa que vale a pena entregar a um agente.

Perguntas frequentes

O que é um esquema de ferramenta para um agente de IA?

É o contrato escrito que descreve o nome de uma ferramenta, suas entradas, os tipos e valores permitidos, e os resultados ou erros que ela pode devolver. O agente lê esse contrato para decidir o que enviar, então ele deve dizer exatamente como é uma chamada válida. Sem isso, o agente precisa inferir as regras a partir de exemplos, e é aí que os erros começam.

Todo campo deve ter um tipo rígido?

Sim, para qualquer coisa que um sistema armazene ou sobre a qual aja, como datas, valores, identificadores e status. Texto livre pode continuar em observações ou resumos que uma pessoa lê e que nenhuma etapa seguinte interpreta. Como regra, um campo que altera um registro deve ser tipado e restringido, enquanto um campo que apenas explica o pedido pode continuar descritivo.

Quão detalhada deve ser uma mensagem de erro?

Ela precisa ser detalhada o bastante para que o agente corrija a chamada ou pare sem adivinhar, e curta o bastante para que o log continue legível. Inclua um código estável, o caminho do campo, a regra que falhou e a próxima ação. Mascare valores pessoais ou financeiros, porque mensagens de erro costumam ser copiadas para logs e chamados.

Preciso reescrever os esquemas quando um fornecedor muda a API?

Nem sempre, mas você deve verificar toda vez. Acrescentar campos opcionais costuma ser seguro, enquanto renomear um campo ou mudar o seu significado é uma quebra de compatibilidade que exige nova versão, reexecução das entradas de teste e revisão pela pessoa responsável pela integração. Uma mudança do fornecedor deve aparecer em uma avaliação antes de aparecer em uma tarefa real.

Seu próximo passo

Descubra primeiro onde um agente de IA cabe na sua empresa.

Faça o diagnóstico gratuito de IA da Be Human. Algumas perguntas sobre o seu trabalho mostram qual tarefa entregar primeiro a um agente, o que ele precisa saber e onde uma pessoa aprova.

Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.

Menos tarefas. Mais espaço para você.

Traga o trabalho para o qual falta tempo.

Agende uma conversa e teste 7 dias grátis um agente de IA personalizado ↗Ou faça o diagnóstico gratuito de IA →