Saídas estruturadas para agentes de IA: esquemas que seus sistemas aceitam
Veja como definir esquemas de saída para agentes de IA, para que os resultados sejam validados antes de chegar a sistemas de cobrança, CRM ou agenda. Passos e checagens incluídos.

Saídas estruturadas para agentes de IA são resultados em um formato fixo e legível por máquina, normalmente JSON, que seguem um esquema definido pelo sistema que vai receber os dados. Antes de um resultado chegar a um sistema de cobrança, CRM ou agenda, um validador confere tipos, campos obrigatórios, valores permitidos e regras de negócio, e então aceita, retém para revisão ou rejeita. O agente propõe, o esquema limita, e o sistema de destino recebe apenas o que consegue aceitar com segurança.
Principais pontos
- Um esquema define o que é um resultado válido antes de o agente rodar, para que os sistemas seguintes nunca precisem adivinhar o significado de um campo.
- Valide em camadas: primeiro a estrutura, depois os valores permitidos e os identificadores existentes, e por fim as regras de negócio do sistema de destino.
- Valide antes de qualquer gravação e trate uma falha como uma exceção encaminhada a um responsável com nome, não como uma nova tentativa silenciosa.
- Tire os nomes dos campos, os tipos e os campos obrigatórios da documentação do sistema que recebe, e não do que o modelo produz por acaso.
- Teste o esquema com entradas comuns e também com entradas propositalmente bagunçadas antes de qualquer agente escrever em registros reais.
O que um esquema de saída garante de fato?
Um esquema é um contrato. Ele diz quais campos um resultado precisa ter, que tipo de dado cada campo guarda, quais valores são permitidos e quais combinações são impossíveis. Ele garante forma e vocabulário. Não garante que o conteúdo seja verdadeiro. Um agente pode devolver uma fatura bem formatada com um total errado, ou um agendamento com horário válido que ninguém ofereceu. O papel do esquema é tornar visíveis os resultados malformados ou fora do escopo, para que possam ser rejeitados, enquanto outras checagens confirmam os fatos.
Muitas plataformas de modelos conseguem restringir a geração a um esquema JSON, o que reduz saídas malformadas. Trate isso como um primeiro filtro útil, e não como validação. O OWASP Top 10 para aplicações com LLM descreve a saída de um modelo como uma entrada não confiável, que precisa ser verificada antes de um componente posterior usá-la. Sua aplicação ainda precisa testar cada resultado contra as regras do sistema que vai recebê-lo.
Comece pelo sistema que recebe, não pelo modelo
Comece pelo destino. Um sistema de cobrança normalmente espera um identificador de cliente, um código de moeda, itens com quantidades e tratamento tributário, e uma data de emissão em um formato específico. Um CRM espera um identificador de contato, uma etapa do funil tirada de uma lista fixa e um responsável que exista como usuário. Um sistema de agenda espera um horário de início com fuso horário, uma duração, um recurso e nenhuma sobreposição com reservas existentes. Copie esses requisitos para o esquema exatamente como são. Se o agente inventar nomes próprios, surge uma etapa de tradução, e é na tradução que os erros se escondem.
Reúna esses detalhes de cada sistema de destino antes de escrever qualquer esquema:
- Campos obrigatórios, usando exatamente os nomes que o sistema usa
- Tipos e formatos, incluindo datas, fusos horários e precisão decimal
- Enumerações: as listas fechadas de status, categorias ou etapas
- Identificadores que precisam já existir no sistema para que uma gravação dê certo
- Regras de escrita: quais campos podem ser preenchidos na criação, quais são somente leitura e quais exigem um papel específico
Para um tratamento mais aprofundado de como definir o contrato em torno de uma ferramenta, veja Contratos de ferramentas de IA: entradas e saídas úteis. A mesma disciplina vale para as saídas: um esquema só é útil se o lado que recebe concordou com ele.
Como estruturar um esquema em três camadas?
Separe as checagens em três camadas para que uma falha indique o que deu errado.
- Forma: os campos obrigatórios existem, os tipos estão corretos, e campos desconhecidos são rejeitados em vez de descartados em silêncio.
- Vocabulário: os valores vêm de listas fechadas, e os identificadores apontam para registros reais no sistema de destino.
- Regras de negócio: os totais são iguais à soma de suas linhas, o agendamento cai dentro do horário de trabalho, o desconto não ultrapassa o limite que o aprovador definiu.
A primeira camada é barata e determinística, então rode-a primeiro e pare em caso de falha. A segunda exige uma consulta ao sistema em operação, de preferência por meio de uma visão somente leitura. A terceira é onde mora o conhecimento do domínio e onde está a maior parte do risco operacional real. Mantenha essas regras em código ou configuração que uma pessoa consiga ler e auditar, e não escondidas em um prompt que muda a cada edição.
Um plano passo a passo para validar antes de gravar
Use esta sequência para cada ação que o agente pode executar:
- Defina o esquema para uma única ação, como criar um rascunho de fatura ou propor um horário na agenda, em vez de um esquema genérico para o sistema inteiro.
- Escreva o esquema a partir da documentação do sistema de destino e, em seguida, peça para a pessoa responsável por esse sistema revisá-lo.
- Confira cada saída do agente primeiro na camada de forma, e devolva os erros ao agente apenas se uma nova tentativa for permitida.
- Resolva cada identificador e cada valor enumerado no sistema em operação antes de ler as regras de negócio.
- Execute as regras de negócio e produza uma única decisão: aceitar, reter para revisão ou rejeitar com um motivo em linguagem simples.
- Envie apenas os resultados aceitos para a etapa de gravação, e inclua uma chave de idempotência para que uma nova tentativa não crie um segundo registro.
- Registre juntos a entrada, a saída proposta, o resultado da validação e o desfecho da gravação, para que qualquer registro possa ser rastreado depois.
Fornecedores documentam esse padrão. A API da Stripe, por exemplo, aceita chaves de idempotência para que uma requisição repetida não repita a ação. Para entender como desenhar essas chaves para as suas próprias ações, leia Idempotência em agentes de IA: evite ações duplicadas.
O que acontece quando um resultado falha na validação?
Decida antes o que cada tipo de falha provoca. Uma falha de esquema normalmente significa que o agente entendeu mal o pedido, então uma nova tentativa, com os erros específicos de validação incluídos, é razoável. Uma falha de consulta, como um identificador de cliente que não existe, não deve ser repetida às cegas, porque a mesma consulta vai falhar de novo. Ela deve ir para uma pessoa ou para uma etapa de busca criada para esse fim. Uma falha de regra de negócio é uma decisão, não um bug. Um desconto acima do limite pertence a quem aprova descontos.
O agente nunca deve ajustar a própria saída para passar em uma regra que falhou. Defina um limite de novas tentativas e, ao atingi-lo, mova o item para uma fila de revisão com a entrada original, a saída tentada e o texto do erro. Execuções agendadas precisam do mesmo tratamento, que é coberto em Tarefas agendadas para agentes de IA: execuções, retentativas e alertas.
Como a Be Human trata isso: em um projeto gerenciado, a Be Human desenha cada esquema junto com o responsável pelo sistema que recebe, implementa o validador como parte da camada de ferramentas do agente e limita as permissões de escrita a resultados que já foram aceitos. O monitoramento acompanha as rejeições por campo e por regra, de modo que uma mudança de formato do fornecedor ou uma regra de negócio alterada aparece como um padrão visível, e não como uma surpresa no financeiro. Revisões periódicas de permissões e mudanças controladas no esquema mantêm o contrato atualizado conforme os sistemas ao redor mudam.
Cenário ilustrativo: um agendamento que não cabe
Cenário ilustrativo: uma empresa de serviços de campo usa um agente para transformar mensagens de clientes em visitas propostas. Uma mensagem pede uma visita no domingo. A saída do agente contém um horário de início sem fuso horário, e o identificador do técnico que ele produziu não existe no sistema de agenda. A checagem de forma rejeita o fuso horário ausente antes que qualquer outra coisa rode. Em seguida, a consulta confirma que o identificador do técnico é inválido. Nada é gravado. O pedido, os dois erros e a mensagem original do cliente vão para o despachante, que escolhe manualmente um técnico disponível e confirma o horário com o cliente. O agente não falhou em silêncio, e o sistema de agenda nunca recebeu um agendamento que não podia ser feito.
Teste o esquema antes que ele toque em registros reais
Monte um conjunto de testes com pedidos reais do passado e inclua casos propositalmente difíceis: campos faltando, mensagens escritas em dois idiomas, datas no formato dia-mês e mês-dia, valores com separador de milhar e envios duplicados. Rode o agente contra esse conjunto após cada mudança no prompt, no modelo ou no esquema. Avalie os resultados da validação, e não apenas se o texto parece bem escrito. As orientações da Anthropic sobre como escrever ferramentas para agentes destacam a importância de testar como os agentes realmente usam uma ferramenta, porque as falhas que importam costumam estar nos detalhes das entradas e saídas. Use esta lista antes de colocar em produção:
- Todo campo obrigatório está presente, ou a saída é rejeitada.
- Campos desconhecidos são rejeitados, não removidos discretamente.
- Datas incluem fuso horário e seguem exatamente o formato do sistema de destino.
- Campos de dinheiro seguem a precisão e as regras de arredondamento do sistema de cobrança.
- Um pedido repetido gera a mesma chave de idempotência, e não um segundo registro.
- Todo caso rejeitado chega a uma pessoa com nome e com um motivo claro.
Se você não tem certeza de qual das suas tarefas é a melhor para começar a validar desta forma, o diagnóstico gratuito de IA da Be Human ajuda a encontrar a primeira tarefa que vale a pena entregar a um agente.
Perguntas frequentes
Ainda preciso de validação se o modelo oferece saídas estruturadas? Sim. A geração restrita a um esquema reduz JSON malformado, mas não consegue confirmar que um identificador de cliente existe, que um desconto está dentro da política ou que um horário está livre. Sua aplicação precisa de checagens próprias contra o sistema de destino antes de qualquer gravação. Trate o recurso da plataforma como o primeiro filtro e o seu validador como a barreira de entrada.
O esquema deve ficar no prompt ou no código? Mantenha o esquema em código ou em configuração versionada. Um esquema dentro do prompt é difícil de testar, fácil de alterar por acidente e invisível para as pessoas que são donas do sistema de destino. Quando o esquema é um arquivo sob controle de versão, você consegue revisá-lo, testá-lo e reverter quando o sistema de destino muda.
O que acontece quando o sistema que recebe muda seus campos? O esquema precisa mudar junto, por meio de uma revisão controlada, e não de uma edição rápida. Monitore as rejeições por campo para que um campo renomeado ou um novo campo obrigatório apareça como padrão dentro do ciclo normal de revisão. Pause as gravações dessa ação até que o esquema seja atualizado e o conjunto de testes seja executado de novo.
Um esquema consegue pegar fatos errados? Só em parte. Um esquema pode confirmar que um valor está bem formado, é permitido e é coerente com as regras que você registrou, e uma consulta pode confirmar que um registro existe. Ele não consegue confirmar que o cliente realmente pediu a visita de domingo. Para fatos que importam, adicione uma etapa de revisão ou uma segunda fonte, e mantenha no registro a proposta do agente e as evidências que ele usou.
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.


