Structured Output
Schemas
Define structured contracts for Anvia outputs.
Start every structured output workflow by writing the shape your application needs. Anvia uses Zod schemas for tool inputs, tool outputs, extractors, and agent output schemas.
1. Define the Shape
import { z } from "zod";
export const ticketSchema = z.object({
customer: z.string(),
priority: z.enum(["low", "medium", "high"]),
summary: z.string(),
});Keep schemas small at first. Add nested fields only when your application actually needs them.
2. Choose Where the Schema Runs
| Workflow | Use |
|---|---|
| The agent should produce a structured final answer | AgentBuilder.outputSchema(...) |
| You have existing text and need typed data | ExtractorBuilder |
| A tool receives model arguments | createTool({ input }) |
| A tool result must be validated | createTool({ output }) |
3. Prefer Explicit Values
Enums, required strings, booleans, and numbers are easier for models to satisfy than loose objects.
const classificationSchema = z.object({
category: z.enum(["billing", "technical", "account"]),
confidence: z.number(),
needsFollowup: z.boolean(),
});4. Add Descriptions Where They Matter
Descriptions are sent to the provider as schema metadata. Use them when a field could be interpreted in more than one way.
const escalationSchema = z.object({
reason: z.string().describe("Short explanation for why escalation is needed."),
severity: z.enum(["normal", "urgent"]),
});Next, read Zod Schema to see how Anvia converts this shape for providers.