Structured output

Get data your code can use directly instead of prose you have to parse. You give the agent a JSON Schema, and the model's answer is held to that shape while it is generated. Use it for extraction, classification, routing, and any other result with a known structure.

Generate an object

This example triages a support message into a category, an urgency flag, and a summary:

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,
  },
});

const triage = Triage.parse(await result.object);
console.log(triage.category, triage.urgent);

In TypeScript, result.object resolves to unknown, so validate it with your own schema, here Zod, before you use it. In Python, pass a Pydantic model as output_type: the SDK sends its JSON Schema and returns a validated instance. You can also pass a raw schema as json_schema to get plain JSON back.

Show progress while it streams

Long objects can take a while. You can show progress as the JSON arrives, then use only the final value:

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

TypeScript gives you partial objects parsed from the JSON so far. Python gives you the raw JSON text. Either way, a partial value can miss required fields or end mid-string, so use it for display only and never as a fallback result.

Write a schema that works

The schema must be a JSON Schema object with at least type or properties. An empty schema, an invalid one, or one that uses features the model cannot enforce is rejected with validation_failed before anything runs. Keep schemas small and specific: list required fields, use enum for fixed choices, and set additionalProperties: false. See objects and schemas for the supported features.

What to expect

• No history. Structured output creates no session and saves no transcript, so the agent cannot publish artifacts during it. Everything else about the agent applies, including its tools.
• Usage is recorded whether the request succeeds, fails, or is stopped.
• Invalid final JSON fails. If the answer does not parse, result.object rejects with stream_error, and Python raises a stream error. A dropped connection or abort also ends without a final object.
• Saved prompts and versions. Pass promptId with its variables instead of prompt to use a saved prompt, and version to run a specific agent version.

Next

• Generation and streaming for free-form text and chat.
• object() in the TypeScript SDK and Python SDK.