Copy page

Build with Hyphen

Pydantic AI

Pydantic AI builds agents whose outputs are validated Pydantic models. It reaches Hyphen through OpenAIChatModel with a custom OpenAIProvider.

Code
pip install "pydantic-ai-slim[openai]"
export HYPHEN_API_KEY="sk-..."

Setup guide: this config comes from Pydantic AI's official documentation and has not been run end to end against the gateway. Corrections to support@hyphen-solution.com.

The model

Code
import os
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "minimax-m3",
    provider=OpenAIProvider(
        base_url="https://api.hyphen-solution.com/v1",
        api_key=os.environ["HYPHEN_API_KEY"],
    ),
)

A typed agent

Code
import os
from pydantic import BaseModel
from pydantic_ai import Agent, RunContext
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "minimax-m3",
    provider=OpenAIProvider(
        base_url="https://api.hyphen-solution.com/v1",
        api_key=os.environ["HYPHEN_API_KEY"],
    ),
)


class WeatherReport(BaseModel):
    city: str
    summary: str
    temp_c: float


agent = Agent(
    model,
    output_type=WeatherReport,
    system_prompt="Report the weather. Use the tools you have.",
    model_settings={"max_tokens": 4000},
)


@agent.tool
def lookup_temp(ctx: RunContext[None], city: str) -> float:
    """Look up the current temperature in Celsius for a city."""
    return 31.4


result = agent.run_sync("What is the weather in Kuala Lumpur?")
print(result.output)
# WeatherReport(city='Kuala Lumpur', summary='Hot and stormy', temp_c=31.4)
print(result.usage())

Keep the default output mode

output_type works here because Pydantic AI's default strategy is a tool call under the hood. That is exactly what MiniMax supports.

Do not switch to NativeOutput. It asks the provider for a strict JSON schema via response_format, which the M-series ignore. If you want an alternative, PromptedOutput is the safe one, since it asks in the prompt and validates the result.

Code
from pydantic_ai import Agent
from pydantic_ai.output import PromptedOutput

# Fine: asks in the prompt, validates the reply.
agent = Agent(model, output_type=PromptedOutput(WeatherReport))

# Broken against MiniMax: needs provider-side json_schema support.
# agent = Agent(model, output_type=NativeOutput(WeatherReport))

Streaming

Code
async def main():
    async with agent.run_stream("What is the weather in Kuala Lumpur?") as result:
        async for message in result.stream_text(delta=True):
            print(message, end="", flush=True)

Model settings

max_tokens belongs in model_settings, and it needs to be generous:

Code
agent = Agent(
    model,
    output_type=WeatherReport,
    model_settings={"max_tokens": 4000, "temperature": 0.0},
)

Set it too low and the reasoning tokens consume the whole budget, the output tool never gets called, and Pydantic AI raises a validation error that looks like a model failure. See Choosing a model.

Gotchas

• OpenAIChatModel, not OpenAIModel.
• Never the bare "openai:minimax-m3" string. It picks the Responses API path and drops your base URL.
• max_tokens of 4000 for anything with tools or output_type.
• Docs moved from ai.pydantic.dev to pydantic.dev/docs/ai.
• 429 means the monthly budget is spent. See Handling the 429 cap.

Related

• Pydantic AI OpenAI models
• Instructor: a lighter option if you only want structured output.
• Structured JSON output: the raw pattern underneath.