Structured Outputs & Tool Calling

Terminal

npm install ai zod
# Only if you also call the Claude API directly:
npm install @anthropic-ai/sdk

lib/triage.ts

import { generateText, Output } from 'ai';
import { z } from 'zod';

const ticketSchema = z.object({
  category: z.enum(['billing', 'bug', 'feature-request', 'other']),
  urgency: z.number().int().min(1).max(5).describe('5 = on fire'),
  summary: z.string().describe('One sentence, plain English'),
  customerEmail: z.string().email().nullable(),
});

const emailBody = 'Hi, I was charged twice this month...';
const { output } = await generateText({
  model: 'anthropic/claude-haiku-4.5',
  output: Output.object({ schema: ticketSchema }),
  prompt: `Triage this support email:\n\n${emailBody}`,
});

// output is fully typed: output.category is 'billing' | 'bug' | ...
if (output.urgency >= 4) {
  console.log('Page someone:', output.summary);
}

lib/classify.ts

import { generateText, Output } from 'ai';
import { z } from 'zod';

const review = 'Great tacos, slow delivery.';
const { output: sentiment } = await generateText({
  model: 'anthropic/claude-haiku-4.5',
  output: Output.choice({ options: ['positive', 'neutral', 'negative'] }),
  prompt: `Classify the sentiment of this review: ${review}`,
});

const { output: tags } = await generateText({
  model: 'anthropic/claude-haiku-4.5',
  output: Output.array({ element: z.object({ tag: z.string(), confidence: z.number() }), maxItems: 5 }),
  prompt: `Suggest tags for: ${review}`,
});
console.log(sentiment, tags.length);

lib/order-bot.ts

import { generateText, isStepCount, tool } from 'ai';
import { z } from 'zod';

const lookupOrders = tool({
  description: 'Look up a customer\'s recent orders by email address.',
  inputSchema: z.object({
    email: z.string().email().describe('The customer email address'),
  }),
  execute: async ({ email }) => {
    const orders = await db.orders.findByEmail(email);
    return orders.slice(0, 5).map((o) => ({ id: o.id, status: o.status }));
  },
});

const result = await generateText({
  model: 'anthropic/claude-sonnet-5',
  instructions: 'You help customers track orders. Use tools; never guess order data.',
  tools: { lookupOrders },
  stopWhen: isStepCount(5), // at most 5 model calls, then stop no matter what
  prompt: 'Where is my order? My email is sam@example.com',
});

console.log(result.text);
console.log(`Took ${result.steps.length} steps, ${result.usage.totalTokens} tokens total`);

lib/agents/support.ts

import { hasToolCall, isStepCount, ToolLoopAgent, tool } from 'ai';
import { z } from 'zod';

export const supportAgent = new ToolLoopAgent({
  model: 'anthropic/claude-sonnet-5',
  instructions: 'You are Taco Tracker support. Search the docs before answering.',
  tools: {
    searchDocs: tool({
      description: 'Search the help center',
      inputSchema: z.object({ query: z.string() }),
      execute: async ({ query }) => searchDocs(query),
    }),
    refundOrder: tool({
      description: 'Refund an order. Only when the customer explicitly asks.',
      inputSchema: z.object({ orderId: z.string() }),
      execute: async ({ orderId }) => refundOrder(orderId),
    }),
    finalAnswer: tool({
      description: 'Call this with your final reply to the customer.',
      inputSchema: z.object({ reply: z.string() }),
    }),
  },
  // Pause for a human before any refund runs.
  toolApproval: { refundOrder: 'user-approval' },
  // Stop when the agent calls finalAnswer, or after 10 steps as a safety net.
  stopWhen: [hasToolCall('finalAnswer'), isStepCount(10)],
});

const result = await supportAgent.generate({ prompt: 'How do I change my delivery address?' });
console.log(result.steps.length);

app/chat/page.tsx (excerpt)

// In your useChat component: approval requests arrive as tool parts.
const { messages, addToolApprovalResponse } = useChat({ /* transport... */ });

// When the user clicks a button next to the pending refund:
addToolApprovalResponse({ id: approvalId, approved: true });
// or: addToolApprovalResponse({ id: approvalId, approved: false, reason: 'Not eligible' });

lib/extract-invoice.ts

import Anthropic from '@anthropic-ai/sdk';
import { zodOutputFormat } from '@anthropic-ai/sdk/helpers/zod';
import { z } from 'zod';

const Invoice = z.object({
  vendor: z.string(),
  total: z.number(),
  currency: z.string(),
  dueDate: z.string().describe('ISO date, YYYY-MM-DD'),
});

const client = new Anthropic(); // reads ANTHROPIC_API_KEY
const invoiceText = '...';

const response = await client.messages.parse({
  model: 'claude-sonnet-5',
  max_tokens: 2000,
  messages: [{ role: 'user', content: `Extract the invoice fields:\n\n${invoiceText}` }],
  output_config: { format: zodOutputFormat(Invoice) },
});

// parsed_output is null if parsing failed, so guard it
const invoice = response.parsed_output;
if (invoice) console.log(invoice.vendor, invoice.total);

Tool definition (Claude API)

{
  "name": "book_table",
  "description": "Book a restaurant table",
  "strict": true,
  "input_schema": {
    "type": "object",
    "properties": {
      "date": { "type": "string", "format": "date" },
      "partySize": { "type": "integer", "enum": [1, 2, 3, 4, 5, 6] }
    },
    "required": ["date", "partySize"],
    "additionalProperties": false
  }
}