Structured Output

Structured output constrains the model’s final message so you can parse it into a typed Python value—a number, a dataclass, a Pydantic model, or the result of your own validator—instead of treating the reply as an opaque string.

What you get on each turn

Every turn returns an AgentReply. Two surfaces matter for structured output:

If the model’s output cannot be parsed or fails validation, content() raises an error from the underlying parser (for example Pydantic’s validation errors). You can pass retries to automatically re-ask the model on failure.

With the default OpenAI client, when the schema exposes a JSON Schema to the API, the client sends a structured response_format so the model is guided to emit JSON matching that schema. PromptedSchema is the escape hatch when the provider does not support that mechanism: the schema is injected into the system prompt instead, and content() still runs the same way afterward.

When to use which tool

• Pass a plain type (int, YourModel, …) when the default schema name and description are enough.
• Use ResponseSchema when you want a clear name and description in the API payload so the model knows the role of the structured payload.
• Use @response_schema when you need custom parsing, normalization, or extra steps after JSON is read.
• Use PromptedSchema when your model or endpoint does not support native structured output.

Quick start

Real-world examples

The following patterns mirror how structured output is used in applications: triage, extraction, and safe normalization.

Classify a support ticket (Pydantic)

Route incoming text into fields your helpdesk or CRM already understands:

Extract a delivery ETA window (dataclass)

Turn natural language into something your scheduling layer can consume:

Score a review on a fixed scale (primitive + clear prompt)

Use a primitive schema when the payload is a single JSON value and your prompt defines the scale:

Supported schema types

You can pass any type the stack can turn into a JSON Schema and parse back: primitives, dataclass, Pydantic models, unions, and more. Plain types are wrapped in an internal ResponseSchema instance for validation and API schema generation.

Primitives

Dataclasses

Pydantic models

Unions

Use a union (int | str) or a tuple of types ((int, str)) when the model must return one of several JSON shapes.

ResponseSchema (named payloads)

For clearer API metadata, construct a ResponseSchema with an explicit name and description:

Those fields are attached to the structured-output payload where the provider supports it, which helps the model treat the JSON as a named contract rather than a generic blob.

Custom validation with @response_schema

Use the decorator when you need logic beyond “parse this JSON into a type”: clamping, regex cleanup, decoding wrapped JSON, or combining fields.

Sync validator: clamp a numeric rating

Async validator: enrich after JSON parse

Validation rules for @response_schema

The framework introspects your function with fast_depents (the same dependency-injection path as @tool callables). Parameters satisfied by injection - Variables, Depends, Inject, Context and similar—are not part of the JSON the model must produce. Every other parameter controls how the completion text is decoded and whether a JSON Schema is attached for native structured output.

Accessing Context

Validators participate in the same dependency injection model as tools. Inject Context to read variables, tie validation to session state, or perform lookups:

PromptedSchema (models without native structured output)

Some models or providers do not support API-level structured output (no response_format JSON schema). PromptedSchema injects the JSON Schema into the system prompt and sets json_schema to None on the wire so the client does not request native structured mode. Validation still goes through the inner schema’s validate method.

Custom prompt template

The default template asks for raw JSON only. Override it with a string that contains the {schema} placeholder:

Override schema per request

Pass response_schema to ask() (or AgentReply.ask()) to change the contract for one turn only. The agent’s default schema applies again on the next turn unless you override again:

Validation retries

When the model's response fails schema validation, you can automatically re-ask the model instead of raising immediately. Pass the retries keyword to content():

The retries parameter controls how many re-asks are allowed after the initial attempt. With retries=3, the initial response is validated; if it fails, the model is re-asked up to 3 more times before the error is raised.