Structured output

What it is

Sometimes the consumer of the agent is another program, not a human. You need a JSON object that matches a schema, not a polite paragraph.

.output(zodSchema) tells the model to return JSON, parses it (including fenced ```json blocks), validates with Zod, and on failure sends a repair turn with the validator error.

Use when: routing tickets, extracting fields, scoring, writing to Postgres.

Do not use when: the user should read a natural-language answer. You can still parse JSON internally and render your own copy.

Usage

import { z } from "zod";

const Ticket = z.object({
  label: z.enum(["bug", "billing", "other"]),
  confidence: z.number().min(0).max(1),
  summary: z.string(),
});

const agent = Agent.builder()
  .name("classifier")
  .instructions("Classify support tickets. Return JSON only.")
  .apiKey(key)
  .output(Ticket)
  .build();

const result = await agent.run("The app crashes every time I open billing.");
const ticket = result.outputParsed as z.infer<typeof Ticket>;
await db.tickets.insert(ticket);

result.output is the JSON string (normalized). result.outputParsed is the typed object after Zod.

Failures

Default 2 repair attempts. Then OutputValidationError with the Zod (or JSON parse) message — catch it and show a fallback UI or retry the whole run.

import { OutputValidationError } from "shirube-ai";

try {
  await agent.run(text);
} catch (error) {
  if (error instanceof OutputValidationError) {
  }
}