Building Agents
MDX
Structured Outputs for Agent Systems
Why typed responses make routing, validation, storage, and user interfaces more dependable.
Editorial review: clarity, operational relevance, safety boundaries, and source quality.
Turn prose into data
A schema lets the application receive fields such as status, evidence, next action, and confidence instead of parsing arbitrary prose. This creates a stable boundary between probabilistic output and deterministic code.
Design schemas around what the application must decide next. A triage result might include category, urgency, supporting evidence IDs, missing information, and recommended route. Avoid fields such as a free-form `analysis` blob when specific evidence and status fields would be easier to validate and measure.
Validate semantics too
Schema validity only proves the shape is correct. The application must still check that identifiers exist, values are allowed for the user, and claims are supported by current data.
Syntactic guarantees stop malformed JSON, not fabricated facts. Check foreign keys, allowed transitions, numerical ranges, and evidence references after parsing. If a field affects money, permissions, or customer state, derive or confirm it from authoritative data instead of accepting the model's value.
Keep presentation separate
Store and route the structured result, then render user-facing language from it. This supports multiple interfaces and makes behavior easier to evaluate over time.
Version schemas like APIs. Add fields compatibly where possible, record the schema version with traces, and test consumers before changing enum meanings. Presentation can then evolve independently: a web UI, audit queue, and notification service can render the same validated result differently.
Practical example
A claims triage contract
The model returns `route`, `urgency`, `evidence_ids`, `missing_fields`, and `customer_summary`. Code verifies that every evidence ID came from the current case, calculates the service deadline, and rejects routes unavailable in that region. The customer sees a plain-language status while operations receives the structured queue item. Neither consumer parses the model's prose to recover workflow state.
Field checklist
Apply it in practice
- Model the next application decision, not hidden reasoning.
- Validate references, permissions, and business semantics.
- Store schema versions with outputs and traces.
- Render user-facing language after validation.
Decision framework
Questions to answer before you build
Schemas make probabilistic output usable by deterministic software, but they guarantee shape—not truth, authorization, evidence quality, or business validity.
What must the application decide next?
Model fields around routing, evidence, missing information, status, and permitted actions instead of storing an unstructured reasoning blob.
Which semantics require validation?
Check references, enum availability, numerical ranges, state transitions, and resource ownership after schema parsing.
How will the schema evolve?
Version outputs, prefer additive changes, and test every consumer before changing field meanings or removing values.
Common failure signals
Watch for these warning signs
- Assuming valid JSON cannot contain invented identifiers or unsupported claims.
- Coupling user-facing prose directly to workflow state.
- Changing an enum meaning without updating stored traces and downstream consumers.
Selected primary references
Continue with the source material
These sources inform the wider editorial perspective for this topic. They are not presented as line-by-line citations for every statement.