class Runner:
@classmethod
async def run(
cls,
starting_agent: Agent[TContext],
input: str | list[TResponseInputItem] | RunState[TContext],
*,
context: TContext | None = None,
max_turns: int = DEFAULT_MAX_TURNS,
hooks: RunHooks[TContext] | None = None,
run_config: RunConfig | None = None,
error_handlers: RunErrorHandlers[TContext] | None = None,
previous_response_id: str | None = None,
auto_previous_response_id: bool = False,
conversation_id: str | None = None,
session: Session | None = None,
) -> RunResult:
"""
Run a workflow starting at the given agent.
The agent will run in a loop until a final output is generated. The loop runs like so:
1. The agent is invoked with the given input.
2. If there is a final output (i.e. the agent produces something of type
`agent.output_type`), the loop terminates.
3. If there's a handoff, we run the loop again, with the new agent.
4. Else, we run tool calls (if any), and re-run the loop.
In two cases, the agent may raise an exception:
1. If the max_turns is exceeded, a MaxTurnsExceeded exception is raised unless handled.
2. If a guardrail tripwire is triggered, a GuardrailTripwireTriggered
exception is raised.
Note:
Only the first agent's input guardrails are run.
Args:
starting_agent: The starting agent to run.
input: The initial input to the agent. You can pass a single string for a
user message, or a list of input items.
context: The context to run the agent with.
max_turns: The maximum number of turns to run the agent for. A turn is
defined as one AI invocation (including any tool calls that might occur).
hooks: An object that receives callbacks on various lifecycle events.
run_config: Global settings for the entire agent run.
error_handlers: Error handlers keyed by error kind. Currently supports max_turns.
previous_response_id: The ID of the previous response. If using OpenAI
models via the Responses API, this allows you to skip passing in input
from the previous turn.
conversation_id: The conversation ID
(https://platform.openai.com/docs/guides/conversation-state?api-mode=responses).
If provided, the conversation will be used to read and write items.
Every agent will have access to the conversation history so far,
and its output items will be written to the conversation.
We recommend only using this if you are exclusively using OpenAI models;
other model providers don't write to the Conversation object,
so you'll end up having partial conversations stored.
session: A session for automatic conversation history management.
Returns:
A run result containing all the inputs, guardrail results and the output of
the last agent. Agents may perform handoffs, so we don't know the specific
type of the output.
"""
runner = DEFAULT_AGENT_RUNNER
return await runner.run(
starting_agent,
input,
context=context,
max_turns=max_turns,
hooks=hooks,
run_config=run_config,
error_handlers=error_handlers,
previous_response_id=previous_response_id,
auto_previous_response_id=auto_previous_response_id,
conversation_id=conversation_id,
session=session,
)
@classmethod
def run_sync(
cls,
starting_agent: Agent[TContext],
input: str | list[TResponseInputItem] | RunState[TContext],
*,
context: TContext | None = None,
max_turns: int = DEFAULT_MAX_TURNS,
hooks: RunHooks[TContext] | None = None,
run_config: RunConfig | None = None,
error_handlers: RunErrorHandlers[TContext] | None = None,
previous_response_id: str | None = None,
auto_previous_response_id: bool = False,
conversation_id: str | None = None,
session: Session | None = None,
) -> RunResult:
"""
Run a workflow synchronously, starting at the given agent.
Note:
This just wraps the `run` method, so it will not work if there's already an
event loop (e.g. inside an async function, or in a Jupyter notebook or async
context like FastAPI). For those cases, use the `run` method instead.
The agent will run in a loop until a final output is generated. The loop runs:
1. The agent is invoked with the given input.
2. If there is a final output (i.e. the agent produces something of type
`agent.output_type`), the loop terminates.
3. If there's a handoff, we run the loop again, with the new agent.
4. Else, we run tool calls (if any), and re-run the loop.
In two cases, the agent may raise an exception:
1. If the max_turns is exceeded, a MaxTurnsExceeded exception is raised unless handled.
2. If a guardrail tripwire is triggered, a GuardrailTripwireTriggered
exception is raised.
Note:
Only the first agent's input guardrails are run.
Args:
starting_agent: The starting agent to run.
input: The initial input to the agent. You can pass a single string for a
user message, or a list of input items.
context: The context to run the agent with.
max_turns: The maximum number of turns to run the agent for. A turn is
defined as one AI invocation (including any tool calls that might occur).
hooks: An object that receives callbacks on various lifecycle events.
run_config: Global settings for the entire agent run.
error_handlers: Error handlers keyed by error kind. Currently supports max_turns.
previous_response_id: The ID of the previous response, if using OpenAI
models via the Responses API, this allows you to skip passing in input
from the previous turn.
conversation_id: The ID of the stored conversation, if any.
session: A session for automatic conversation history management.
Returns:
A run result containing all the inputs, guardrail results and the output of
the last agent. Agents may perform handoffs, so we don't know the specific
type of the output.
"""
runner = DEFAULT_AGENT_RUNNER
return runner.run_sync(
starting_agent,
input,
context=context,
max_turns=max_turns,
hooks=hooks,
run_config=run_config,
error_handlers=error_handlers,
previous_response_id=previous_response_id,
conversation_id=conversation_id,
session=session,
auto_previous_response_id=auto_previous_response_id,
)
@classmethod
def run_streamed(
cls,
starting_agent: Agent[TContext],
input: str | list[TResponseInputItem] | RunState[TContext],
context: TContext | None = None,
max_turns: int = DEFAULT_MAX_TURNS,
hooks: RunHooks[TContext] | None = None,
run_config: RunConfig | None = None,
previous_response_id: str | None = None,
auto_previous_response_id: bool = False,
conversation_id: str | None = None,
session: Session | None = None,
*,
error_handlers: RunErrorHandlers[TContext] | None = None,
) -> RunResultStreaming:
"""
Run a workflow starting at the given agent in streaming mode.
The returned result object contains a method you can use to stream semantic
events as they are generated.
The agent will run in a loop until a final output is generated. The loop runs like so:
1. The agent is invoked with the given input.
2. If there is a final output (i.e. the agent produces something of type
`agent.output_type`), the loop terminates.
3. If there's a handoff, we run the loop again, with the new agent.
4. Else, we run tool calls (if any), and re-run the loop.
In two cases, the agent may raise an exception:
1. If the max_turns is exceeded, a MaxTurnsExceeded exception is raised unless handled.
2. If a guardrail tripwire is triggered, a GuardrailTripwireTriggered
exception is raised.
Note:
Only the first agent's input guardrails are run.
Args:
starting_agent: The starting agent to run.
input: The initial input to the agent. You can pass a single string for a
user message, or a list of input items.
context: The context to run the agent with.
max_turns: The maximum number of turns to run the agent for. A turn is
defined as one AI invocation (including any tool calls that might occur).
hooks: An object that receives callbacks on various lifecycle events.
run_config: Global settings for the entire agent run.
error_handlers: Error handlers keyed by error kind. Currently supports max_turns.
previous_response_id: The ID of the previous response, if using OpenAI
models via the Responses API, this allows you to skip passing in input
from the previous turn.
conversation_id: The ID of the stored conversation, if any.
session: A session for automatic conversation history management.
Returns:
A result object that contains data about the run, as well as a method to
stream events.
"""
runner = DEFAULT_AGENT_RUNNER
return runner.run_streamed(
starting_agent,
input,
context=context,
max_turns=max_turns,
hooks=hooks,
run_config=run_config,
error_handlers=error_handlers,
previous_response_id=previous_response_id,
auto_previous_response_id=auto_previous_response_id,
conversation_id=conversation_id,
session=session,
)