Define OpenAI Agents, Instructions, Models, and Output

An OpenAI Agent is a specialist contract: name, instructions, model choice, tools, handoffs, guardrails, MCP connections, and optional structured output. Put stable job rules on the agent, pass trusted application dependencies through local run context, and require a typed output whenever downstream code needs fields rather than prose.

What will you be able to do?

You will define a typed triage agent, use local context without exposing it to the model, and decide when model selection belongs in configuration.

How do agent and application context differ?

Conversation input is visible to the model. Local run context is visible to your callbacks and tools. It can hold authenticated identity, repositories, loggers, or feature flags—but those values reach the model only if your code deliberately renders or returns them.

typed_agent.py:

python

import asyncio
from dataclasses import dataclass

from agents import Agent, Runner
from pydantic import BaseModel, Field


@dataclass(frozen=True)
class AppContext:
    tenant_id: str
    request_id: str


class TriageOutput(BaseModel):
    category: str = Field(pattern="^(billing|technical|general)$")
    summary: str = Field(max_length=300)
    needs_human: bool


agent = Agent[AppContext](
    name="Support triage",
    instructions=(
        "Classify the supplied support request. Return only the required output. "
        "Set needs_human when the request asks for a financial or destructive action."
    ),
    output_type=TriageOutput,
)


async def main() -> None:
    result = await Runner.run(
        agent,
        "Delete my account and all data.",
        context=AppContext(tenant_id="tenant_demo", request_id="req_1"),
    )
    output = result.final_output
    print(output.model_dump_json(indent=2))


if __name__ == "__main__":
    asyncio.run(main())

The generic type documents which context tools/callbacks may receive. output_type asks the SDK/model path for schema-conforming output. Your code must still apply business validation.

How should you choose a model?

Select a model using current official guidance and an evaluation suite, not reputation. Compare task quality, tool-call accuracy, latency, availability, and cost for your workload. Keep the chosen identifier in deployable configuration and record it on each run.

Use a cheaper/faster model only after it meets the required scorecard. Use a stronger model only when its gain justifies operational cost. Do not let a book chapter become your source of truth for current model names.

How do you prove it works?

Validate category always matches the enum-like pattern.
Confirm destructive requests set needs_human in an evaluation suite.
Verify tenant_id does not appear in model messages or final output.
Pass an impossible output through a unit test and confirm validation fails.

Failure injection: Change the prompt to request an extra internal_reasoning field. The schema should prevent the application from depending on undeclared model output.

What changes in production?

Version instructions and schemas, keep model selection behind tested configuration, use dynamic instructions only for truly request-dependent guidance, and attach prompt/model/schema versions to trace and outcome records.

What mistakes should you avoid?

Concatenating untrusted ticket text into agent instructions.
Sending the whole authenticated user object to the model.
Treating typed output as authorization.
Hardcoding a model across every task without evaluation.
Giving one agent multiple conflicting roles.

Check your understanding

What is visible to the model versus local callbacks?
What does output_type provide—and not provide?
Which evidence should determine model selection?

Expert extension

Add a model-routing configuration with two candidates. Write an offline evaluation that selects the cheapest candidate meeting minimum quality, safety, and latency thresholds.

Official references

Define OpenAI Agents, Instructions, Models, and Output

How do agent and application context differ?

typed_agent.py:

python

import asyncio
from dataclasses import dataclass

from agents import Agent, Runner
from pydantic import BaseModel, Field


@dataclass(frozen=True)
class AppContext:
    tenant_id: str
    request_id: str


class TriageOutput(BaseModel):
    category: str = Field(pattern="^(billing|technical|general)$")
    summary: str = Field(max_length=300)
    needs_human: bool


agent = Agent[AppContext](
    name="Support triage",
    instructions=(
        "Classify the supplied support request. Return only the required output. "
        "Set needs_human when the request asks for a financial or destructive action."
    ),
    output_type=TriageOutput,
)


async def main() -> None:
    result = await Runner.run(
        agent,
        "Delete my account and all data.",
        context=AppContext(tenant_id="tenant_demo", request_id="req_1"),
    )
    output = result.final_output
    print(output.model_dump_json(indent=2))


if __name__ == "__main__":
    asyncio.run(main())

The generic type documents which context tools/callbacks may receive. output_type asks the SDK/model path for schema-conforming output. Your code must still apply business validation.

How should you choose a model?

How do you prove it works?

Validate category always matches the enum-like pattern.

Confirm destructive requests set needs_human in an evaluation suite.

Verify tenant_id does not appear in model messages or final output.

Pass an impossible output through a unit test and confirm validation fails.

Failure injection: Change the prompt to request an extra internal_reasoning field. The schema should prevent the application from depending on undeclared model output.