Saídas estruturadas para agentes de IA

Texto convincente ainda pode quebrar o processo

Um agente lê uma conversa comercial e deve devolver estágio, objeção, prioridade e próxima ação. A resposta parece correta para uma pessoa. Para o CRM, porém, o estágio veio com um nome inexistente, a data está em formato ambíguo e o campo de evidência ficou vazio.

O modelo produziu linguagem útil. A integração recebeu dados que não consegue usar com segurança.

Saída estruturada é o contrato que organiza o resultado de uma etapa para que outra pessoa, regra ou sistema consiga interpretá-lo de forma previsível. Esse contrato define campos, tipos, valores permitidos, estados de ausência e evidências obrigatórias.

O schema resolve a forma. A operação ainda precisa validar significado, autoridade e consequência. JSON válido pode carregar cliente errado, valor impossível ou decisão sem fonte.

Quando a saída estruturada é necessária

Texto livre funciona bem para rascunhos, explicações e materiais que serão lidos integralmente por uma pessoa. A estrutura passa a ser necessária quando o resultado alimenta outra etapa.

Use um contrato explícito quando a saída:

atualiza CRM, ERP, sistema financeiro ou plataforma de atendimento;
cria tarefas, alertas, documentos ou registros;
define uma rota do workflow;
aciona uma ferramenta;
passa por aprovação humana;
alimenta cálculo, painel ou relatório;
precisa ser comparada entre versões;
será processada em volume;
exige trilha de evidência;
pode gerar consequência para cliente, dinheiro ou dado.

Um resumo para leitura pode aceitar variação. Uma instrução para emitir cobrança precisa de campos, limites e confirmação. O nível de estrutura deve acompanhar a consequência.

Schema, validação e regra de negócio são camadas diferentes

As três camadas costumam ser confundidas.

Schema

Define a forma esperada:

campos obrigatórios;
tipo de cada campo;
valores enumerados;
tamanho mínimo e máximo;
objetos e listas permitidos;
campos adicionais aceitos ou proibidos;
representação de ausência;
versão do contrato.

Validação sintática

Confirma se a saída respeita o schema. Verifica, por exemplo, se prioridade pertence à enumeração, se prazo usa a data esperada e se evidencias é uma lista.

Validação operacional

Confirma se o conteúdo faz sentido para aquele processo. Verifica se o cliente existe, se a oportunidade está ativa, se o prazo cabe na política, se a fonte possui autoridade e se a ação respeita a alçada.

O schema impede que uma data chegue como parágrafo. Ele não confirma que a data está correta. A regra operacional precisa consultar o contexto e a fonte oficial.

Comece pela decisão que consumirá o resultado

Um schema desenhado a partir do que o modelo consegue gerar tende a acumular campos interessantes e pouca utilidade. Comece pela etapa seguinte.

Pergunte:

Quem ou qual sistema recebe a saída?
Que decisão será tomada com ela?
Quais campos são indispensáveis para essa decisão?
Que evidência permite conferir cada conclusão?
Quais estados de ausência e conflito precisam aparecer?
Que erro deve bloquear o fluxo?
Que erro permite correção ou revisão?

Considere uma triagem de atendimento. A etapa seguinte precisa decidir entre responder, pedir informação ou escalar. Uma saída útil pode conter:

categoria;
urgencia;
cliente_id;
intencao_identificada;
dados_ausentes;
trechos_de_evidencia;
rota_recomendada;
motivo_da_rota;
revisao_obrigatoria.

Adicionar um campo genérico chamado analise_completa devolve texto longo e transfere a decisão para o consumidor. Estrutura boa reduz ambiguidade na interface entre etapas.

Modele ausência, conflito e incerteza

Muitos contratos só descrevem o caso feliz. Quando falta informação, o modelo tenta preencher o campo para satisfazer o schema.

Crie estados explícitos:

confirmado;
ausente;
conflitante;
inaplicavel;
ilegivel;
fora_de_escopo;
requer_revisao.

Use null somente quando seu significado estiver definido. Campo vazio pode indicar ausência na fonte, falha de extração, falta de permissão ou erro técnico. Essas causas exigem tratamentos diferentes.

Também evite obrigar uma classificação final quando as evidências não sustentam a escolha. Permitir sem_classificacao com motivo verificável costuma ser mais seguro que forçar o modelo a selecionar a categoria mais próxima.

A página sobre como reduzir alucinações de IA mostra por que reconhecer falta de informação protege a operação.

Faça enumerações refletirem o sistema oficial

Valores livres criam variações difíceis de reconciliar. Um agente pode devolver em negociação, negociação, proposta em análise e aguardando decisão para um CRM que aceita somente proposta_enviada ou negociacao.

As enumerações devem vir do domínio oficial. Registre o código estável e, quando útil, um rótulo legível. Não permita que o agente invente um novo estágio para acomodar um caso.

Quando a classificação disponível não representa a realidade, a saída deve marcar a exceção. O dono do processo decide se a taxonomia precisa mudar. Atualizar o sistema por improviso do modelo esconde uma decisão de gestão dentro da integração.

Exija evidência junto da conclusão

Para decisões relevantes, cada conclusão precisa apontar para o que a sustenta.

A evidência pode incluir:

identificador da fonte;
trecho exato;
campo do sistema consultado;
data e versão do registro;
evento que originou a interpretação;
regra aplicada;
cálculo reproduzível;
confirmação do destino.

Em um agente comercial, risco_de_perda: alto tem pouco valor isolado. A saída melhora quando inclui o compromisso vencido, a última interação, a objeção registrada e a regra que elevou o risco.

Evidência permite revisão e ajuda a separar erro de interpretação, contexto incompleto e fonte desatualizada. O guia sobre artefatos auditáveis em IA detalha como transformar execução em algo que uma pessoa consegue conferir.

Separe extração, interpretação e decisão

Um único objeto pode misturar fatos extraídos, interpretação do modelo e decisão da política. Depois, ninguém sabe qual parte pode ser tratada como verdade.

Organize a saída em blocos distintos:

Fatos observados

Campos copiados ou extraídos das fontes, acompanhados de referência.

Interpretações

Classificações, resumos e inferências produzidas pelo modelo.

Validações

Resultados de regras determinísticas, consultas e conferências.

Decisão operacional

Rota final permitida pela política: seguir, corrigir, pedir informação, revisar ou bloquear.

Essa separação facilita investigação. Se a rota ficou errada, a equipe consegue descobrir se o fato foi extraído incorretamente, se a interpretação falhou ou se a política estava desatualizada.

Valide antes de produzir consequência

A saída precisa atravessar uma sequência conhecida antes de atualizar sistemas.

Receber o objeto e a versão do schema.
Validar sintaxe, tipos e campos obrigatórios.
Rejeitar campos adicionais não autorizados.
Normalizar somente transformações determinísticas aprovadas.
Validar identificadores, estados e valores contra fontes oficiais.
Conferir política, permissão e alçada.
Calcular risco e necessidade de revisão.
Registrar a decisão da validação.
Executar a ação autorizada.
Confirmar o efeito no sistema de destino.

Os hooks em agentes de IA podem aplicar controles antes e depois de ferramentas. O agente propõe uma atualização estruturada; o ambiente confere o contrato e a autoridade antes da escrita.

Reparo automático precisa de teto

Uma saída pode falhar por aspas inválidas, campo ausente, enumeração incorreta ou estrutura incompleta. Algumas falhas admitem reparo controlado.

Use uma sequência curta:

informe ao modelo os erros específicos de validação;
envie somente o contexto necessário para corrigir;
preserve o mesmo identificador de execução;
limite quantidade, tempo e custo das correções;
valide novamente desde o início;
encaminhe a exceção quando o teto acabar.

Não peça uma nova resposta completa sem dizer o que falhou. Isso pode corrigir a estrutura e alterar campos que já estavam certos.

Também não permita reparo para violação de política, identidade incerta ou ação externa ambígua. Esses casos exigem bloqueio, reconciliação ou revisão. A política de retentativas em agentes de IA ajuda a separar falha recuperável de insistência inútil.

Versione o contrato de saída

Schemas mudam quando o processo ganha campos, regras ou estados. Uma alteração aparentemente simples pode quebrar consumidores, testes e registros históricos.

Mantenha:

identificador e versão do schema;
data de entrada em vigor;
responsável pela mudança;
consumidores compatíveis;
regra de migração;
período de convivência entre versões;
exemplos válidos e inválidos;
testes de regressão;
procedimento de rollback.

Adicionar campo opcional costuma ser menos arriscado que renomear um campo usado. Alterar o significado de uma enumeração sem mudar a versão é especialmente perigoso: a estrutura continua válida e a interpretação muda silenciosamente.

O controle de mudanças para agentes de IA deve incluir contrato, validadores, consumidores e dashboards na mesma liberação.

Preserve o objeto original e a decisão aplicada

Para auditoria, guarde o necessário para reconstruir a passagem:

saída original do modelo;
versão do modelo e das instruções;
versão do schema;
erros de validação;
correções solicitadas;
objeto validado;
regras operacionais aplicadas;
campos alterados por normalização;
decisão final;
ação executada;
confirmação do destino;
ator humano, quando houve revisão.

A política de retenção precisa limitar dados sensíveis. Referências protegidas podem substituir cópias integrais de conversas e documentos.

Alterações silenciosas são um problema. Se um validador remove um destinatário, reduz um valor ou troca uma categoria, a mudança precisa aparecer na evidência e no estado da unidade.

Teste o contrato com casos difíceis

Inclua exemplos que pressionem forma e significado:

campo obrigatório ausente;
campo adicional inesperado;
enumeração próxima, mas inválida;
número enviado como texto;
data ambígua;
objeto truncado;
lista vazia quando existe mínimo operacional;
identificador de outro cliente;
fonte vencida;
duas fontes em conflito;
fato ausente com classificação forçada;
evidência que não sustenta a conclusão;
reparo que altera campo já aprovado;
versão antiga consumida por fluxo novo;
resposta válida com ação fora da alçada.

Meça o comportamento completo: detecção, correção, bloqueio, encaminhamento e ausência de consequência indevida. O guia sobre como avaliar agentes de IA organiza casos de regressão por responsabilidade.

Métricas para operar saídas estruturadas

Acompanhe:

aprovação sintática na primeira tentativa;
falhas por campo e versão;
reparos por unidade;
sucesso depois do reparo;
falhas de validação operacional;
classificações sem evidência;
conflitos encaminhados;
alterações humanas por campo;
ações bloqueadas;
erros que chegaram ao sistema de destino;
tempo e custo da validação;
quebra de consumidor depois de mudança;
reincidência por versão do agente.

Uma alta taxa de JSON válido pode conviver com decisões ruins. O indicador importante é a proporção de objetos que produzem uma decisão ou registro correto, com evidência suficiente e sem retrabalho oculto.

Checklist de implementação

[ ] A etapa consumidora e sua decisão estão definidas?
[ ] O schema contém apenas campos úteis para essa decisão?
[ ] Tipos, enumerações e limites refletem o sistema oficial?
[ ] Ausência, conflito e fora de escopo possuem estados próprios?
[ ] Fatos, interpretações, validações e decisão estão separados?
[ ] Conclusões relevantes carregam evidência?
[ ] Validação sintática acontece antes da operacional?
[ ] Identidade, permissão, alçada e estado são conferidos?
[ ] Reparos possuem erro específico, contador e teto?
[ ] Casos sensíveis saem do reparo automático?
[ ] Schema e consumidores são versionados juntos?
[ ] Alterações do validador ficam visíveis?
[ ] A ação externa recebe confirmação do destino?
[ ] Testes cobrem forma válida com significado errado?
[ ] Métricas mostram qualidade do objeto e impacto no processo?

Estrutura útil termina em decisão segura

Saídas estruturadas criam uma fronteira clara entre interpretação probabilística e operação verificável. Elas permitem que o modelo lide com linguagem variável enquanto sistemas e pessoas recebem campos conhecidos, evidência e estados de exceção.

O ganho aparece quando o contrato representa a decisão real, a validação consulta fontes oficiais e a consequência continua subordinada a política e autoridade. Assim, uma resposta deixa de ser apenas legível e passa a sustentar trabalho confiável.