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

Ferramentas e integrações

Como escrever descrições de ferramentas para agentes de IA como guias de trabalho

Descreva cada ferramenta de agente de IA como um guia de tarefa: finalidade, entradas, limites e falhas. Textos claros ajudam o agente a escolher certo.

Capa tipográfica do Be Human com o título: Como escrever descrições de ferramentas para agentes de IA como guias de trabalho
Ilustração conceitual criada com IA · Be Human

Para escrever descrições de ferramentas para agentes de IA, trate cada uma como um guia de tarefa: uma referência curta que diz para que a ferramenta serve, quais entradas ela exige, onde ficam seus limites e o que fazer quando ela falha. O agente lê essas descrições para escolher entre as ferramentas disponíveis. Por isso, uma frase vaga como "atualiza registros de clientes" produz chamadas erradas, enquanto uma frase precisa diz quando usar a ferramenta, quando escolher outra e quando parar e perguntar a uma pessoa.

Principais pontos

  • Comece cada descrição com a única tarefa que a ferramenta executa e as situações em que ela deve ser escolhida.
  • Liste cada entrada obrigatória com formato, origem e um exemplo de valor válido.
  • Declare os limites rígidos, incluindo o que a ferramenta não pode fazer e quais ações exigem um aprovador nomeado.
  • Descreva os casos de falha mais comuns e o próximo passo exato que o agente deve dar em cada um.
  • Mantenha descrição, esquema e conjunto de permissões alinhados, e teste tudo com pedidos realistas.

Por que a descrição é o guia de tarefa do agente

Um agente não aprende seus sistemas como um funcionário novo, ao longo de semanas. Ele vê um nome, uma descrição e um esquema de parâmetros para cada ferramenta, e decide a partir disso no momento de cada pedido. Tudo o que você deixa fora desse texto é desconhecido para o agente, então ele adivinha ou recorre a um padrão que pode estar errado para o seu negócio.

Um bom guia de tarefa é o que um operador experiente deixa ao lado da máquina. Ele cobre a tarefa comum, as exceções, o que nunca fazer e o passo a seguir quando algo inesperado aparece na tela. Descrições de ferramentas merecem a mesma disciplina. Elas são lidas em cada execução, o que faz delas o lugar mais barato para prevenir erros e o mais caro para descuidar.

Descrições também têm um lado de segurança. Documentos, e-mails e resultados de ferramentas que o agente lê podem conter textos que parecem instruções. O OWASP Top 10 para aplicações com LLM trata a injeção de prompt como um risco central por esse motivo. A descrição deve dizer com clareza que instruções encontradas dentro de dados retornados não mudam a tarefa, e que só as pessoas e regras definidas no papel podem alterar o que o agente faz.

O que toda descrição de ferramenta precisa dizer

Uma descrição completa tem quatro partes, nesta ordem:

  • Finalidade: a única tarefa que a ferramenta executa, escrita como uma ação sobre um objeto nomeado.
  • Quando usar: as situações que pedem a ferramenta, com o nome da alternativa mais próxima.
  • Entradas: cada campo obrigatório, seu formato, de onde vem o valor e como é um valor válido.
  • Limites e falhas: o que a ferramenta não pode fazer, quais ações exigem aprovação e o que cada erro significa para o próximo passo.

A linha de finalidade carrega a maior parte do peso, porque é a primeira coisa que o agente compara com o pedido do usuário. Verbos vagos como "tratar", "processar" ou "gerenciar" não dão nada para o agente casar. Compare duas descrições para uma função de contabilidade.

Cenário ilustrativo: uma equipe financeira dá a um agente duas ferramentas de fatura. A primeira descrição diz "Obtém informações da fatura." O agente não consegue saber se a ferramenta busca por cliente, por número da fatura ou por data, então às vezes chama a errada. Uma descrição revisada diz: "Retorna o status de uma fatura, identificada pelo número da fatura. Use quando o usuário informar um número de fatura. Não use para encontrar as faturas de um cliente; para isso, use a ferramenta de busca de clientes. Somente leitura. Nunca altera a fatura." Cada frase responde a uma pergunta que o agente, de outra forma, teria de adivinhar.

O nível de permissão também pertence à descrição. Uma ferramenta que redige um e-mail deve dizer que não envia, e uma ferramenta que lê um razão deve dizer que não lança nada. A diferença entre ler, rascunhar e enviar vale ser explícita, como explicado em ler, preparar e enviar: três permissões diferentes de IA.

Entradas e limites: os detalhes que evitam uso indevido

As descrições de entradas devem ser pelo menos tão rigorosas quanto o esquema permite. Diga se um identificador é o ID interno do registro ou o número que o usuário vê na tela. Informe se as datas usam um fuso horário declarado, se os valores estão na moeda do registro e se texto livre é aceito ou rejeitado. Quando um valor precisa vir de outra ferramenta, nomeie essa ferramenta. As orientações da Anthropic sobre como escrever ferramentas para agentes favorecem ferramentas estreitas, com nomes e parâmetros claros, e que devolvam contexto significativo em vez de identificadores opacos.

Os limites são a parte que as equipes mais pulam, porque parecem óbvios para quem construiu o processo. Escreva-os como fatos: o número máximo de registros por chamada, se a ferramenta escreve ou apenas lê, se repetir uma chamada é seguro, quais ações exigem um aprovador nomeado e quais horários ou canais são proibidos. Depois, garanta que a ferramenta cumpra o que a descrição promete. A descrição informa o agente, mas é a camada de permissões que bloqueia uma ação que nunca deveria acontecer.

Regras por campo pertencem ao esquema, e a redação deve coincidir com ele. O detalhe prático está em esquema de ferramentas para agentes de IA: campos tipados e erros claros, que vale ser lido junto com este artigo na hora de escrever a lista de parâmetros.

Uma descrição que não pode ser conferida contra o comportamento da ferramenta é uma esperança, não uma especificação.

Casos de falha que o agente consegue tratar

A maioria dos erros de agentes não acontece no caminho de sucesso. Acontece quando a ferramenta devolve algo que o agente não esperava. A descrição deve nomear as falhas comuns e o próximo passo para cada uma, para que o agente não improvise. A lista abaixo é um ponto de partida para a maioria das ferramentas de negócio:

  • Não encontrado: o identificador não correspondeu a nenhum registro. Peça ao usuário outro identificador. Não crie um registro novo para preencher a lacuna.
  • Correspondência ambígua: mais de um registro se encaixa. Mostre os candidatos e pergunte qual é o pretendido antes de qualquer ação.
  • Permissão negada: o agente não tem acesso para esta ação. Informe o limite e encaminhe o pedido ao responsável nomeado.
  • Limite de taxa atingido: aguarde o intervalo indicado e tente uma vez. Não entre em loop repetindo a mesma chamada.
  • Possível duplicidade: a escrita pode já ter acontecido. Leia o registro antes de qualquer nova tentativa.
  • Tempo esgotado com resultado desconhecido: verifique o status da ação antes de repetir uma escrita.

Os dois últimos itens importam mais para tudo que altera dados. Repetir uma escrita após um tempo esgotado é como aparecem faturas duplicadas e reservas em duplicidade, e a descrição é o primeiro lugar para interromper esse padrão. As mensagens de erro da ferramenta devem usar o mesmo vocabulário da descrição, para que o agente consiga relacionar os dois sem interpretar.

Checklist antes de a ferramenta entrar em operação

Antes que uma ferramenta chegue a um agente, um revisor deve conseguir responder sim para cada item a seguir:

  • A frase de finalidade nomeia uma ação sobre um objeto.
  • A frase de quando usar nomeia a alternativa mais próxima e diz quando não usar esta.
  • Cada entrada informa seu formato, sua origem e um exemplo de valor válido.
  • O nível de permissão (leitura, rascunho, envio ou escrita) está declarado e corresponde ao acesso realmente concedido.
  • Limites, aprovações e regras de taxa estão escritos na descrição e aplicados pela ferramenta.
  • Cada falha listada tem um próximo passo que o agente pode dar sem adivinhar.
  • Texto devolvido pela ferramenta é descrito como dado, não como instrução.
  • Pedidos realistas foram testados, incluindo pelo menos um pedido que não deveria usar esta ferramenta.

A ordem do trabalho importa. Escreva primeiro a finalidade e depois teste se o agente seleciona a ferramenta para pedidos reais. Só então refine as entradas e o tratamento de falhas, com base no que o agente de fato errou. Escrever todos os campos antes de testar a seleção costuma gerar descrições longas que ainda confundem o agente. As etapas gerais de aceite de uma integração estão resumidas em checklist para aceitar uma integração de agente de IA.

Como a Be Human conduz isso nas operações gerenciadas

No modelo gerenciado da Be Human, as descrições de ferramentas são escritas no primeiro engajamento, junto com o papel que atendem, a memória e as ferramentas de que esse papel precisa, seus limites de aprovação e o critério de sucesso pelo qual será medido. As descrições passam pela mesma revisão das permissões, de modo que uma mudança no que a ferramenta pode fazer também muda o que a descrição diz. Durante a operação contínua, a equipe revisa erros de seleção e chamadas falhas nos registros operacionais, atualiza as descrições onde o agente escolheu errado e registra cada mudança, para que a empresa veja por que o contexto operacional está escrito do jeito que está.

Testar descrições e mantê-las atualizadas

Descrições envelhecem. Um campo novo, um status renomeado ou uma regra de aprovação alterada podem tornar uma descrição antiga errada sem gerar nenhum erro visível. Monte um conjunto pequeno de pedidos realistas, tirados do trabalho real. Para cada um, registre qual ferramenta deve ser chamada, qual não deve ser chamada e como é um resultado correto. Execute esse conjunto após cada mudança em descrição, esquema ou permissão. As orientações da Anthropic sobre avaliações de agentes descrevem esse tipo de verificação baseada em tarefas, e o guia de evals da OpenAI explica como estruturar testes com nota. Acompanhe três coisas: se a ferramenta certa foi selecionada, se as entradas foram válidas e se as falhas foram tratadas como a descrição manda.

Guarde o conjunto de testes junto da descrição, para que um revisor veja por que cada frase existe. Revisite os dois quando o sistema subjacente mudar e depois de qualquer incidente em que o agente tenha usado a ferramenta errada ou repetido uma ação que não deveria ter repetido.

Se você ainda não sabe qual das suas tarefas diárias é a certa para começar a entregar a um agente, o diagnóstico gratuito de IA da Be Human pode ajudar a encontrá-la.

Perguntas frequentes

Qual deve ser o tamanho de uma descrição de ferramenta? Não há um tamanho fixo, mas cada descrição deve cobrir finalidade, quando usar, entradas, limites e falhas sem enrolação. Se uma descrição precisa de muitos parágrafos, a ferramenta provavelmente faz coisa demais e deve ser dividida em ferramentas mais estreitas. Frases curtas e específicas costumam funcionar melhor que frases longas e genéricas.

A descrição deve dizer ao agente o que não fazer? Sim. Orientação negativa é útil quando duas ferramentas parecem parecidas, porque nomeia a alternativa e elimina o palpite. Mantenha-a em uma frase e aplique a proibição rígida também na camada de permissões, já que a descrição orienta o comportamento, mas sozinha não bloqueia uma ação.

A mesma ferramenta pode atender vários agentes de IA? Pode, mas a descrição deve corresponder ao papel que cada agente ocupa. Um agente de relatórios somente leitura e um agente que redige faturas podem chamar o mesmo sistema subjacente, então cada um deve ver redação e permissões escritas para o próprio trabalho. Um texto compartilhado que ignora as diferenças de papel é uma fonte comum de escritas inesperadas.

Preciso ser técnico para escrever essas descrições? Você precisa saber o que o sistema faz e o que pode dar errado, e esse conhecimento costuma estar com a pessoa de operações ou financeiro que executa o processo. Um responsável técnico deve conferir o esquema e o tratamento de erros, enquanto o dono do negócio confirma que os limites e as regras de aprovação refletem como o trabalho é feito de fato.

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 →