Structured output

Structured output is stateless object generation through the shared Agent generation endpoint. Use it when downstream code needs JSON constrained during model execution, rather than free-form text that your application attempts to parse afterwards.

When to use structured output

client.object fits extraction, classification, and other bounded results with a known shape. It creates no Session or transcript, but it is still a quota-gated, metered Turn and can use the Agent's configured capabilities.

Schema-constrained generation

Pass a JSON Schema object containing at least type or properties. At the HTTP boundary, Blazing Agents rejects non-object, empty match-anything, invalid, unresolvable, or unsupported schemas. The server compiles accepted JSON Schema with Zod's JSON Schema compiler and supplies it to model-constrained generation.

That compiler defines the accepted feature set; do not assume every JSON Schema keyword or reference form is supported. Consult objects and schemas for the exact contract.

Stream partial objects

result.partialObjectStream parses the accumulated JSON text and emits cumulative progress values. A partial may omit required fields or contain an unfinished string, so use it only for progressive display or observation—not as a valid final result.

Await and validate the final object

The public SDK type of result.object is Promise<unknown>. Await the terminal parsed object, then validate it at the application boundary to obtain a trusted application type.

import { z } from "zod";

const Triage = z.object({
  category: z.enum(["billing", "technical", "other"]),
  urgent: z.boolean(),
  summary: z.string(),
});

const result = await client.object({
  agentId,
  prompt: "Triage: I was charged twice and need a refund today.",
  schema: {
    type: "object",
    properties: {
      category: { enum: ["billing", "technical", "other"] },
      urgent: { type: "boolean" },
      summary: { type: "string" },
    },
    required: ["category", "urgent", "summary"],
    additionalProperties: false,
  },
});

for await (const partial of result.partialObjectStream) {
  console.log("partial", partial);
}
const triage = Triage.parse(await result.object);
console.log(triage.category);

The partial values are progress only; triage is the validated terminal value.

Errors, limits, and settlement

An invalid schema is a pre-stream invalid_request. If the terminal text is not valid JSON, result.object rejects with stream_error; transport failure and abort also prevent a successful final object. Model-constrained validation completes before the server settles the Turn.

Success, failure, and cancellation record usage. Structured generation creates no Session, saves no transcript, and cannot publish Session-owned Artifacts.

Prompts and Version Pins

Use promptId plus its exact variables instead of prompt to reuse a stored Prompt. Supply version to Pin this one stateless Turn; without it, execution resolves the Agent's latest Version.