Structured Outputs with Zod: Typed JSON from LLMs in TypeScript

import { z } from "zod";
 
export const Triage = z.object({
  category: z.enum(["billing", "bug", "account", "feature_request", "other"]),
  priority: z.enum(["low", "normal", "high", "urgent"]).describe("urgent only when the customer cannot work at all or money is being lost"),
  summary: z.string().describe("One sentence, written for a support engineer"),
  customerSentiment: z.enum(["positive", "neutral", "frustrated", "angry"]),
  orderIds: z.array(z.string()).describe("Order IDs mentioned, without the # sign; empty if none"),
  needsHuman: z.boolean().describe("true when the request needs a refund, legal answer, or account change"),
});
 
export type Triage = z.infer<typeof Triage>;

import Anthropic from "@anthropic-ai/sdk";
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
import { Triage } from "./lib/ticket-schema.ts";
 
const client = new Anthropic();
 
const ticket = `Hi, I've been charged twice for order #A-1043 and again for #A-1051 this week.
This is the third time I'm writing. Please fix it today or I'm cancelling.`;
 
const message = await client.messages.parse({
  model: "claude-opus-5-5",
  max_tokens: 2048,
  output_config: { effort: "low", format: zodOutputFormat(Triage) },
  system: "You triage customer support tickets for a billing product.",
  messages: [{ role: "user", content: `<ticket>\n${ticket}\n</ticket>` }],
});
 
const triage = message.parsed_output; // Triage | null
if (!triage) throw new Error(`No structured output (stop_reason: ${message.stop_reason})`);
 
console.log(triage.category, triage.priority, triage.orderIds);
// billing high [ 'A-1043', 'A-1051' ]  (typical output)

import Anthropic from "@anthropic-ai/sdk";
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
import { Triage } from "./ticket-schema.ts";
 
const client = new Anthropic();
const ORDER_ID = /^[A-Z]-\d{4}$/;
 
// Business rules the schema cannot express. Returns human-readable problems.
export function checkRules(t: Triage, ticket: string, knownOrders: Set<string>): string[] {
  const problems: string[] = [];
  for (const id of t.orderIds) {
    if (!ORDER_ID.test(id)) problems.push(`orderIds: "${id}" is not in the format X-0000`);
    else if (!knownOrders.has(id)) problems.push(`orderIds: "${id}" does not exist for this customer`);
  }
  if (/\b(lawyer|legal action|chargeback)\b/i.test(ticket) && !t.needsHuman) {
    problems.push("needsHuman: tickets that mention legal action or chargebacks always need a human");
  }
  return problems;
}
 
export type TriageResult = { ok: true; triage: Triage; attempts: number } | { ok: false; reason: string; attempts: number };
 
export async function triageTicket(ticket: string, knownOrders: Set<string>): Promise<TriageResult> {
  const messages: Anthropic.MessageParam[] = [{ role: "user", content: `<ticket>\n${ticket}\n</ticket>` }];
 
  for (let attempt = 1; attempt <= 2; attempt++) {
    const message = await client.messages.create({
      model: "claude-opus-5-5",
      max_tokens: 2048,
      output_config: { effort: "low", format: zodOutputFormat(Triage) },
      system: "You triage customer support tickets for a billing product.",
      messages,
    });
 
    if (message.stop_reason !== "end_turn") {
      return { ok: false, reason: `no complete output (stop_reason: ${message.stop_reason})`, attempts: attempt };
    }
    const text = message.content.flatMap((b) => (b.type === "text" ? [b.text] : [])).join("");
    const parsed = Triage.safeParse(JSON.parse(text));
 
    const problems = parsed.success
      ? checkRules(parsed.data, ticket, knownOrders)
      : parsed.error.issues.map((i) => `${i.path.map(String).join(".")}: ${i.message}`);
    if (parsed.success && problems.length === 0) return { ok: true, triage: parsed.data, attempts: attempt };
 
    // Show the model its own answer and exactly what was wrong with it.
    messages.push(
      { role: "assistant", content: message.content },
      { role: "user", content: `Your triage has problems:\n- ${problems.join("\n- ")}\nReturn a corrected triage.` },
    );
  }
  return { ok: false, reason: "business rules still failing after retry", attempts: 2 };
}

import { triageTicket } from "./lib/triage-with-rules.ts";
 
const knownOrders = new Set(["A-1043", "A-1051", "B-2210"]);
const tickets = [
  "Charged twice for #A-1043, please refund.",
  "My bank says I should file a chargeback for order B-2210 if you don't answer.",
  "Feature idea: export invoices as CSV.",
];
 
for (const ticket of tickets) {
  const result = await triageTicket(ticket, knownOrders);
  if (result.ok) console.log(result.attempts, result.triage.category, result.triage.priority, result.triage.needsHuman);
  else console.log("→ human queue:", result.reason); // the safe fallback
}

import { test } from "node:test";
import assert from "node:assert/strict";
import { checkRules } from "./lib/triage-with-rules.ts";
import type { Triage } from "./lib/ticket-schema.ts";
 
const base: Triage = {
  category: "billing", priority: "high", summary: "Double charge", customerSentiment: "frustrated",
  orderIds: ["A-1043"], needsHuman: false,
};
const known = new Set(["A-1043"]);
 
test("accepts a valid triage", () => {
  assert.deepEqual(checkRules(base, "Charged twice", known), []);
});
 
test("rejects unknown and malformed order IDs", () => {
  const problems = checkRules({ ...base, orderIds: ["A-9999", "1043"] }, "x", known);
  assert.equal(problems.length, 2);
});
 
test("requires a human for chargebacks", () => {
  assert.match(checkRules(base, "I will file a chargeback", known)[0] ?? "", /needsHuman/);
});

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const message = await client.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 2048,
  tools: [
    {
      name: "create_refund",
      description: "Create a refund request for a single order. Use only after the customer confirmed the order ID.",
      strict: true,
      input_schema: {
        type: "object",
        properties: {
          orderId: { type: "string", description: "Order ID such as A-1043" },
          reason: { type: "string", enum: ["duplicate_charge", "not_delivered", "other"] },
        },
        required: ["orderId", "reason"],
        additionalProperties: false,
      },
    },
  ],
  messages: [{ role: "user", content: "Yes, order A-1043 was the duplicate. Please refund it." }],
});
 
for (const block of message.content) {
  if (block.type === "tool_use") console.log(block.name, block.input); // input matches the schema
}