You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
When working with language models, generating responses that match a specific structure is crucial for building reliable applications. Agno Agents support two methods to achieve this: **Structured Outputs** and **JSON mode**.
9
+
10
+
---
11
+
12
+
### Structured Outputs (Default if supported)
13
+
14
+
"Structured Outputs" is the **preferred** and most **reliable** way to extract well-formed, schema-compliant responses from a Model. If a model class supports it, Agno Agents use Structured Outputs by default.
15
+
16
+
With structured outputs, we provide a schema to the model (using Pydantic or JSON Schema), and the model’s response is guaranteed to **strictly follow** that schema. This eliminates many common issues like missing fields, invalid enum values, or inconsistent formatting. Structured Outputs are ideal when you need high-confidence, well-structured responses—like entity extraction, content generation for UI rendering, and more.
17
+
18
+
In this case, the response model is passed as a keyword argument to the model.
19
+
20
+
## Example
21
+
22
+
```python
23
+
from pydantic import BaseModel
24
+
from agno.agent import Agent
25
+
from agno.models.openai import OpenAIChat
26
+
27
+
classUser(BaseModel):
28
+
name: str
29
+
age: int
30
+
email: str
31
+
32
+
agent = Agent(
33
+
model=OpenAIChat(id="gpt-4o"),
34
+
description="You are a helpful assistant that can extract information from a user's profile.",
35
+
response_model=User,
36
+
)
37
+
```
38
+
39
+
In the example above, the model will generate a response that matches the `User` schema using structured outputs via OpenAI's `gpt-4o` model. The agent will then return the `User` object as-is.
40
+
41
+
---
42
+
43
+
### JSON Mode
44
+
45
+
Some model classes **do not support Structured Outputs**, or you may want to fall back to JSON mode even when the model supports both options. In such cases, you can enable **JSON mode** by setting `use_json_mode=True`.
46
+
47
+
JSON mode works by injecting a detailed description of the expected JSON structure into the system prompt. The model is then instructed to return a valid JSON object that follows this structure. Unlike Structured Outputs, the response is **not automatically validated** against the schema at the API level.
48
+
49
+
## Example
50
+
51
+
```python
52
+
from pydantic import BaseModel
53
+
from agno.agent import Agent
54
+
from agno.models.openai import OpenAIChat
55
+
56
+
classUser(BaseModel):
57
+
name: str
58
+
age: int
59
+
email: str
60
+
61
+
agent = Agent(
62
+
model=OpenAIChat(id="gpt-4o"),
63
+
description="You are a helpful assistant that can extract information from a user's profile.",
64
+
response_model=User,
65
+
use_json_mode=True,
66
+
)
67
+
68
+
```
69
+
70
+
### When to use
71
+
72
+
Use **Structured Outputs** if the model supports it — it’s reliable, clean, and validated automatically.
73
+
74
+
Use **JSON mode**:
75
+
76
+
- When the model doesn't support structured outputs. Agno agents do this by default on your behalf.
77
+
- When you need broader compatibility, but are okay validating manually.
78
+
- When the model does not support tools with structured outputs.
0 commit comments