Router Structured Output

Request JSON through Router and validate a MovieScript with Pydantic.

This example sends the schema through the Responses API in text.format. Choose a Router candidate that supports structured output.

structured_output.py
"""
Router Structured Output
========================

Cookbook example for `ramp/structured_output.py`.
"""

from typing import List

from agno.agent import Agent, RunOutput  # noqa
from agno.models.ramp import RampRouter
from pydantic import BaseModel, Field
from rich.pretty import pprint  # noqa

# ---------------------------------------------------------------------------
# Create Agent
# ---------------------------------------------------------------------------

class MovieScript(BaseModel):
    setting: str = Field(
        ..., description="Provide a nice setting for a blockbuster movie."
    )
    ending: str = Field(
        ...,
        description="Ending of the movie. If not available, provide a happy ending.",
    )
    genre: str = Field(
        ...,
        description="Genre of the movie. If not available, select action, thriller or romantic comedy.",
    )
    name: str = Field(..., description="Give a name to this movie")
    characters: List[str] = Field(..., description="Name of characters for this movie.")
    storyline: str = Field(
        ..., description="3 sentence storyline for the movie. Make it exciting!"
    )

# Agent that uses a structured output
structured_output_agent = Agent(
    model=RampRouter(id="gpt-5.6-luna"),
    description="You are a helpful assistant. Summarize the movie script based on the location in a JSON object.",
    output_schema=MovieScript,
)

structured_output_agent.print_response("New York")

# ---------------------------------------------------------------------------
# Run Agent
# ---------------------------------------------------------------------------

if __name__ == "__main__":
    pass

output_schema describes the expected type. If parsing or validation fails, result.content can remain a string. Before accessing schema fields in a run result, use isinstance(result.content, YourSchema), replacing YourSchema with the class you passed as output_schema.

Run the Example

Set up your virtual environment

uv venv --python 3.12
source .venv/bin/activate

Install dependencies

uv pip install -U agno openai

Export your API keys

export RAMP_ROUTER_API_KEY="your_ramp_router_api_key_here"

Select models available to your key

Choose exact callable IDs from the authenticated GET https://api.router.com/v1/models catalog, following Router's model selection guide. Select candidates with the tool or structured-output capabilities required by this example. Access is specific to your API key.

Update id or the models list in the saved file as needed. In the basic example, also update the model string: keep its ramp: provider prefix and put the selected callable ID after it. Do not pass both id and models.

Run the example

Save the code above as structured_output.py, then run:

python structured_output.py

Full source: cookbook/90_models/ramp/structured_output.py