Principle:Openai Openai agents python Runner Invocation

Property	Value
Principle Name	Runner Invocation
SDK	OpenAI Agents Python
Repository	openai-agents-python
Documentation	Running Agents Guide
Source Reference	`src/agents/run.py:L154-231`
Import	`from agents import Runner`

Overview

The Runner Invocation principle describes the execution model for agents in the OpenAI Agents Python SDK. The Runner orchestrates the complete agent lifecycle: invoking the model, processing tool calls, handling handoffs between agents, enforcing guardrails, and producing a final output. It implements a turn-based execution loop that continues until a terminal condition is reached.

Description

The Runner is a class with class-level methods (primarily run(), run_sync(), and run_streamed()) that serve as the primary entry point for executing agents. When Runner.run() is called, it enters a loop that repeats the following cycle:

Model Invocation: The agent's instructions, conversation history, tool schemas, and output schema are assembled and sent to the LLM.
Response Processing: The model's response is analyzed for output items: text content, tool calls, handoff requests, or structured final output.
Tool Execution: If the model requested tool calls, the tools are executed and their results are appended to the conversation history.
Handoff Resolution: If the model requested a handoff, execution transfers to the target agent with the conversation history carried forward.
Termination Check: The loop terminates when a final output is produced, max_turns is exceeded, or an interruption occurs (e.g., tool approval required).

Turn-Based Execution

Each turn corresponds to one model invocation plus the processing of its response (including any tool calls). The max_turns parameter controls the maximum number of turns before a MaxTurnsExceeded exception is raised. This prevents runaway loops where the model continuously calls tools without producing a final answer.

Guardrail Execution

Input guardrails run only on the first turn of the first agent. They execute in parallel with the initial model invocation, validating the user's input before (or concurrently with) the first response. Output guardrails run whenever an agent produces a final output, validating the generated content.

If a guardrail tripwire is triggered, a GuardrailTripwireTriggered exception is raised, halting the run.

Handoff Semantics

When a handoff occurs, the Runner:

Applies any handoff input filters to transform the conversation history for the target agent.
Switches the current agent to the handoff target.
Continues the execution loop with the new agent.

The handoff mechanism allows building multi-agent workflows where specialized agents collaborate on a task.

Resumable Execution (Human-in-the-Loop)

The Runner supports passing a RunState as input instead of a string or message list. This enables resuming interrupted runs, which is essential for human-in-the-loop workflows where tool calls require approval before execution. The caller can inspect interruptions, approve or reject tool calls, and pass the modified state back to Runner.run() to continue execution.

Session and Conversation Management

The Runner supports server-managed conversations via conversation_id and previous_response_id parameters, as well as client-side session persistence through the session parameter. These mechanisms enable multi-turn conversations that persist across separate run() invocations.

Theoretical Basis

The Runner Invocation principle embodies several design patterns:

Mediator Pattern: The Runner mediates between agents, tools, guardrails, and the model layer, coordinating their interactions without them knowing about each other directly.
State Machine: The execution loop is effectively a state machine transitioning between states: invoke model, process tools, check handoffs, check termination.
Template Method: The run loop defines the skeleton of the execution algorithm, with specific steps (model invocation, tool execution) delegated to pluggable components.
Continuation Passing: The RunState mechanism captures the execution state at an interruption point, allowing the run to be resumed from exactly where it left off.

Usage

Basic Invocation

from agents import Agent, Runner

agent = Agent(name="assistant", instructions="You are helpful.")
result = await Runner.run(agent, "What is the capital of France?")
print(result.final_output)

With Max Turns and Hooks

result = await Runner.run(
    agent,
    "Solve this complex problem step by step.",
    max_turns=20,
    hooks=my_run_hooks,
    run_config=RunConfig(tracing_disabled=True),
)

Resuming from Interruption

result = await Runner.run(agent, "Delete the file")
if result.interruptions:
    state = result.to_state()
    state.approve(result.interruptions[0])
    result = await Runner.run(agent, state)

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment