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

Fundamentos de harness

Saídas estruturadas para agentes de IA: esquemas que o harness valida

Aprenda a definir esquemas de saída para agentes de IA para que o harness valide os resultados e barre dados malformados antes de cobrança, e-mail ou sistemas.

Capa tipográfica do Be Human com o título: Saídas estruturadas para agentes de IA: esquemas que o harness valida
Ilustração conceitual criada com IA · Be Human

Uma saída estruturada é o resultado de um agente com formato fixo: campos nomeados, tipos declarados, valores obrigatórios e listas fechadas de opções permitidas, escritos para que uma máquina possa conferir o conteúdo antes que qualquer outro sistema o leia. Para que essa conferência seja útil, defina um esquema para cada ação que o agente pode produzir, faça o harness rejeitar qualquer resultado que não corresponda ao esquema e envie os resultados rejeitados para uma nova tentativa ou para uma pessoa, nunca para os sistemas seguintes. As seções abaixo explicam como escrever esses esquemas e o que o harness deve fazer quando um deles falha.

Principais pontos

  • Defina um esquema de saída para cada ação que o agente pode executar, e não um formato genérico para tudo.
  • Verifique tipos, campos obrigatórios e valores permitidos no harness antes que qualquer sistema receba o resultado.
  • Trate uma validação com falha como uma parada com motivo registrado, nunca como texto a ser corrigido em silêncio.
  • Versione cada esquema e teste-o com casos reais do passado, inclusive os que deram errado.
  • Comece pela ação cujo dano seria maior se um único campo estivesse errado.

Por que o texto livre vira risco quando o software depende da resposta

Quando um agente responde em texto corrido, uma pessoa lê a resposta e preenche pequenas lacunas por conta própria. Um sistema de cobrança, uma agenda, um CRM ou um disparador de e-mails não consegue fazer isso. Ele precisa de um valor no campo certo, de um identificador de cliente que exista, de uma data em um formato declarado e de um status tirado de uma lista conhecida. Se o agente escreve a data de forma ambígua ou coloca o nome do cliente onde deveria haver um identificador, a etapa seguinte falha de um jeito confuso ou tem sucesso sobre o registro errado.

Modelos de linguagem produzem texto plausível, então um resultado pode parecer correto e, ainda assim, não ser utilizável. O Top 10 da OWASP para aplicações com LLM inclui o tratamento inadequado de saídas como categoria de risco por esse motivo: uma saída do modelo repassada adiante sem verificação pode disparar ações em outros sistemas. O esquema é o lugar mais simples para começar a fechar essa brecha, porque transforma a esperança de que a resposta está certa em um teste que roda sempre.

Desenhe o esquema em torno da ação, não do modelo

Comece pelo que o sistema seguinte vai fazer com o resultado. Ele pode enviar uma mensagem, criar ou atualizar um registro, reservar um horário, mudar um status ou gravar um arquivo. Cada uma dessas ações tem entradas obrigatórias próprias. Uma ação de lembrete precisa de uma referência ao destinatário, um código de modelo de mensagem, uma janela de envio e um código de motivo. Uma atualização de status precisa do identificador do registro, do status anterior, do novo status e de uma referência à evidência que o agente usou.

Escreva um esquema por ação. Evite um único objeto de resultado que carregue todos os campos possíveis marcados como opcionais, porque campos opcionais escondem informação faltante. Um esquema pequeno é mais fácil de testar, de revisar e de versionar quando o negócio muda. As notas de engenharia da Anthropic sobre como escrever ferramentas para agentes fazem um ponto parecido sobre definições de ferramentas: quanto mais claros forem os parâmetros e sua finalidade, menos chamadas erradas o agente faz.

Regras de campo que pegam erros reais

A maior parte da validação útil vem de um conjunto curto de regras aplicadas campo a campo:

  • Tipo: uma quantidade é um número, uma data é uma data em um formato declarado, e um identificador é um texto que segue um padrão conhecido.
  • Obrigatório: marque um campo como obrigatório quando a ação seguinte não pode rodar sem ele, e proíba o agente de inventar um valor provisório para preenchê-lo.
  • Valores permitidos: use uma lista fechada para status, canais e códigos de motivo, para que um rótulo novo ou escrito errado falhe de forma clara.
  • Limites: defina valores mínimos e máximos, e um tamanho máximo para qualquer texto livre que vá chegar a um cliente.
  • Referências: exija um identificador que o harness consiga consultar, para que a ação aponte para um registro real e não para um nome que o agente lembrou.
  • Evidência: para cada alteração, inclua a referência da fonte em que o agente se apoiou, para que um revisor consiga conferir a base.

Um esquema não decide se o conteúdo é sensato. Uma mensagem bem formada ainda pode ser a mensagem errada, e esses julgamentos pertencem às regras de aprovação e às avaliações recorrentes. O guia de guardrails para agentes de IA nas empresas explica quais controles adicionar primeiro.

Um plano passo a passo para escrever e testar um esquema

Siga esta sequência para uma ação antes de passar para a próxima:

  • Nomeie a ação, o gatilho que a inicia e o sistema que recebe o resultado.
  • Liste os campos mínimos que esse sistema precisa, com tipo, formato e se cada um é obrigatório.
  • Substitua cada campo de texto livre que dirige uma decisão por uma lista fechada de valores.
  • Monte um conjunto de casos passados, incluindo deliberadamente vários que foram tratados mal antes.
  • Rode o agente com esses casos e registre quais saídas falham na validação e a regra que cada uma quebrou.
  • Confirme que cada falha corresponde a uma regra do esquema, e peça a uma pessoa que revise as saídas aprovadas para confirmar que elas também estão corretas para o negócio.
  • Versione o esquema, escreva uma nota curta de release e teste a nova versão em uma cópia de homologação antes da produção.

As duas últimas etapas são as mais importantes. Um esquema que passa nos testes, mas deixa passar um cliente errado, está só parcialmente pronto. O guia sobre como escrever um contrato de tarefa de IA mostra como transformar os mesmos casos em um contrato que sua equipe pode rodar de novo depois de cada mudança.

O que o harness faz quando a validação falha

A rejeição precisa de um caminho definido. Um resultado com falha nunca deve chegar ao sistema seguinte, e nunca deve ser editado discretamente até passar. Um padrão comum é uma nova tentativa, em que o harness envia o erro de validação de volta ao agente junto com o pedido original. Isso costuma resolver um campo faltante ou um formato errado. Se a nova tentativa também falhar, a tarefa vai para uma fila de revisão com a saída original, a versão do esquema, a regra que falhou e a entrada que gerou o problema.

Falhas repetidas na mesma ação são um sinal para mudar o prompt, a ferramenta ou o esquema, e não para afrouxar a verificação. As novas tentativas também exigem cuidado com efeitos colaterais. Se um resultado passa, mas o envio falha no meio do caminho, uma nova tentativa não pode enviar duas vezes. A documentação da Stripe sobre requisições idempotentes descreve a abordagem de um provedor para tornar chamadas repetidas seguras, e o mesmo princípio vale para qualquer ação disparada por um agente: o sistema receptor precisa conseguir reconhecer uma duplicata.

Cenário ilustrativo: um agente de lembretes que quase enviou a mensagem errada

O cenário a seguir é ilustrativo e não descreve um cliente real. Uma pequena equipe financeira deixa um agente redigir e enfileirar lembretes de pagamento. Na primeira versão, o agente devolvia uma frase contendo o nome do cliente, a fatura em atraso e um dia sugerido para envio. Uma pessoa copiava essa frase para o disparador, e o nome do cliente era parecido o suficiente com o de outro cliente para que o lembrete errado pudesse ser enviado.

Na versão revisada, o agente devolve um identificador de cliente, um identificador de fatura, um código de modelo de uma lista fechada e uma janela de envio. O harness rejeita qualquer resultado em que a fatura não pertença ao cliente e rejeita qualquer código de modelo que não esteja na lista. Nos testes, o esquema revelou um caso em que a ferramenta de consulta devolveu uma fatura de uma conta encerrada. A correção foi feita na ferramenta de consulta, e foi o esquema que tornou essa divergência visível antes de a mensagem entrar na fila.

Onde a abordagem gerenciada da Be Human se encaixa

A Be Human projeta, implementa e opera essa camada como parte de uma infraestrutura de IA personalizada. Um primeiro projeto começa escolhendo uma função útil, depois define o esquema de saída de cada ação que essa função pode executar, a fronteira de aprovação para ações que exigem uma pessoa e o critério de sucesso que o harness consegue observar. A operação gerenciada mantém esses esquemas funcionando ao longo do tempo: monitora falhas de validação, roda avaliações recorrentes com casos passados, mantém as integrações que recebem os resultados, revisa permissões quando um esquema muda e trata incidentes quando uma saída ruim chega perto de um sistema em produção. As mudanças são entregues como atualizações controladas e versionadas, para que cada uma possa ser revisada e revertida. Equipes que estão avaliando se devem fazer isso por conta própria podem comparar o trabalho contínuo em agentes de IA para empresas sem equipe de TI, que mostra o que manter internamente e o que delegar.

Se você não tem certeza de qual das suas tarefas com agentes deveria receber primeiro um esquema rigoroso, faça o diagnóstico gratuito de IA da Be Human para descobrir a primeira tarefa que vale a pena entregar a um agente.

Perguntas frequentes

O que é uma saída estruturada para um agente de IA? É um resultado que segue um formato fixo, com campos nomeados, tipos declarados e valores permitidos, para que o software consiga lê-lo sem adivinhar. Um harness confere cada resultado com o esquema antes que qualquer sistema seguinte aja sobre ele. O objetivo é tornar visíveis os resultados errados ou incompletos na fronteira, onde são baratos de pegar.

Se o modelo já devolve JSON, ainda preciso de um esquema? Sim. JSON válido só prova que a sintaxe está correta, não que os valores fazem sentido. Um esquema acrescenta campos obrigatórios, valores permitidos, faixas e referências a registros que precisam existir, e essas verificações pegam erros que uma checagem de sintaxe não alcança.

Qual esquema devo escrever primeiro? Comece pela ação em que um campo errado causaria mais dano, normalmente aquela que altera cobranças, registros de clientes, comunicação com o público externo ou permissões de acesso. Teste esse esquema com casos reais do passado antes de escrever os demais. O primeiro ensina sua equipe a escrever os outros.

Quem deve ser responsável pelos esquemas? O responsável pela operação deve definir o que cada campo significa e quais valores são permitidos, enquanto o responsável técnico aplica as verificações e gerencia as versões. Ambos devem revisar qualquer mudança antes que ela chegue à produção. A operação gerenciada da Be Human pode manter esses esquemas, monitorar falhas e revisar mudanças conforme o negócio evolui.

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 →