Inkdown
Start writing

Study

70 filesยท12 subfolders

Shared Workspace

Study
AI eng

01_AGENT_SYSTEM

Shared from "Study" on Inkdown

Agent System - Comprehensive Deep Dive

Overview

The Agent system is the heart of the OpenAI Agents SDK. An Agent represents an AI assistant that can be configured with instructions, tools, guardrails, handoffs, and more. Think of an Agent as a "persona" or "role" that the LLM adopts, equipped with specific capabilities and constraints.

Core Classes

AgentBase

AgentBase is the base class for all agents. It provides the foundational attributes that are shared across different agent types (including Agent and RealtimeAgent).

basic-ques
core
Revision w/ Whiteboard
CN Basics - 1
CN Basics - 2
DNS
Event loop
programming-language-concepts.md
zero-language-explanation.md
DB
Quick
databases-deep-dive.md
01-introduction.md
02-relational-databases.md
03-database-design.md
04-indexing.md
05-transactions-acid.md
06-nosql-databases.md
07-query-optimization.md
08-replication-ha.md
09-sharding-partitioning.md
10-caching-strategies.md
11-cap-theorem.md
12-connection-pooling.md
13-backup-recovery.md
14-monitoring.md
15-database-selection.md
README.md
JS
core topics
Event loop
Merlin Backend
01-Orchestration.md
02-DeepResearch.md
03-Search.md
04-Scraping.md
05-Streaming.md
06-MultiProviderLLM.md
07-MemoryAndContext.md
08-ErrorHandling.md
09-RateLimiting.md
10-TaskQueue.md
11-SecurityAndAuth.md
Orchestration-2nd-draft
Mobile
Build Alternative
Bundling
metro-bundler-deep-dive.md
OpenAI Agents Python
00_OVERVIEW.md
01_AGENT_SYSTEM.md
02_RUNNER_SYSTEM.md
03_TOOL_SYSTEM.md
04_ITEMS_SYSTEM.md
05_GUARDRAILS.md
06_HANDOFFS.md
07_MEMORY_SESSIONS.md
08_MODEL_PROVIDERS.md
09_SANDBOX_SYSTEM.md
10_TRACING.md
11_RUN_STATE.md
12_CONTEXT.md
13_LIFECYCLE_HOOKS.md
14_CONFIGURATION.md
15_ERROR_HANDLING.md
16_STREAMING.md
17_EXTENSIONS.md
18_MCP_INTEGRATION.md
19_BEST_PRACTICES.md
20_ARCHITECTURE_PATTERNS.md
opencode-study
context-handling
core
Python
Alembic
Basics
sqlalchemy - fastapi
SQLAlchemy overview
tweets
system_design_for_agentic_apps.md
Agent Loop

Location: src/agents/agent.py

Key Attributes:

  • name: str - The name of the agent. This is used for identification, tracing, and when the agent is exposed as a tool or handoff.

  • handoff_description: str | None - A human-readable description of what this agent does. This is crucial when the agent is used in handoffs, as it helps other agents understand when and why they should delegate to this agent.

  • tools: list[Tool] - A list of tools that this agent can use. Tools are functions or capabilities the agent can call to perform actions (e.g., web search, file operations, API calls).

  • mcp_servers: list[MCPServer] - A list of Model Context Protocol (MCP) servers that provide additional tools. MCP is a standard protocol for exposing tools to AI models.

  • mcp_config: MCPConfig - Configuration for MCP servers, including schema conversion settings and error handling.

Key Methods:

  • async def get_mcp_tools(run_context) - Fetches available tools from MCP servers. This is called each time the agent runs to get the current set of available tools.

  • async def get_all_tools(run_context) - Returns all tools available to the agent, combining both direct tools and MCP tools. It also filters out disabled tools and checks for tool name collisions.

Agent

Agent is the main agent class you'll use most often. It extends AgentBase and adds agent-specific configuration.

Location: src/agents/agent.py

Key Attributes:

  • instructions: str | Callable | None - The system prompt for the agent. This is the most important attribute as it defines the agent's behavior, personality, and capabilities. It can be:

    • A static string
    • A function that dynamically generates instructions based on context
    • None (no specific instructions)

  • prompt: Prompt | DynamicPromptFunction | None - A more advanced way to configure prompts using OpenAI's Prompt API. This allows dynamic configuration of instructions, tools, and other settings outside of your code. Only usable with OpenAI models using the Responses API.

  • handoffs: list[Agent | Handoff] - A list of sub-agents or handoff configurations that this agent can delegate to. This enables multi-agent workflows where specialized agents handle specific tasks.

  • model: str | Model | None - The model to use for this agent. If not specified, it uses the default model (currently "gpt-4.1"). You can specify:

    • A string model name (e.g., "gpt-4o")
    • A custom Model instance

  • model_settings: ModelSettings - Model-specific tuning parameters like temperature, top_p, max tokens, etc. These control the randomness and creativity of the model's responses.

  • input_guardrails: list[InputGuardrail] - Guardrails that run before the agent processes input. These are safety checks that can validate, filter, or reject input before it reaches the LLM.

  • output_guardrails: list[OutputGuardrail] - Guardrails that run after the agent produces output. These validate the final output to ensure it meets safety or quality standards.

  • output_type: type | AgentOutputSchemaBase | None - The expected type of the output. If not specified, output is a string. You can specify:

    • A Python type (dataclass, Pydantic model, TypedDict, etc.)
    • A custom AgentOutputSchemaBase for custom JSON schemas
    • AgentOutputSchema with strict_json_schema=False for non-strict schemas

  • hooks: AgentHooks | None - A class that receives callbacks on various lifecycle events for this specific agent. This allows you to hook into the agent's execution to add custom logic.

  • tool_use_behavior: Literal | StopAtTools | Callable - Controls how tool use is handled:

    • "run_llm_again" (default) - Tools are executed, then the LLM receives the results and can respond again
    • "stop_on_first_tool" - The first tool's output is treated as the final result
    • StopAtTools dict - Stop if specific tools are called
    • Custom function - Fine-grained control over tool-to-output logic

  • reset_tool_choice: bool - Whether to reset tool choice after a tool call. Defaults to True to prevent infinite loops of tool usage.

Agent Lifecycle

1. Creation
Python

When you create an agent, the __post_init__ method runs extensive validation:

  • Checks that name is a string
  • Validates that tools is a list
  • Ensures instructions is either a string, callable, or None
  • Validates model settings compatibility
  • Checks that guardrails are lists
  • Validates output_type is a type or schema
  • Ensures hooks is an AgentHooks instance if provided
  • Validates tool_use_behavior is a valid option

This validation happens at creation time, so you get immediate feedback if configuration is invalid.

2. Execution

When you run an agent via Runner.run(), the following happens:

  1. Context Setup - A RunContextWrapper is created with your user context
  2. Tool Resolution - All available tools (direct + MCP) are gathered
  3. Input Preparation - Input is converted to the format expected by the model
  4. Guardrail Check - Input guardrails run (if configured)
  5. Model Call - The LLM is called with instructions, input, and tools
  6. Tool Execution - If the model calls tools, they're executed
  7. Response Processing - Model output is processed
  8. Output Guardrail Check - Output guardrails run (if configured)
  9. Result Return - Final output is returned
3. Cloning

Agents support shallow cloning via the clone() method:

Python

This uses dataclasses.replace() which:

  • Creates a new agent instance
  • Copies all attributes
  • Allows overriding specific attributes
  • Performs a shallow copy - mutable objects like tools and handoffs lists are shared unless explicitly overridden

This is useful for creating variations of an agent without duplicating all configuration.

Agents as Tools

One of the most powerful features is that agents can be exposed as tools to other agents. This is done via the as_tool() method:

Python

How it works:

  1. The agent is wrapped in a FunctionTool
  2. When called, it runs the nested agent with the provided input
  3. The nested agent's output is returned to the calling agent
  4. The nested agent runs in isolation - it doesn't automatically see the parent conversation history
  5. You can configure input parameters, streaming, approval requirements, and more

Key Parameters of as_tool():

  • tool_name - Name of the tool (defaults to agent name transformed to function style)
  • tool_description - Description for the LLM to understand when to use it
  • custom_output_extractor - Function to extract output from the nested agent
  • is_enabled - Whether the tool is enabled (can be dynamic)
  • on_stream - Callback to receive streaming events from nested runs
  • run_config - Run configuration for the nested agent
  • max_turns - Maximum turns for the nested agent
  • needs_approval - Whether the tool requires approval
  • parameters - Structured input type for the tool
  • input_builder - Function to build nested agent input from structured data

Difference from Handoffs:

  • Handoffs - The new agent receives the full conversation history and takes over the conversation
  • Agent as Tool - The new agent receives generated input and returns as a tool result, conversation continues with original agent

Context and Generics

Agents are generic over a context type:

Python

What is Context?

Context is a mutable object you create that is passed to:

  • Tool functions
  • Handoff functions
  • Guardrail functions
  • Lifecycle hooks

Why use Context?

Context allows you to:

  • Share state across tool calls
  • Track information during agent execution
  • Pass configuration to tools
  • Maintain application-specific state

Example:

Python

Dynamic Instructions

Instructions can be dynamic functions that generate the system prompt based on context:

Python

This is useful when:

  • You need to personalize instructions based on user data
  • Instructions depend on runtime state
  • You want to A/B test different instructions
  • Instructions need to be generated from external sources

Tool Management

Adding Tools
Python
Tool Namespaces

Tools can be organized into namespaces to avoid name collisions:

Python
Dynamic Tool Enablement

Tools can be dynamically enabled or disabled:

Python

Handoff Management

Adding Handoffs
Python
Handoff Input Filters

You can filter what information is passed to the next agent:

Python

Guardrails

Input Guardrails
Python
Output Guardrails
Python

Model Configuration

Model Selection
Python
Model Settings
Python
GPT-5 Special Handling

The SDK has special handling for GPT-5 models, which require specific reasoning settings. If you specify a non-GPT-5 model but the default is GPT-5, the SDK automatically adjusts the model settings to be compatible.

Output Types

String Output (Default)
Python
Structured Output
Python
Custom Schema
Python

Tool Use Behavior

Default Behavior (run_llm_again)
Python
Stop on First Tool
Python
Stop at Specific Tools
Python
Custom Behavior
Python

Lifecycle Hooks

Agent-level hooks allow you to react to events specific to this agent:

Python

Best Practices

1. Clear Instructions

Write clear, specific instructions:

Python
2. Tool Naming

Use descriptive tool names:

Python
3. Handoff Descriptions

Write clear handoff descriptions:

Python
4. Context Design

Keep context focused:

Python
5. Guardrail Granularity

Use guardrails at appropriate levels:

Python

Common Patterns

1. Specialist Pattern

Create specialized agents for specific tasks:

Python
2. Supervisor Pattern

One agent supervises others:

Python
3. Sequential Pattern

Chain agents in sequence:

Python
4. Parallel Pattern

Run multiple agents in parallel:

Python

Error Handling in Agents

Model Behavior Errors

When the model behaves unexpectedly:

Python
Tool Errors

Tools can raise errors:

Python
Guardrail Tripwires

When guardrails trigger:

Python

Advanced Topics

Agent Cloning for Variations
Python
Dynamic Tool Addition
Python
MCP Integration
Python

Summary

The Agent system is the foundation of the SDK. Key takeaways:

  1. Agent is the main class representing an AI assistant
  2. Instructions define the agent's behavior and personality
  3. Tools give agents capabilities to perform actions
  4. Guardrails provide safety and validation
  5. Handoffs enable multi-agent workflows
  6. Context allows state sharing across the agent lifecycle
  7. Agents as tools enables powerful composition patterns
  8. Generics provide type safety for context
  9. Lifecycle hooks allow custom logic at key points
  10. Cloning enables agent variations efficiently

Understanding the Agent system is crucial for building effective multi-agent workflows with the SDK.