Initiates the agent loop
AI Models & Assistants / Knowledge library
Agent Run
Represents one bounded attempt to pursue a goal through one or more model turns
Why learn Agent Run?
It gives tracing, budgets, cancellation, resumption, and results a clear operational scope.
The problem it solves
It provides a boundary for managing and measuring a multi-step agent task.
Where it came from
A run begins with an input and runtime configuration, accumulates messages and actions, and finishes, pauses, fails, or reaches a limit. One run can contain many turns and tool calls, so run and model request are not synonyms.
Build your understanding
Work through these exercises in order. Try the task before opening a reference.
- Define Agent Run and identify its place in an agent architecture.
- Choose a task where Agent Run improves an agent system.
- Diagnose one failure caused by misusing Agent Run.
- Interpret a trace or state transition involving Agent Run.
- Explain one operational tradeoff of Agent Run.
Documentation and sources
- OpenAI Agents SDK: Running agents (openai.github.io)
Connect the ideas
Explore next
Real World Example
Automated Inventory Reconciliation Agent
Logistics firms managing high-frequency warehouse stock updates.
The business problem
Manual reconciliation of inventory discrepancies between disparate database systems is slow and prone to human error, leading to stock-outs or over-ordering.
How this topic solves it
An Agent Run orchestrates a bounded attempt to reconcile stock by using a Runner to execute tool calls that query inventory databases, compare values, and generate summary reports within a single, controlled session.
- Define an Agent with specific instructions for inventory comparison and access to database query tools.
- Initialize a Runner to manage the lifecycle of the reconciliation request.
- Configure a RunConfig to set max_turns, preventing infinite loops during complex data cross-referencing.
- Execute the Runner to process the reconciliation logic through model turns, tool execution, and final output generation.
- Capture the RunResult to verify the final reconciliation status or identify unresolved discrepancies.
The sequence of events during an Agent Run for inventory reconciliation.
Analyzes inventory data
Queries warehouse databases
Final reconciliation report
- Runner.run() → triggers → LLM Turn
- LLM Turn → emits tool calls → Tool Execution
- Tool Execution → appends results → LLM Turn
- LLM Turn → produces final output → RunResult
Implementation example
This code demonstrates initializing an Agent and using the Runner to perform a bounded reconciliation task with a specific turn limit.
from agents import Agent, Runner, RunConfig
# Define the agent with inventory tools
agent = Agent(name="InventoryBot", tools=[query_db, compare_stock])
# Execute the reconciliation with a turn limit
result = await Runner.run(agent, "Reconcile warehouse A and B", run_config=RunConfig(max_turns=5))Expected business outcome
Consistent, automated inventory audits that reduce manual intervention and provide immediate visibility into stock discrepancies.
Limitations and checks
The Runner loop terminates if max_turns is exceeded, which may occur during large-scale data reconciliation; check for MaxTurnsExceeded exceptions to determine if the process requires manual continuation or higher turn limits.