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

Fundamentos de harness

Nomes de ferramentas para agentes de IA: nomes, descrições e esquemas claros

Nomeie ferramentas de agentes de IA, escreva descrições que guiem a escolha, crie esquemas que recusem chamadas vagas e revise tudo antes de lançar.

Capa tipográfica do Be Human com o título: Nomes de ferramentas para agentes de IA: nomes, descrições e esquemas claros
Ilustração conceitual criada com IA · Be Human

Nomear ferramentas para agentes de IA significa dar a cada ação um nome claro, uma descrição curta sobre quando usá-la e um esquema de argumentos que recuse entradas incompletas ou ambíguas. O modelo escolhe as ferramentas lendo esse texto. Por isso, um nome parecido com outro ou uma descrição que deixa de fora os efeitos colaterais gera ações erradas, mesmo quando o código por trás funciona. Revise nomes, descrições e esquemas como uma unidade antes do lançamento e teste com pedidos que deveriam acionar cada ferramenta e com pedidos que não deveriam acionar nenhuma.

Principais pontos

  • Dê a cada ferramenta um nome com verbo e objeto que corresponda a uma única ação de negócio, para que o modelo reconheça o pedido sem adivinhar.
  • Escreva a descrição como um guia de escolha: quando usar a ferramenta, quando não usar, o que ela devolve e se altera algum dado.
  • Use esquemas de argumentos para as verificações que o modelo não consegue fazer sozinho: campos tipados, opções fixas, valores obrigatórios e unidades.
  • Revise nomes, descrições e esquemas juntos e teste qual ferramenta o modelo escolhe para pedidos realistas, incluindo pedidos que não precisam de ferramenta.
  • Lance mudanças nas ferramentas como conjuntos versionados com caminho de reversão, do mesmo modo que faria com uma mudança de prompt.

Por que o nome da ferramenta decide a ação antes de qualquer código rodar

Um harness mostra ao modelo a lista de ferramentas disponíveis, cada uma com nome, descrição e definição de parâmetros. A cada passo, o modelo lê essa lista e escolhe uma ação ou nenhuma. O código por trás de uma ferramenta pode estar correto e, ainda assim, ser chamado no momento errado, porque a decisão foi tomada antes, em texto. Por isso, o desenho das ferramentas deve entrar na mesma revisão dos direitos de acesso e das regras de aprovação, e não em uma limpeza técnica separada depois. Se quiser entender como as chamadas de ferramenta se encaixam no ciclo de trabalho, a explicação simples sobre tool calling é um bom ponto de partida.

Exemplo ilustrativo: uma equipe de atendimento expõe duas ferramentas, uma chamada buscar_cliente e outra chamada obter_conta. Ambas devolvem um registro de cliente. Quando o usuário pergunta se uma fatura específica já foi paga, o modelo escolhe buscar_cliente, que devolve dados de contato, mas não o status do pagamento. A correção não é um prompt maior. É renomear e reescrever: uma ferramenta chamada buscar_status_pagamento_fatura, descrita como a ferramenta para perguntas sobre pago ou em aberto de um número de fatura, e uma ferramenta de cliente cuja descrição diz que devolve apenas dados de contato.

Como nomear uma ferramenta para que o modelo a escolha com segurança?

Um nome de ferramenta deve descrever exatamente uma ação sobre um tipo de objeto. O modelo trata os nomes como rótulos literais, então nomes vagos o obrigam a adivinhar. Aplique estas regras em todo o registro:

  • Comece com um verbo que corresponda à ação de negócio, como buscar, criar, atualizar, cancelar ou enviar.
  • Nomeie o objeto que a ação toca, como fatura, agendamento, orçamento ou remessa.
  • Evite verbos genéricos como tratar, processar, gerenciar ou executar, porque eles permitem que o modelo presuma quase qualquer coisa.
  • Mantenha uma tarefa por ferramenta. Se o nome precisar da palavra e para ser entendido, divida a ferramenta em duas.
  • Use um único padrão de nomes em todo o registro e garanta que nenhuma ferramenta possa, de forma plausível, responder ao mesmo pedido que outra.

Trate os nomes publicados como estáveis. Uma renomeação muda o comportamento que seus testes medem. Se um nome precisar mudar, registre a alteração como uma nova versão do registro e refaça os testes de escolha antes de liberar.

O que a descrição de uma ferramenta deve dizer?

A descrição é o guia de escolha que o modelo lê antes de se comprometer com uma ação. Uma descrição útil cobre cinco pontos: o que a ferramenta faz, quando usá-la, quando não usá-la, o que devolve e se altera dados ou dispara uma mensagem externa. Escreva como se estivesse orientando um funcionário novo que nunca viu seus sistemas. Evite linguagem de marketing, como poderosa ou avançada, porque ela não acrescenta informação para decidir.

Uma descrição para a ferramenta de pagamento pode dizer que ela lê o status de pagamento de uma fatura quando o usuário informa o número, que não deve ser usada para consultar dados de contato, que devolve o status e o valor em aberto e que é somente leitura. Esse único parágrafo evita a maior parte das escolhas erradas. Mencione também os requisitos de aprovação na descrição, para que o modelo não suponha que uma ferramenta de leitura também pode enviar um lembrete.

Como os esquemas de argumentos impedem chamadas vagas?

O esquema é a parte da definição da ferramenta que o harness consegue verificar. O modelo preenche os campos, o harness valida a chamada antes de qualquer execução, e uma chamada inválida devolve um erro claro que o modelo pode corrigir. Sem esquema, um pedido vago pode virar um identificador inventado ou uma data em formato errado, e a falha só aparece depois que uma ação já foi executada. Construa os esquemas com estes hábitos:

  • Tipifique cada campo como texto, número inteiro, booleano ou um conjunto fixo de valores.
  • Use enumerações para opções como status, canal ou região, para que o modelo não invente um valor novo.
  • Marque explicitamente os campos obrigatórios e mantenha os opcionais no mínimo.
  • Coloque a unidade no nome do campo, como dias_ate_vencimento, em vez de deixar um número solto.
  • Prefira identificadores estáveis, como o identificador da fatura, a nomes em texto livre quando o sistema de origem aceitar.
  • Defina limites para o tamanho de listas e textos, para que uma chamada não devolva nem envie conteúdo sem limite.

Mantenha as descrições dos campos curtas, porém precisas. Um campo descrito apenas como data deixa dúvidas sobre formato e fuso horário. Um campo descrito como data de vencimento no formato de calendário ISO 8601 deixa pouco espaço para erro. O artigo sobre saídas estruturadas mostra como o esquema funciona como um contrato que o harness pode validar.

O esquema impede chamadas malformadas. Ele não decide se quem chama tem permissão para fazê-las, e isso pertence às regras de autorização do harness.

Uma revisão antes do lançamento para nomes, descrições e esquemas

Rode esta revisão antes que qualquer mudança no registro chegue ao trabalho real. Ela leva menos tempo do que uma reunião e pega os problemas que são caros de encontrar em produção.

  • Exporte a lista completa de ferramentas exatamente como o modelo a receberá, com nomes, descrições e esquemas.
  • Verifique cada nome pela regra de uma ação e sinalize qualquer par de ferramentas cujos verbos e objetos se sobreponham.
  • Leia cada descrição em voz alta e confirme que ela informa uso, não uso, valores devolvidos e efeitos colaterais.
  • Confirme que toda ação de escrita ou externa tem uma fronteira de aprovação definida fora da descrição, para que a descrição nunca seja o único controle.
  • Valide cada esquema com uma chamada válida de exemplo e várias inválidas, e confirme que o harness recusa as inválidas com um erro legível.
  • Rode os testes de escolha descritos na seção seguinte e registre os resultados.
  • Aprove a mudança, guarde-a como versão numerada do registro e mantenha a versão anterior pronta para reversão.

Como testar qual ferramenta o modelo escolhe?

Teste a escolha, e não apenas se a ferramenta funciona. Escreva um conjunto pequeno de pedidos com as palavras que os usuários reais usam, agrupe-os pela ferramenta que deveriam acionar e inclua pedidos que não devem acionar ferramenta alguma. Execute o conjunto contra o registro atual e registre a ferramenta e os argumentos escolhidos. Escolhas erradas apontam para problemas de nome ou descrição. Argumentos inválidos apontam para problemas de esquema. O guia de avaliações da OpenAI descreve esse padrão de escrever casos, executá-los e avaliar os resultados, e a mesma lógica se aplica à escolha de ferramentas.

Comece pequeno e aumente o conjunto a partir de falhas reais, em vez de escrever uma suíte grande antes de ver como o agente se comporta. Refaça o conjunto após cada mudança no registro e guarde os resultados junto ao registro da versão. Se o registro cresce e as escolhas erradas continuam aparecendo, reduza a lista de ferramentas antes de acrescentar descrições. O artigo sobre lista de ferramentas permitidas explica como começar com menos ferramentas e ampliar apenas com evidência.

Como a Be Human trabalha o registro de ferramentas

O modelo gerenciado da Be Human começa pela definição do papel. A primeira implantação nomeia um papel útil, a memória e as ferramentas que ele precisa e a fronteira de aprovação de cada ação. Assim, nomes e descrições são escritos a partir de uma lista definida, e não de um catálogo com tudo o que os sistemas conseguem fazer. O registro de ferramentas é revisado com o dono do negócio, que julga os resultados, e com um revisor técnico, que verifica esquemas, permissões e registros. Depois, é publicado como conjunto versionado. A operação continua após o lançamento, com testes de escolha recorrentes, revisões de permissão sempre que uma ferramenta muda e resposta a incidentes quando uma ferramenta errada causa problema. As mudanças passam por lançamentos controlados, e não por edições diretas no trabalho ativo. Se não tiver certeza de qual tarefa repetitiva deve ser a primeira a ir para um agente, faça o diagnóstico gratuito de IA da Be Human para identificar essa primeira tarefa.

Perguntas frequentes

Todo nome de ferramenta deve seguir o mesmo padrão?

Sim. Um único padrão em todo o registro facilita identificar sobreposições na revisão e mantém os registros legíveis para quem investiga problemas. Escolha a forma verbo e objeto, aplique-a a todas as ferramentas e trate as exceções como bloqueios de lançamento. O estilo exato importa menos do que a capacidade de a equipe manter a consistência.

Quantas ferramentas um agente deve receber?

Dê ao agente apenas as ferramentas que o papel dele exige. Cada ferramenta extra é mais uma opção que o modelo precisa avaliar, e mais opções aumentam a chance de escolhas erradas. Comece com uma lista curta, teste e acrescente uma ferramenta só quando os testes mostrarem uma capacidade realmente faltando.

Uma descrição melhor pode corrigir uma ferramenta mal desenhada?

Às vezes ajuda, mas a descrição não consegue consertar uma ferramenta que faz duas tarefas ou aceita entradas pouco claras. Se duas ações compartilham uma ferramenta, separe-as em duas ferramentas com nomes próprios. Se um campo é ambíguo, altere o esquema e use a descrição para esclarecer quando escolher a ferramenta, e não para esconder um problema de desenho.

Quem deve revisar os nomes das ferramentas antes do lançamento?

A revisão precisa de duas perspectivas: alguém que conhece o processo de negócio e consegue julgar se cada nome e descrição corresponde ao trabalho real, e alguém que conhece o harness e consegue verificar esquemas, permissões e registros. Guarde o registro da revisão junto à versão do harness para que uma mudança posterior possa ser rastreada até a decisão que a originou.

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 →