Structured outputs

Agno agents support two methods for schema-compliant responses: Structured Outputs and JSON mode. Both use the agent’s output_schema parameter.

Structured Outputs (Default if supported)

If the model class supports it, Agno agents use Structured Outputs by default. The schema (Pydantic or JSON Schema) is passed to the model provider’s API. For successfully completed, non-refusal responses, providers that support strict Structured Outputs validate the response against that schema. Handle refusals, incomplete generations, and provider errors separately.

from pydantic import BaseModel
from agno.agent import Agent
from agno.models.openai import OpenAIChat

class User(BaseModel):
    name: str
    age: int
    email: str

agent = Agent(
    model=OpenAIChat(id="gpt-5.4-mini"),
    description="You are a helpful assistant that can extract information from a user's profile.",
    output_schema=User,
)

The agent returns a User object instead of free-form text. Structured Outputs are a good fit for tasks where the output shape has to be right, like entity extraction or generating content for UI rendering.

JSON Mode

Some model classes do not support Structured Outputs, and sometimes you want to bypass it even when they do. Set use_json_mode=True to enable JSON mode.

from pydantic import BaseModel
from agno.agent import Agent
from agno.models.openai import OpenAIChat

class User(BaseModel):
    name: str
    age: int
    email: str

agent = Agent(
    model=OpenAIChat(id="gpt-5.4-mini"),
    description="You are a helpful assistant that can extract information from a user's profile.",
    output_schema=User,
    use_json_mode=True,
)

JSON mode injects a description of the expected JSON structure into the system prompt and instructs the model to return valid JSON. The response is not validated against the schema at the API level.

When to Use Which

Situation	Mode
Model supports Structured Outputs	Structured Outputs (default)
Model lacks Structured Outputs support	JSON mode (Agno falls back automatically)
Model can’t combine tools with Structured Outputs	JSON mode
Broad compatibility matters and you validate manually	JSON mode

FAQs

Structured outputs