# 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`](https://docs.ag2.ai/latest/docs/beta/agents/). Two surfaces matter for structured output: | Surface | What it is | | --- | --- | | `reply.body` | Raw text from the model for that turn (a `str` or `None`). | | `await reply.content()` | Parsed value according to the **response schema** in effect for that turn. | 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](https://docs.ag2.ai/latest/docs/beta/structured_output/#validation-retries) 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`](https://docs.ag2.ai/latest/docs/beta/structured_output/#promptedschema-models-without-native-structured-output) 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 | | | | --- | --- | | ```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
``` | ```
from autogen.beta import Agent
from autogen.beta.config import OpenAIConfig
agent = Agent(
"assistant",
prompt="You are a helpful assistant. Answer concisely.",
config=OpenAIConfig("gpt-4o-mini"),
response_schema=int,
)
reply = await agent.ask("How many bits are in a byte?")
print(reply.body) # e.g. '8' — raw model text
result = await reply.content()
print(result) # 8 — Python int
``` | ## 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: | | | | --- | --- | | ```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
``` | ```
from typing import Annotated
from pydantic import BaseModel, Field
from autogen.beta import Agent
from autogen.beta.config import OpenAIConfig
class TicketTriage(BaseModel):
"""Structured triage for a single support message."""
category: Annotated[str, Field(description="e.g. billing, bug, account_access")]
urgency: Annotated[str, Field(description="low, medium, or high")]
summary_one_line: Annotated[str, Field(description="Max 120 characters", max_length=120)]
agent = Agent(
"triage",
prompt="You triage customer support messages. Be conservative with urgency.",
config=OpenAIConfig("gpt-4o-mini"),
response_schema=TicketTriage,
)
body = (
"I was charged twice for Pro last week and I still can't export my reports. "
"This is blocking our quarter close."
)
reply = await agent.ask(f"Classify this ticket:\n\n{body}")
triage = await reply.content()
# triage.category, triage.urgency, triage.summary_one_line → use in routing rules
``` | ### Extract a delivery ETA window (dataclass) Turn natural language into something your scheduling layer can consume: | | | | --- | --- | | ```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
``` | ```
from dataclasses import dataclass
from autogen.beta import Agent
from autogen.beta.config import OpenAIConfig
@dataclass
class DeliveryWindow:
day_label: str
start_hour_local: int
end_hour_local: int
timezone: str
agent = Agent(
"scheduler",
prompt="Extract delivery windows as structured data only; use 24h integers for hours.",
config=OpenAIConfig("gpt-4o-mini"),
response_schema=DeliveryWindow,
)
reply = await agent.ask(
"Customer said: drop off Tuesday between 2 and 5pm Pacific, before dinner."
)
window = await reply.content()
``` | ### 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: | | | | --- | --- | | ```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
``` | ```
from autogen.beta import Agent
from autogen.beta.config import OpenAIConfig
agent = Agent(
"reviews",
prompt="You output a single integer 1–5 for overall satisfaction. No prose.",
config=OpenAIConfig("gpt-4o-mini"),
response_schema=int,
)
reply = await agent.ask(
"Rate this review: 'Shipped fast, packaging was torn, product works great.'"
)
stars = await reply.content()
``` | ## 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 | | | | --- | --- | | ```
1
2
3
4
5
``` | ```
agent = Agent("assistant", config=config, response_schema=int)
reply = await agent.ask("What is 2 + 2?")
result = await reply.content()
# 4 — int
``` | ### Dataclasses | | | | --- | --- | | ```
1
2
3
4
5
6
7
8
9
10
11
``` | ```
from dataclasses import dataclass
@dataclass
class City:
name: str
population: int
agent = Agent("assistant", config=config, response_schema=City)
reply = await agent.ask("Give the city name and approximate population for Kyoto.")
result = await reply.content()
``` | ### Pydantic models | | | | --- | --- | | ```
1
2
3
4
5
6
7
8
9
10
``` | ```
from pydantic import BaseModel
class Sentiment(BaseModel):
label: str
score: float
agent = Agent("assistant", config=config, response_schema=Sentiment)
reply = await agent.ask("Analyze: 'I love this product!'")
result = await reply.content()
``` | ### Unions Use a union (`int | str`) or a tuple of types (`(int, str)`) when the model must return **one of several JSON shapes**. | | | | --- | --- | | ```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
``` | ```
from autogen.beta import Agent
from autogen.beta.config import OpenAIConfig
config = OpenAIConfig("gpt-4o-mini")
# int | str — e.g. a count, or "unknown" when the text does not say
agent = Agent(
"extractor",
prompt='Reply with JSON only: either an integer count or the string "unknown".',
config=config,
response_schema=int | str,
)
reply = await agent.ask("How many seats does the venue mention? (no number in text)")
result = await reply.content()
# result is int or str, depending on the model output
``` | ### `ResponseSchema` (named payloads) For clearer API metadata, construct a `ResponseSchema` with an explicit **`name`** and **`description`**: | | | | --- | --- | | ```
1
2
3
4
5
6
7
8
9
``` | ```
from autogen.beta import Agent, ResponseSchema
schema = ResponseSchema(
int | str,
name="ByteWidth",
description="The number of bits in one byte.",
)
agent = Agent("assistant", config=config, response_schema=schema)
``` | 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 | | | | --- | --- | | ```
1
2
3
4
5
6
7
8
9
10
11
``` | ```
from autogen.beta import Agent, response_schema
@response_schema
def parse_rating(content: str) -> int:
"""Parse a rating and clamp it to 1–5."""
return max(1, min(5, int(content)))
agent = Agent("assistant", config=config, response_schema=parse_rating)
reply = await agent.ask("Rate this movie from 1 to 5.")
result = await reply.content()
``` | ### Async validator: enrich after JSON parse | | | | --- | --- | | ```
1
2
3
4
5
6
7
``` | ```
import json
@response_schema
async def fetch_and_validate(content: str) -> dict:
"""Validate and enrich the model's JSON response."""
data = json.loads(content)
data["validated"] = True
return data
``` | ### 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`](https://docs.ag2.ai/latest/docs/beta/context/variables/), [`Depends`](https://docs.ag2.ai/latest/docs/beta/depends/), [`Inject`](https://docs.ag2.ai/latest/docs/beta/context/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`](https://docs.ag2.ai/latest/docs/beta/context/variables/) to read `variables`, tie validation to session state, or perform lookups: | | | | --- | --- | | ```
1
2
3
4
5
6
7
``` | ```
from autogen.beta import Context, response_schema
@response_schema
def validate_with_context(content: str, context: Context) -> str:
"""Use context variables during validation."""
language = context.variables.get("language", "en")
return f"[{language}] {content}"
``` | ## `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: | | | | --- | --- | | ```
1
2
3
4
``` | ```
PromptedSchema(
int,
prompt_template="Reply with JSON matching this schema:\n{schema}",
)
``` | ### 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: | | | | --- | --- | | ```
1
2
3
4
``` | ```
agent = Agent("assistant", config=config)
turn = await agent.ask("How many seconds in a minute?", response_schema=int)
result = await turn.content()
#> 60 - int
turn2 = await turn.ask("Say hello.")
result2 = await turn2.content()
#> "Hello!" - str
``` | ## 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()`: | Value | Behavior | | --- | --- | | `retries=0` (default) | No retries — raise on the first validation failure. | | `retries=3` | Up to 3 re-asks after the initial attempt (4 total). | | `retries=math.inf` | Re-ask indefinitely until the model produces a valid response. | 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.