Prompt livre ou Decisions API: quando vale pedir uma decisão em vez de um texto?

Fala aí, beleza? Pedir ‘responda só sim ou não’ num prompt é pedir uma decisão disfarçada de texto 😛

E todo mundo já fez isso, né? Eu também

Só que a OpenAI anunciou no DevDay, em 29/09/2026, a Decisions API: uma chamada feita justamente pra devolver respostas tipadas em vez de texto livre

Neste post eu comparo o hábito do prompt livre com essa chamada nova, passando pelo meio-termo (Structured Outputs), e mostro quando cada um resolve o seu problema 🙂

O que é a Decisions API da OpenAI?

A ideia é simples: em vez de pedir pro modelo escrever, você pede pra ele escolher

Ela avalia texto, imagem ou os dois juntos e escolhe entre respostas que você, desenvolvedor, definiu antes. Vive no endpoint POST /v1/decisions, e a referência oficial está no guia oficial da OpenAI

São três tipos de pergunta:

• predicate: checa uma condição e devolve uma probabilidade de 0 a 1 de ela ser verdadeira
• choice: escolhe um dos valores que você forneceu, com um score de confiança
• score: avalia a entrada contra níveis ordenados e devolve a média dos índices dos níveis, ponderada pela probabilidade

Se liga no estado atual: ela começou em preview limitado e está em beta pública desde 06/10/2026, ainda sem disponibilidade geral (GA)

E ela roda apenas no GPT-6 Luna (gpt-6-luna)

Quanto custa a Decisions API?

US$ 0,10 por 1 milhão de tokens de entrada no GPT-6 Luna

Tokens de saída, leitura e escrita de cache não são cobrados, o que faz sentido: a saída de uma decisão é curtinha, o grosso é o que você manda pra ela avaliar

Ela é rápida mesmo?

A OpenAI afirma que ela é cerca de 10x mais rápida que a Responses API

É uma afirmação da própria OpenAI, então vale medir no seu caso antes de montar arquitetura em cima disso

E a parte de conformidade?

Na beta já tem suporte a Zero Data Retention, elegibilidade HIPAA e residência de dados nos EUA e na Europa (EEE/Suíça)

Pra quem trabalha com dado sensível, isso pesa MUITO na escolha

Onde o ‘responda só sim ou não’ quebra: parsing e inconsistência

Bora ver o problema na prática? Imagina um código assim:

resposta = chamar_modelo("Este comentário é spam? Responda só sim ou não.")

if resposta == "sim":
    bloquear_comentario()
else:
    publicar_comentario()

Parece inocente, né? Pois é…

Os sintomas:

• O modelo responde ‘Sim.’, com maiúscula e ponto, e o if já não bate
• Às vezes vem ‘sim, porque o texto tem links suspeitos…’ e a comparação falha de novo
• Aí você troca o == por regex, depois por .lower().strip(), depois por um startswith, e por aí vai
• A mesma entrada, rodada duas vezes, pode receber respostas diferentes
• E o pior: não vem nenhuma medida de confiança, então você não tem como saber quando o modelo estava em dúvida

Repara no detalhe do último exemplo: o else publica tudo que não for exatamente ‘sim’

Ou seja, cada variação de texto vira um spam publicado. Tome cuidado com isso!

A causa:

Texto livre não tem contrato de formato

Você PEDIU sim ou não, mas nada obriga o modelo a cumprir. É como mandar um formulário em branco e torcer pra pessoa escrever exatamente ‘sim’ no campo certo

A solução:

Definir as opções antes, em vez de interpretar texto depois

Dá pra fazer isso de dois jeitos:

• Com a Decisions API, usando predicate (a condição é verdadeira?) ou choice (qual dessas opções?)
• Impondo um schema via Structured Outputs, que garante que a resposta segue o formato que você definiu

A lógica de trocar o prompt por decisão tipada é a mesma nos dois casos: o código para de adivinhar e passa a receber um valor que ele já sabe tratar

Como prevenir:

As boas práticas oficiais da API ajudam a não recriar o problema com outra cara:

• Separe assuntos diferentes em perguntas diferentes (não junte ‘é spam?’ com ‘é ofensivo?’ numa pergunta só)
• Dê significados distintos às opções de choice, sem duas opções que quase se sobrepõem
• Defina os níveis de score de modo que níveis vizinhos tenham critérios distintos

Se duas opções parecem a mesma coisa pra você, vão parecer pro modelo também haha

Prompt livre vs Structured Outputs vs Decisions API: comparação

Antes da tabela, um conceito rápido: o que é JSON mode?

É o modo da OpenAI que só garante JSON válido. Já o Structured Outputs garante aderência ao JSON Schema que você forneceu, e a OpenAI recomenda usar Structured Outputs em vez de JSON mode sempre que possível

No lado da Anthropic, os structured outputs do Claude usam constrained decoding: a resposta sai conforme o schema, sem erro de JSON.parse e sem retry por violação de schema

A leitura rápida: quanto mais pra direita, menos parsing você faz no seu código

E só a Decisions API devolve uma medida de confiança como parte do próprio recurso, que é o que te deixa tratar a dúvida de forma diferente da certeza

Casos de uso: predicate, choice e score na prática

Os exemplos abaixo são os que a própria documentação oficial cita, e os três casam com o que a OpenAI indica como uso dessa API: classificação rápida, roteamento e decisão do próximo passo de agentes

Predicate: a condição é verdadeira?

Exemplos da doc: dano visível numa imagem ou relevância de um trecho

Por que rende mais como decisão tipada? Porque você recebe uma probabilidade de 0 a 1, não um ‘acho que sim’

Aí quem decide o corte é o seu código: probabilidade alta segue automático, faixa do meio vai pra revisão humana. Com texto livre, essa faixa do meio simplesmente não existe

Choice: qual dessas opções?

Exemplos da doc: departamento ou categoria de conteúdo

É o roteamento clássico, tipo mandar um chamado de suporte pro time certo

Com texto livre, o modelo pode inventar um departamento que não existe no seu sistema 😛 Com choice, ele escolhe um dos valores que você forneceu, e ainda vem o score de confiança junto

Score: quão grave é?

Exemplo da doc: gravidade de um problema

Aqui você define níveis ordenados (tipo baixo, médio, alto, crítico) e recebe a média dos índices ponderada pela probabilidade

Isso é massa porque um resultado entre dois níveis já te conta que o caso está na fronteira, coisa que um rótulo seco em texto nunca diria

E nos agentes?

Decidir o próximo passo de um agente é basicamente um choice: chamar ferramenta, pedir mais informação, encerrar

Quando essa escolha vem tipada, o loop do agente fica previsível, sem aquele parsing frágil no meio do caminho

Quando o prompt livre ainda é suficiente

Nem tudo precisa virar decisão tipada, beleza? Tem cenário em que a resposta solta resolve de boa:

• Um humano lê o resultado: se ninguém faz if em cima da resposta, não tem parsing pra quebrar
• Protótipo ou volume baixo: tu ainda tá descobrindo quais são as opções, então fechar elas cedo demais atrapalha
• A resposta precisa de explicação ou nuance: um ‘sim, mas…’ bem argumentado vale mais que um booleano
• A pergunta não cabe em opções fechadas: se você não consegue listar as respostas possíveis, não tem como usar choice

Tem também o caso de a decisão precisar de outro modelo ou de outro provedor

A chamada nova roda só no gpt-6-luna e ainda está em beta. Se isso não serve pro seu projeto, o meio-termo é Structured Outputs na OpenAI ou os structured outputs da Anthropic

Você perde a probabilidade que ela devolve, mas ganha o contrato de formato. E dá pra montar um schema com um enum de opções e um campo de justificativa, o que já mata o problema do parsing

E se você está no Claude repetindo o mesmo contexto longo em cada chamada de classificação, vale entender também o cache de prompt na Claude API

De prompt solto a automação: onde a decisão tipada passa a importar

Enquanto o prompt é algo que você roda e lê, texto livre funciona

O problema aparece quando o prompt vira automação, rodando sozinho e alimentando o próximo passo sem ninguém olhando

Pra começar do zero com essa ideia de transformar prompts em automações, este vídeo do canal mostra como prompts viram automações com scheduled tasks no Antigravity:

Repara que, a partir do momento em que algo roda agendado e decide sozinho, é exatamente aí que um ‘sim’ escrito de um jeito diferente pode quebrar o fluxo inteiro…

Veredito: prompt livre ou Decisions API?

Se o seu código decide em cima da resposta, decisão tipada vence o prompt livre. Simples assim

Agora, qual decisão tipada?

• Decisions API: a opção mais direta quando dá pra usar o gpt-6-luna e aceitar o status de beta. É a única da comparação que devolve probabilidade ou confiança como parte do recurso
• Structured Outputs com strict: true: o caminho seguro e portátil quando a resposta precisa de mais campos (decisão + motivo + outros dados), ou quando você está no Claude com os structured outputs da Anthropic
• JSON mode: só garante JSON válido, e a própria OpenAI recomenda Structured Outputs no lugar sempre que possível
• Prompt livre: fica pra leitura humana e exploração

Não é que o prompt livre morreu, ele só não deveria estar no meio de um if 🙂

Próximo passo: transforme um ‘sim ou não’ do seu código em decisão tipada

Faz o teste no seu próprio projeto:

1. Procure um ponto do sistema que hoje faz parsing de ‘sim/não’ ou de uma categoria em texto livre. O erro comum aqui é achar que não tem nenhum: busque por .lower(), startswith e regex em cima de resposta de modelo
2. Liste as respostas possíveis. Se for uma condição, é predicate; se for uma escolha entre valores, é choice; se for uma escala, é score
3. Reescreva usando a Decisions API ou, se precisar de outro modelo ou provedor, com um schema strict. O erro comum deste passo é juntar dois assuntos numa pergunta só, então separe
4. Ajuste o código pra tratar a dúvida: com a chamada nova, use a probabilidade ou a confiança pra mandar os casos na fronteira pra revisão

E lembra: ela ainda não está em GA

Então vale acompanhar as mudanças antes de colocar ela em produção crítica, beleza?

Até o próximo post! 😀