Principle:Openai Openai agents python Agent Definition

Property	Value
Principle Name	Agent Definition
SDK	OpenAI Agents Python
Repository	openai-agents-python
Documentation	Agents Guide
Source Reference	`src/agents/agent.py:L217-296`
Import	`from agents import Agent`

Overview

The Agent Definition principle describes the core primitive of the OpenAI Agents Python SDK: defining an AI agent as a configured LLM entity that encapsulates instructions, tools, guardrails, handoffs, and output types. An agent is not merely a model call but a self-contained unit of behavior that can be composed, specialized, and executed within a larger workflow.

Description

An Agent in the OpenAI Agents SDK is a dataclass that bundles together all the configuration needed to invoke a large language model in a purposeful way. At its heart, an agent wraps:

Instructions (system prompt): A static string or a dynamic callable that generates the system prompt at runtime, given the current context and agent instance.
Tools: A list of tool definitions (function tools, hosted tools, MCP tools) that the agent can invoke during execution.
Handoffs: Sub-agents that the agent can delegate to when a task falls outside its specialization, enabling modular multi-agent architectures.
Guardrails: Input and output guardrails that validate the conversation before and after the model generates a response.
Output type: An optional structured output type (e.g., a dataclass or Pydantic model) that constrains the agent's final output beyond plain text.
Model and model settings: Which LLM to use and tuning parameters such as temperature and top_p.
Hooks: Lifecycle callbacks that fire on events like agent start, tool execution, and handoff.
Tool use behavior: Configuration controlling whether the model is re-invoked after tool calls or whether tool output is treated as the final result.

Generic Context Type

Agents are generic over a context type (TContext). The context is a mutable object created by the caller and threaded through the entire execution lifecycle. It is available to tool functions, guardrails, handoff callbacks, and dynamic instruction generators. This enables shared state across all components without global variables.

Dynamic Instructions

Instructions can be either:

A plain string, used directly as the system prompt.
A callable (sync or async) that receives a RunContextWrapper[TContext] and the Agent[TContext] instance, returning a string. This allows instructions to adapt based on runtime state, user identity, or other contextual factors.

Separation of Concerns

The agent pattern encourages separation of concerns: rather than building a single monolithic prompt with every capability, the SDK promotes creating multiple specialized agents that hand off to each other. A triage agent might classify user intent and delegate to a billing agent, a technical support agent, or a sales agent. Each agent carries its own instructions, tools, and guardrails appropriate to its domain.

Theoretical Basis

The Agent Definition principle draws from several design patterns:

Encapsulation: An agent bundles related configuration (prompt, tools, guardrails) into a cohesive unit, reducing coupling between the orchestration layer and the model invocation details.
Strategy Pattern: Dynamic instructions and tool use behavior allow the agent's behavior to be varied at runtime without changing its structure.
Generic Programming: The Generic[TContext] parameterization ensures type safety for shared mutable state across the entire agent execution pipeline.
Composition over Inheritance: Agents compose tools, guardrails, and handoffs rather than inheriting behavior, making them flexible and easy to reconfigure.

Usage

API Signature

Agent(
    name="agent_name",
    instructions="You are a helpful assistant.",
    model="gpt-4.1",
    model_settings=ModelSettings(...),
    handoffs=[other_agent],
    tools=[my_tool],
    output_type=MyOutputType,
    hooks=MyAgentHooks(),
    input_guardrails=[my_input_guardrail],
    output_guardrails=[my_output_guardrail],
    tool_use_behavior="run_llm_again",
)

Basic Example

from agents import Agent

agent = Agent(
    name="assistant",
    instructions="You are a helpful assistant that answers questions concisely.",
    model="gpt-4.1",
)

Multi-Agent Handoff Example

from agents import Agent

billing_agent = Agent(
    name="billing",
    instructions="You handle billing inquiries.",
)

support_agent = Agent(
    name="support",
    instructions="You handle technical support questions.",
)

triage_agent = Agent(
    name="triage",
    instructions="You classify user intent and delegate to the appropriate agent.",
    handoffs=[billing_agent, support_agent],
)

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment