Saída estruturada

Devolva um objeto JSON que o seu sistema usa como está, ou uma tela que o seu app renderiza — montado a partir do resultado (sem modelo) ou por um LLM, sempre conferido antes de sair da Dcision.

Uma decisão responde perguntas: result, confidence e a action. Um destino de saída estruturada (json) também devolve um objeto pronto para o seu sistema — o ticket a abrir, o pedido a atualizar, o lead a criar — e o confere com os campos que você define antes de ele sair da Dcision.

Ele volta no output de nível superior da resposta:

{
  "result": { "route": "support", "priority": "high" },
  "action": "continue",
  "output": { "awb": "1Z999AA10123456784", "team": "support", "priority": 3, "summary": "Package is 3 days late" },
  "destinations": [
    { "key": "ticket", "type": "json", "mode": "template", "status": "completed", "output": { "awb": "1Z999AA10123456784", "team": "support", "priority": 3, "summary": "Package is 3 days late" } }
  ]
}

Duas formas de preenchê-lo

modeComoCusto e latência
template (padrão)Um template JSON com variáveis — o estado, as respostas, os níveis ponderados, os composites e os params.Grátis, instantâneo: nenhuma chamada a modelo.
extractUm LLM lê o estado e preenche os campos, com a sua chave da OpenRouter ou do Vercel AI Gateway — como nas respostas de LLM.Os tokens do provedor; quem chama espera (conta como uma das 3 chamadas que fazem quem chama esperar).

Use template quando os valores já existem — no estado ou nas respostas. Use extract quando eles estão escondidos em texto: um número de pedido num e-mail, um nome numa mensagem de chat.

Os campos

O schema é um objeto JSON Schema, o mesmo formato que os provedores de LLM usam para saídas estruturadas:

{
  "type": "object",
  "properties": {
    "awb": { "type": "string", "description": "The tracking number" },
    "team": { "type": "string", "enum": ["sales", "support", "billing"] },
    "priority": { "type": "integer", "minimum": 1, "maximum": 4 },
    "items": { "type": "array", "items": { "type": "string" }, "maxItems": 10 },
    "note": { "type": ["string", "null"] }
  },
  "required": ["awb", "team"]
}
Palavra-chaveUso
typestring, number, integer, boolean, object ou array — ou ["string", "null"] para aceitar null. A raiz é sempre um object.
properties, requiredOs campos de um objeto, e quais deles precisam estar presentes. Todo objeto declara os seus campos.
itemsO que uma lista contém (obrigatório em array).
enumValores permitidos de um campo de texto ou número (até 50).
descriptionO que um campo significa — o modelo o lê no modo extract.
minimum, maximum, minLength, maxLength, minItems, maxItemsLimites de números, textos e listas.

Campos que não estão no schema não são aceitos. Limites: até 3 níveis de objetos aninhados, 50 campos no total e 8 KB de schema; a saída em si tem até 16 KB. No editor, Campos da saída monta o schema linha a linha; a aba JSON Schema o mostra como JSON, e você pode colar um ali.

Modo template

O template é JSON com variáveis, codificado como o body de uma requisição de API: fora de aspas, uma variável vira um valor JSON; dentro de aspas, vira texto.

{
  "key": "ticket",
  "type": "json",
  "when": { "conditions": [{ "field": "route", "on": "output", "operator": "eq", "value": "support" }] },
  "params": { "awb": { "from": "state.awb", "required": true } },
  "json": {
    "mode": "template",
    "schema": { "type": "object", "properties": { "awb": { "type": "string" }, "team": { "type": "string" }, "priority": { "type": "number" }, "summary": { "type": "string" } }, "required": ["awb", "team"] },
    "template": "{\"awb\": {{params.awb}}, \"team\": {{result.route}}, \"priority\": {{scores.priority}}, \"summary\": \"Customer said: {{state.message}}\"}"
  }
}
  • Texto vindo do estado não quebra o JSON: aspas e quebras de linha são escapadas onde quer que a variável esteja.
  • Segredos não podem ser usados — a saída volta para quem chama. {{secrets.NAME}} é recusado quando você salva.
  • Ao salvar, o template precisa ser JSON válido com valores de exemplo e ter os campos obrigatórios. Preencher a partir dos campos, no editor, escreve um template inicial: um campo com o mesmo nome de um campo do estado, de uma pergunta, de um composite ou de um param lê esse valor.

Modo extract

"json": {
  "mode": "extract",
  "schema": { "type": "object", "properties": { "order_id": { "type": "string" }, "customer": { "type": "string" }, "request": { "type": "string", "enum": ["refund", "exchange", "tracking"] } }, "required": ["order_id", "request"] },
  "provider": "openrouter",
  "model": "openai/gpt-5-mini",
  "instructions": "Extract the order this customer is writing about.",
  "input": "{{state.message}}",
  "temperature": 0,
  "maxTokens": 1024,
  "timeoutMs": 20000
}
CampoPadrãoDescrição
provideropenrouteropenrouter ou vercel — a chave salva em Configurações → Engine.
model—O ID do modelo no provedor. Escolha um que suporte saídas estruturadas (JSON Schema).
instructions—O que extrair (mensagem de sistema): até 8.000 caracteres. Variáveis permitidas, sem segredos.
inputo estado inteiroA mensagem do usuário: até 8.000 caracteres.
temperature00 a 2.
maxTokens102416 a 4.096.
timeoutMs200001.000 a 25.000, retries incluídos.

A Dcision envia o schema no modo strict de saída estruturada do provedor (response_format: json_schema). O modo strict exige todos os campos, então os campos opcionais vão como anuláveis e os nulls que o modelo escreve para eles são removidos antes da validação. Se a resposta ainda assim não se encaixar — JSON inválido, um valor fora do enum, um campo faltando — a Dcision a devolve uma vez com os problemas, dentro do mesmo timeoutMs.

Quando falha

Uma saída estruturada nunca faz a decisão falhar. O item volta com "status": "failed", um error e, quando o objeto não confere, os issues:

{
  "key": "ticket",
  "type": "json",
  "mode": "template",
  "status": "failed",
  "error": "The output doesn't match the schema.",
  "issues": [{ "path": "/awb", "message": "Must not be null." }]
}

issues[].path é um JSON Pointer para o valor (/items/2). O output de nível superior é:

Casooutput
Um destino json concluiuO objeto dele — o primeiro, na ordem do schema, quando vários dispararam.
Destinos json dispararam, nenhum concluiunull
Nenhum destino json disparouausente

Telas (json-render)

Com "format": "ui", a saída é uma tela em vez de dados: uma spec do json-render — cards, textos, badges, tabelas, botões — que o seu app renderiza nativamente. Ela responde a quem chama com uma interface, não só com um valor: o status do pedido com um botão Falar com o suporte, o resumo do lead com um link Agendar uma demo.

"json": {
  "format": "ui",
  "mode": "template",
  "template": "{\"root\": \"card\", \"elements\": {\"card\": {\"type\": \"Card\", \"props\": {\"title\": \"Order {{state.awb}}\"}, \"children\": [\"status\", \"talk\"]}, \"status\": {\"type\": \"Badge\", \"props\": {\"text\": {{result.route}}}, \"children\": []}, \"talk\": {\"type\": \"Button\", \"props\": {\"label\": \"Talk to support\"}, \"children\": [], \"on\": {\"press\": {\"action\": \"reply\", \"params\": {\"text\": \"support\"}}}}}}"
}

Uma tela é { "root", "elements" }: um mapa plano de elementos, cada um com um type, props, children (chaves de elementos) e on opcional (evento → ação). A saída volta completa — todas as props de cada componente, null quando não usadas.

O catálogo

As telas usam o catálogo da Dcision — um subconjunto exato dos componentes shadcn do json-render, com as mesmas props:

ComponentesUso
Card, Stack, Grid, SeparatorLayout.
Heading, Text, Badge, AlertTexto e status.
Table, Image, Avatar, ProgressDados e mídia.
Button, LinkAções (on.press).
AçãoParamsSignificado
reply{ "text": "…" }Envia o texto de volta como a próxima mensagem do usuário — uma resposta rápida.
open_url{ "url": "https://…" }Abre uma URL.

Como a Dcision confere uma tela

Toda tela — de um template ou de um LLM — passa pelas verificações do próprio json-render e pelo reforço de segurança da Dcision:

  1. O autoFixSpec do json-render corrige erros comuns de modelos (um visible dentro de props, um filho que não existe).
  2. A estrutura precisa se sustentar: uma raiz que existe, filhos que existem, tipos de componente conhecidos.
  3. As props são conferidas por componente com o schema dele — props desconhecidas são recusadas.
  4. Ações: só reply e open_url, num evento que o componente tem (press), com params válidos.
  5. URLs — Link.href, Image.src, Avatar.src, open_url — precisam ser https:// (nada de links javascript:, nada de rastreamento por http simples).
  6. Só valores finais: nada de repeat, condições de visibilidade ou expressões $state; className é sempre null. No máximo 60 elementos e 32 KB.

No modo extract, o modelo recebe o prompt de catálogo do json-render mais as suas instruções; se a tela dele não passar numa verificação, a Dcision devolve os problemas uma vez. Templates são conferidos quando você salva, com valores de exemplo.

Renderizar

npm install @json-render/core @json-render/react @json-render/shadcn zod
import { defineCatalog } from "@json-render/core";
import { JSONUIProvider, Renderer, defineRegistry } from "@json-render/react";
import { schema } from "@json-render/react/schema";
import { shadcnComponents } from "@json-render/shadcn";
import { shadcnComponentDefinitions as d } from "@json-render/shadcn/catalog";
import { z } from "zod";

const names = ["Card", "Stack", "Grid", "Separator", "Heading", "Text", "Badge", "Alert", "Table", "Image", "Avatar", "Progress", "Button", "Link"] as const;
const catalog = defineCatalog(schema, {
  components: Object.fromEntries(names.map((name) => [name, d[name]])),
  actions: {
    reply: { params: z.object({ text: z.string() }), description: "Quick reply" },
    open_url: { params: z.object({ url: z.string() }), description: "Open a URL" },
  },
});
const { registry } = defineRegistry(catalog, {
  components: Object.fromEntries(names.map((name) => [name, shadcnComponents[name]])),
  actions: { reply: async () => {}, open_url: async () => {} },
});

export function DecisionScreen({ decision, send }) {
  return (
    <JSONUIProvider
      registry={registry}
      handlers={{
        reply: async ({ text }) => send(text),
        open_url: async ({ url }) => window.open(url, "_blank", "noopener"),
      }}
    >
      <Renderer spec={decision.output} registry={registry} />
    </JSONUIProvider>
  );
}

O json-render também renderiza a mesma spec com React Native, React Email, React PDF e outros alvos — mapeie os mesmos nomes de componentes lá.

No Playground e nos logs

  • No Playground, destinos template sempre rodam (são gratuitos); destinos extract mostram o prompt e o schema strict que seriam enviados ("status": "preview"), a menos que você execute os destinos de verdade. As telas são renderizadas, e pressionar um botão mostra a ação que ele enviaria.
  • O log de execuções guarda o output quando a decisão armazena as saídas (storeOutput); com storeOutput: false, ele guarda apenas se a saída foi montada.
  • Os SDKs a expõem como decision.output — em TypeScript, tipada com dcision.decide<Result, Output>(…).

Nesta página