Saídas Estruturadas em IA: como gerar respostas confiáveis em JSON

O que são saídas estruturadas em IA?

Saídas estruturadas são respostas geradas por um modelo de IA conforme uma estrutura definida pela aplicação.

Em vez de receber um texto livre e tentar descobrir onde estão as informações importantes, o sistema determina antecipadamente quais campos devem existir, seus tipos e quais valores são permitidos.

Imagine um sistema que analisa currículos e precisa devolver nome, competências, anos de experiência e nível de aderência à vaga.

Uma resposta em prosa pode ser agradável para leitura humana, mas é ruim para automação.

Com um contrato estruturado, cada informação chega em uma posição previsível.

A documentação de Structured Outputs da OpenAI descreve o recurso como uma forma de fazer a resposta aderir a um JSON Schema fornecido. A documentação da Anthropic apresenta a mesma ideia para resultados JSON e parâmetros de ferramentas validados.

A sintaxe e o conjunto de recursos suportados variam entre provedores, mas o princípio é semelhante: transformar o formato esperado em uma restrição processável.

Por que pedir “responda em JSON” não basta?

Um prompt é uma instrução, não necessariamente uma garantia. Quando você escreve “responda apenas em JSON”, o modelo pode seguir o pedido na maioria das vezes, mas ainda inserir uma explicação antes do objeto, usar uma chave inesperada ou produzir um tipo incompatível.

Quanto mais complexo for o formato, maior tende a ser a chance de variação.

JSON válido não é contrato cumprido

Este objeto é um JSON válido: {"score":"alto"}. Entretanto, ele não serve para uma aplicação que espera score como número entre zero e cem.

Validade sintática significa apenas que o texto pode ser interpretado como JSON. Aderência ao schema significa que nomes, tipos, campos obrigatórios e relações também respeitam o contrato.

Onde o formato costuma quebrar

• campos obrigatórios são omitidos quando a informação não aparece no texto;
• valores numéricos chegam como strings;
• nomes de propriedades mudam entre português e inglês;
• valores livres aparecem onde a aplicação esperava uma enumeração;
• comentários ou blocos Markdown envolvem o JSON;
• objetos extras são criados porque o modelo tenta “ajudar”.

Em uma conversa, essas diferenças podem ser toleráveis. Em uma API REST que precisa trocar dados de forma previsível, elas se transformam em erros de parsing, ramificações especiais e tentativas repetidas.

Como JSON Schema define o contrato da resposta

JSON Schema é uma linguagem declarativa usada para descrever e validar documentos JSON.

Segundo o projeto oficial JSON Schema, um schema permite definir estrutura, restrições e tipos de dados de maneira compreensível por pessoas e máquinas.

Propriedades, tipos e campos obrigatórios

Em um objeto, properties descreve as chaves conhecidas. Cada chave pode ter um tipo, como string, number, boolean, array ou outro object.

A lista required informa quais propriedades precisam aparecer. Já enum restringe um valor a um conjunto fechado de opções.

Controle de campos adicionais

Quando suportado, additionalProperties: false impede que o objeto receba chaves que não foram declaradas. Isso reduz surpresas e ajuda a detectar mudanças de contrato.

Alguns provedores exigem essa configuração em objetos usados no modo estrito; outros aceitam apenas um subconjunto do padrão. Por isso, o schema deve ser validado contra a documentação do modelo escolhido.

Como as saídas estruturadas funcionam

O fluxo começa quando a aplicação envia ao provedor a instrução da tarefa e o schema esperado.

A API transforma essa estrutura em restrições para a geração. Em implementações baseadas em decodificação restrita, o modelo é conduzido a escolher apenas sequências compatíveis com a gramática permitida pelo schema.

1. A aplicação define o contrato: campos, tipos, opções permitidas e estrutura dos objetos.
2. O modelo recebe a tarefa e o formato: o prompt explica o que deve ser produzido; o schema define como o resultado deve chegar.
3. A geração respeita as restrições suportadas: tokens incompatíveis com a estrutura deixam de ser opções válidas.
4. O SDK ou a aplicação interpreta o resultado: o JSON pode ser convertido para um objeto tipado.
5. As regras do domínio são verificadas: valores, permissões e consistência continuam sob responsabilidade do sistema.

Esse processo combina bem com engenharia de contexto: o contexto entrega as informações necessárias para responder, enquanto o schema determina a forma que a resposta deve assumir. Um não substitui o outro.

Exemplo prático com JSON Schema

Considere uma aplicação que classifica chamados de suporte. Ela precisa de uma categoria, uma prioridade, um resumo e uma indicação sobre a necessidade de atendimento humano. Um schema simplificado poderia ser:

{
  "type": "object",
  "properties": {
    "categoria": {
      "type": "string",
      "enum": ["acesso", "cobranca", "erro_tecnico", "outro"]
    },
    "prioridade": {
      "type": "string",
      "enum": ["baixa", "media", "alta"]
    },
    "resumo": {
      "type": "string"
    },
    "requer_atendimento_humano": {
      "type": "boolean"
    }
  },
  "required": [
    "categoria",
    "prioridade",
    "resumo",
    "requer_atendimento_humano"
  ],
  "additionalProperties": false
}

Uma resposta compatível seria:

{
  "categoria": "acesso",
  "prioridade": "alta",
  "resumo": "Usuário não consegue entrar após redefinir a senha.",
  "requer_atendimento_humano": true
}

O ganho não está apenas em receber chaves organizadas. A aplicação sabe que prioridade terá uma das três opções previstas e que a decisão de encaminhamento será booleana.

Se o código usa tipagem em TypeScript, bibliotecas como Zod podem aproximar o schema usado na API do tipo consumido pelo restante do sistema.

Saída estruturada, JSON mode e function calling

Recurso	O que controla	Uso mais comum	Limite principal
Pedido no prompt	A intenção de formato	Protótipos e respostas flexíveis	Não garante JSON nem schema
JSON mode	JSON sintaticamente válido	Quando qualquer objeto JSON é suficiente	Pode não cumprir campos e tipos esperados
Saída estruturada	Resposta conforme um schema suportado	Extração, classificação e objetos para sistemas	Não valida a verdade nem todas as regras do negócio
Function calling	Nome da ferramenta e argumentos	Executar funções, consultar sistemas e acionar fluxos	Exige implementação e autorização da ação no código

Saída estruturada e function calling são complementares. A primeira organiza o que o modelo responde; a segunda descreve como ele solicita que uma função seja executada.

Em fluxos com agentes, argumentos estritos ajudam a proteger a fronteira entre a decisão do modelo e a ação realizada pela aplicação.

Quando usar saídas estruturadas em IA

O recurso faz mais sentido quando a resposta será consumida por código, e não apenas lida por uma pessoa. Bons casos incluem:

• extrair campos de documentos, e-mails, currículos ou notas fiscais;
• classificar mensagens por tema, urgência ou risco;
• preencher componentes de interface com dados previsíveis;
• gerar etapas de um fluxo de automação;
• normalizar informações recebidas em linguagem natural;
• produzir relatórios com seções fixas;
• devolver parâmetros para ferramentas e agentes;
• integrar um modelo a APIs, filas ou bancos de dados.

A documentação de saídas estruturadas do Gemini, por exemplo, apresenta schemas para classificação e extração de dados.

Isso ilustra uma regra prática: quanto mais previsível precisar ser o consumo da resposta, maior o valor de um contrato explícito.

Quando o recurso não resolve sozinho

Um schema controla a forma, não o conhecimento do modelo. Ele pode obrigar o campo preco a ser numérico, mas não garante que o preço foi extraído do produto correto.

Também não verifica se uma data existe no calendário, se um usuário possui permissão ou se uma recomendação respeita uma política interna.

Saídas estruturadas também não eliminam alucinações. Se o modelo não tiver contexto suficiente, poderá preencher uma estrutura perfeita com conteúdo incorreto.

Nesse cenário, é melhor permitir um estado explícito como informacao_indisponivel ou um campo anulável do que forçar uma resposta inventada.

Para respostas destinadas somente à leitura humana, um schema rígido pode acrescentar complexidade sem benefício.

Texto livre continua adequado para explicações, brainstorming e conversas nas quais estrutura fixa não é necessária.

Por que a validação continua necessária

Mesmo quando o provedor promete aderência ao schema, a aplicação deve manter validações na fronteira de entrada.

A resposta pode ser interrompida por limite de saída, recusada por segurança, afetada por indisponibilidade ou produzida por um modelo que não suporta todos os recursos declarados.

Validação sintática, estrutural e semântica

• Sintática: confirma se o conteúdo pode ser interpretado como JSON.
• Estrutural: verifica campos, tipos, enumerações e demais regras do schema.
• Semântica: avalia regras do domínio, como datas possíveis, faixas permitidas, referências existentes e coerência entre campos.
• Autorização: impede que um objeto formalmente válido execute uma ação que o usuário não poderia realizar.

Essa separação segue a mesma lógica dos guardrails em IA: diferentes camadas controlam entradas, resultados e ações. Confiar apenas no formato é concentrar segurança demais em uma única barreira.

Como tratar recusas, interrupções e erros

Um fluxo robusto diferencia erro técnico, resposta recusada e conteúdo inválido. Tratar tudo como “JSON quebrado” dificulta observabilidade e pode disparar tentativas inúteis.

• Recusa: verifique o indicador específico fornecido pela API e não tente converter a mensagem de recusa para o objeto de negócio.
• Interrupção por limite: detecte o motivo de término antes de fazer o parse; aumente o limite ou reduza a resposta quando apropriado.
• Schema incompatível: valide o schema no desenvolvimento e registre claramente o erro retornado pelo provedor.
• Falha transitória: use repetição com limite, espera progressiva e idempotência quando a operação puder ser repetida.
• Falha semântica: encaminhe para correção, nova tentativa orientada ou revisão humana, de acordo com o risco.

Também é importante registrar versão do schema, modelo, motivo de término, latência e resultado da validação. Não registre dados pessoais ou conteúdo sensível sem uma política adequada.

Boas práticas para criar o schema

• Comece pelo consumidor: defina o que a aplicação realmente precisa, não tudo que o modelo poderia gerar.
• Use nomes claros: propriedades ambíguas aumentam o risco de conteúdo semanticamente errado.
• Descreva campos: descrições curtas ajudam o modelo a entender significado, unidade e critérios.
• Prefira enumerações estáveis: categorias fechadas evitam pequenas variações de escrita.
• Modele ausência explicitamente: decida entre campo anulável, estado conhecido ou objeto de erro.
• Evite profundidade desnecessária: schemas muito aninhados ficam mais difíceis de manter, testar e migrar.
• Feche objetos quando possível: proibir propriedades extras reduz mudanças silenciosas.
• Não misture apresentação e domínio: retorne dados; deixe o front-end decidir rótulos, cores e formatação.

Também vale gerar o schema a partir de tipos usados pela aplicação quando o SDK oferece essa integração.

Isso reduz divergências entre a definição enviada ao modelo e o objeto esperado pelo código. Ainda assim, revise o resultado, porque cada provedor pode suportar apenas parte das palavras-chave do JSON Schema.

Performance, custo e versionamento

Schemas extensos aumentam o tamanho da requisição e podem elevar o custo de entrada.

Alguns provedores também compilam uma gramática na primeira utilização de uma estrutura, acrescentando latência inicial e reaproveitando o resultado em chamadas seguintes.

A implementação exata deve ser conferida na documentação da API utilizada.

Evite alterar o schema a cada solicitação quando a estrutura poderia ser estável. Além de facilitar cache e observabilidade, versões fixas tornam regressões mais fáceis de identificar.

Uma estratégia simples é manter schema_version nos metadados internos da chamada ou na configuração do serviço.

Mudanças incompatíveis, como renomear uma propriedade ou trocar seu tipo, devem ser tratadas como uma nova versão de contrato.

Durante a migração, o consumidor pode aceitar duas versões por um período controlado, em vez de alterar produtor e consumidores ao mesmo tempo sem proteção.

Segurança e privacidade

Dados estruturados são fáceis de encaminhar para outras partes do sistema — e exatamente por isso exigem cuidado.

Nunca transforme automaticamente a resposta do modelo em consulta, comando, transferência financeira ou alteração de permissão. Faça validação, autorização e, para ações sensíveis, confirmação humana.

Trate strings retornadas pelo modelo como dados não confiáveis. Escape conteúdo antes de renderizar HTML, use consultas parametrizadas e mantenha listas permitidas para operações.

Se o modelo analisou conteúdo externo, considere também riscos de injeção de prompt: um schema válido não neutraliza uma instrução maliciosa presente na fonte.

Na privacidade, minimize os campos enviados e armazenados. Um schema bem desenhado ajuda porque deixa explícito quais dados são necessários, mas a equipe ainda precisa aplicar retenção, controle de acesso, mascaramento de logs e as regras adequadas ao contexto.

Como testar antes de colocar em produção

Testar três exemplos felizes não é suficiente. Crie um conjunto que inclua entradas incompletas, contraditórias, muito longas, multilíngues e fora do escopo.

Inclua também casos nos quais o modelo deve declarar ausência de informação.

1. valide automaticamente todas as respostas contra o schema;
2. aplique regras semânticas separadas;
3. meça taxa de sucesso sem nova tentativa;
4. acompanhe recusas, truncamentos e erros por tipo;
5. compare modelos e versões usando o mesmo conjunto de casos;
6. teste mudanças de prompt e schema antes de liberar;
7. revise amostras do conteúdo, não apenas a validade estrutural.

Esse processo pode ser incorporado a evals de modelos e agentes. A validação estrutural vira uma métrica objetiva, enquanto avaliadores adicionais verificam precisão, completude e segurança.

Erros comuns ao implementar saídas estruturadas

• Achar que JSON mode e schema estrito são equivalentes: JSON válido ainda pode ter formato inesperado.
• Criar um schema gigantesco: o contrato passa a representar toda a aplicação e se torna difícil de evoluir.
• Forçar preenchimento: sem opção para “desconhecido”, o modelo pode inventar um valor para satisfazer o tipo.
• Confiar na estrutura como prova de verdade: a resposta pode estar perfeitamente formatada e factualmente errada.
• Ignorar o motivo de término: tentar analisar uma resposta interrompida produz diagnóstico incorreto.
• Executar ações diretamente: argumentos válidos ainda precisam de autorização e regras do domínio.
• Não versionar o contrato: uma mudança simples quebra consumidores sem deixar clara a causa.
• Testar apenas no console: produção inclui concorrência, limites, falhas de rede e entradas imprevisíveis.

Perguntas frequentes

Saída estruturada garante que a resposta está correta?

Não. Ela aumenta a confiabilidade do formato, mas não garante que os valores sejam verdadeiros, completos ou coerentes com o negócio. Conteúdo e estrutura precisam ser avaliados separadamente.

Todo modelo aceita JSON Schema?

Não. O suporte depende do provedor, do modelo e da versão da API. Mesmo quando existe suporte, normalmente há um subconjunto de recursos e limites de complexidade que devem ser conferidos na documentação atual.

Ainda preciso validar o JSON na aplicação?

Sim. A validação local protege a fronteira do sistema, facilita o diagnóstico e permite aplicar regras semânticas que não pertencem ao schema ou não são suportadas pelo provedor.

O schema pode ter campos opcionais?

Depende da implementação. Alguns modos estritos exigem que todas as propriedades declaradas sejam obrigatórias e representam ausência com tipos anuláveis. Modele essa possibilidade de forma explícita conforme as regras da API escolhida.

Saídas estruturadas substituem function calling?

Não. A saída estruturada organiza a resposta final; function calling permite ao modelo solicitar a execução de uma ferramenta. Um fluxo pode usar os dois: parâmetros estritos para a ferramenta e um objeto estruturado como resultado.

O que fazer quando o modelo recusar a solicitação?

Verifique o campo ou estado de recusa retornado pela API e trate-o fora do objeto de negócio. A aplicação pode explicar a limitação ao usuário, solicitar uma entrada diferente ou encaminhar o caso, sem tentar forçar o parse.

Conclusão

Saídas estruturadas aproximam modelos generativos das expectativas de um sistema tradicional: contratos claros, tipos previsíveis e falhas tratáveis.

Elas são muito mais confiáveis do que apenas pedir JSON no prompt e reduzem uma classe inteira de erros de integração.

O uso responsável, porém, mantém responsabilidades bem separadas. O schema controla o formato; o modelo produz o conteúdo; a aplicação valida regras, autoriza ações, protege dados e observa o comportamento em produção.

Quando essas camadas trabalham juntas, a IA deixa de ser uma caixa de texto isolada e passa a participar de fluxos de software com muito mais segurança.