Portkey Structured Output

Apply the account model and explicit-key setup below before running the preserved source.

structured_output.py

"""
Portkey Structured Output
=========================

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

from typing import List

from agno.agent import Agent, RunOutput  # noqa
from agno.models.portkey import Portkey
from pydantic import BaseModel, Field

# ---------------------------------------------------------------------------
# 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 = Agent(
    model=Portkey(id="@first-integrati-707071/gpt-5-nano"),
    output_schema=MovieScript,
    markdown=True,
)

# Get the response in a variable
# run: RunOutput = agent.run("New York")
# print(run.content)

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 portkey-ai

Export your Portkey API key

export PORTKEY_API_KEY="your_portkey_api_key_here"

Select and configure your Portkey model

In the Portkey model catalog, configure an AI Provider integration with its provider credentials and enable the model for your workspace. Copy its full model slug, including your integration prefix. The source's @first-integrati-707071 prefix belongs to a different account.

export PORTKEY_MODEL_ID="@your-integration/your-enabled-model"

Replace the placeholder with your copied slug. Add from os import environ to the saved file, then replace every model construction with Portkey(id=environ["PORTKEY_MODEL_ID"], portkey_api_key=environ["PORTKEY_API_KEY"]). Keep any additional model options you need. This revision requires the explicit portkey_api_key argument; setting the environment variable alone is insufficient. Choose a model that supports this example's tools or JSON Schema when those are used.

Run the example

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

python structured_output.py

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