TOON structured mode

​

Why TOON?

• 30–60 % fewer tokens compared to pretty-printed JSON for tabular payloads.
• Explicit schema header (collection[length]{fields}) acts as a guardrail for the model.
• Single code path for generation + parsing thanks to @toon-format/toon.
• Decoder now coerces numeric tokens into strings when the schema expects strings (handy for IDs such as SIRET/SIREN).

​

Enabling TOON

​

Default on an agent

import { Agent } from "@ai_kit/core";
import { Output } from "@ai_kit/core/agents";
import { z } from "zod";
import { openaiProvider } from "@ai-sdk/openai";

const siretOutput = Output.object({
  schema: z.object({
    siret: z.string().length(14, "Must contain 14 digits."),
  }),
});

const assistantSiret = new Agent({
  name: "assistant_siret",
  instructions:
    "You find SIRET identifiers by combining web search and business directories.",
  model: openaiProvider("gpt-4.1-mini"),
  tools: {
    web_search: openaiProvider.tools.webSearch({}),
  },
  toon: true, // default to TOON for every generate() call
});

const result = await assistantSiret.generate({
  prompt:
    'Find the SIRET of "Aidalinfo". Return only the 14-digit ID as a string.',
  structuredOutput: siretOutput,
});

console.log(result.experimental_output);
// -> { siret: "38347481400100" }

​

Override per call

await assistantSiret.generate({
  prompt: "Return a free-form summary instead of a structured ID.",
  structuredOutput: freeformOutput,
  toon: false, // fallback to regular structured generation
});

​

Prompt behavior

1. Builds a schema example from your structuredOutput and injects it into the system prompt inside a ```toon block.
2. Instructs the model to produce only that block, keeping [N] equal to the number of rows.
3. Parses the response with @toon-format/toon, coerces numeric literals into strings when the schema wants strings, and finally validates via Zod.

​

Limitations & tips

• agent.stream does not support TOON yet—stick to agent.generate.
• Always pass a structuredOutput; TOON is ignored otherwise.
• Keep short instructions telling the model how to reference the TOON block (e.g., “quote IDs exactly as shown”).
• Log token savings by comparing JSON.stringify length with the resulting TOON block to measure impact.
• Need raw conversion utilities? Use the upstream @toon-format/toon package or CLI locally.