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
mode | Como | Custo 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. |
extract | Um 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-chave | Uso |
|---|---|
type | string, number, integer, boolean, object ou array — ou ["string", "null"] para aceitar null. A raiz é sempre um object. |
properties, required | Os campos de um objeto, e quais deles precisam estar presentes. Todo objeto declara os seus campos. |
items | O que uma lista contém (obrigatório em array). |
enum | Valores permitidos de um campo de texto ou número (até 50). |
description | O que um campo significa — o modelo o lê no modo extract. |
minimum, maximum, minLength, maxLength, minItems, maxItems | Limites 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
}| Campo | Padrão | Descrição |
|---|---|---|
provider | openrouter | openrouter 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. |
input | o estado inteiro | A mensagem do usuário: até 8.000 caracteres. |
temperature | 0 | 0 a 2. |
maxTokens | 1024 | 16 a 4.096. |
timeoutMs | 20000 | 1.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 é:
| Caso | output |
|---|---|
Um destino json concluiu | O objeto dele — o primeiro, na ordem do schema, quando vários dispararam. |
Destinos json dispararam, nenhum concluiu | null |
Nenhum destino json disparou | ausente |
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:
| Componentes | Uso |
|---|---|
Card, Stack, Grid, Separator | Layout. |
Heading, Text, Badge, Alert | Texto e status. |
Table, Image, Avatar, Progress | Dados e mídia. |
Button, Link | Ações (on.press). |
| Ação | Params | Significado |
|---|---|---|
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:
- O
autoFixSpecdo json-render corrige erros comuns de modelos (umvisibledentro deprops, um filho que não existe). - A estrutura precisa se sustentar: uma raiz que existe, filhos que existem, tipos de componente conhecidos.
- As props são conferidas por componente com o schema dele — props desconhecidas são recusadas.
- Ações: só
replyeopen_url, num evento que o componente tem (press), com params válidos. - URLs —
Link.href,Image.src,Avatar.src,open_url— precisam serhttps://(nada de linksjavascript:, nada de rastreamento por http simples). - Só valores finais: nada de
repeat, condições de visibilidade ou expressões$state;classNameé semprenull. 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 zodimport { 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
templatesempre rodam (são gratuitos); destinosextractmostram 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
outputquando a decisão armazena as saídas (storeOutput); comstoreOutput: false, ele guarda apenas se a saída foi montada. - Os SDKs a expõem como
decision.output— em TypeScript, tipada comdcision.decide<Result, Output>(…).
Respostas fixas
Devolva uma mensagem pronta — texto e botões opcionais, com variáveis — na resposta da API para um determinado resultado, na hora e sem chamar nenhum modelo.
Respostas de LLM
Deixe um modelo responder por uma rota — a Dcision chama o OpenRouter ou o Vercel AI Gateway com a chave do seu próprio workspace, o prompt da rota como mensagem de sistema e o estado como entrada.