Generate structured output

Use structured output when an application needs a stateless, machine-readable response instead of free-form text. The Agent can still use its configured Tools and extensions while the response is constrained by your JSON Schema.

Outcome

You will define a two-field schema, inspect partial values as they arrive, await the settled object, and verify its fields.

Before you begin

You need an Agent ID, a backend SDK client, and a small schema that represents the application boundary. Review Structured output, Generation and streaming, and Prompts before introducing reusable prompt content.

Define the schema

Keep the first schema narrow. This example requires a category and a Boolean escalation decision, rejects extra properties, and uses only JSON Schema features accepted by the platform's schema converter.

Start object generation

Call client.object() with one literal prompt. The same method also accepts a stored promptId and variables instead of prompt.

import assert from "node:assert/strict";
const result = await client.object({
  agentId,
  prompt: "Triage: I was charged twice and need help today.",
  schema: {
    type: "object",
    properties: {
      category: { enum: ["billing", "technical", "other"] },
      escalate: { type: "boolean" },
    },
    required: ["category", "escalate"],
    additionalProperties: false,
  },
});
for await (const partial of result.partialObjectStream) {
  console.log("Partial:", partial);
}
const final = await result.object;
if (typeof final !== "object" || final === null) throw new Error("Expected an object");
assert.ok("category" in final && "escalate" in final);
assert.ok(typeof final.category === "string");
assert.ok(["billing", "technical", "other"].includes(final.category));
assert.equal(typeof final.escalate, "boolean");

Read partial and final output

partialObjectStream yields parsed snapshots of incomplete JSON. Fields can be absent until later chunks; use them for progressive display, not as a settled application result. result.object resolves only after the stream completes and server-side structured-output validation settles.

Verify the object

The assertions confirm that category is one of the schema's three allowed values and that escalate is Boolean. The SDK returns the final value as unknown, so narrow it or validate it at your application boundary before domain use.

Production notes

Prefer small schemas that the selected model supports reliably. Invalid or unsupported JSON Schema is rejected before generation.
A model or transport failure can terminate the partial stream. Invalid final JSON, schema settlement failure, or a stream failure rejects result.object; do not treat the latest partial value as the final result.
Replace the literal prompt with a reusable Prompt when multiple calls share the same instruction.

See Structured output, Generation and streaming, and Prompts.

SDK and REST reference

See client.object(), POST /v1/agents/:agentId/generation, and the Agent endpoints. The shared wire shape is documented under Objects and schemas.

On this page