LLM: run.py: add support for configurable default Runner

pakrym-oai · pakrym-oai · commit 046c2874ee8f · 2025-05-19T17:51:18.000-07:00
- Introduce a DEFAULT_RUNNER global and a set_default_runner() function to allow callers to specify a default Runner for agent runs.
- Update Runner.run, run_sync, and run_streaming to use DEFAULT_RUNNER if set, otherwise fallback to DefaultRunner.
- Add detailed docstrings to run, run_sync, and run_streaming methods for clarity on agent execution flow and exceptions.
diff --git a/src/agents/run.py b/src/agents/run.py
@@ -46,6 +46,15 @@
 from .util import _coro, _error_tracing
 
 DEFAULT_MAX_TURNS = 10
+DEFAULT_RUNNER: Runner | None = None
+
+
+def set_default_runner(runner: Runner) -> None:
+    """
+    Set the default runner to use for the agent run.
+    """
+    global DEFAULT_RUNNER
+    DEFAULT_RUNNER = runner
 
 
 @dataclass
@@ -161,7 +170,34 @@ async def run(
         run_config: RunConfig | None = None,
         previous_response_id: str | None = None,
     ) -> RunResult:
-        return await DefaultRunner().run_impl(
+        """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.
+        2. If a guardrail tripwire is triggered, a GuardrailTripwireTriggered exception is raised.
+        Note that 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.
+            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.
+        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_RUNNER or DefaultRunner()
+        return await runner.run_impl(
             starting_agent,
             input,
             context=context,
@@ -183,7 +219,37 @@ def run_sync(
         run_config: RunConfig | None = None,
         previous_response_id: str | None = None,
     ) -> RunResult:
-        return DefaultRunner().run_sync_impl(
+        """Run a workflow synchronously, starting at the given agent. Note that 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 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.
+        2. If a guardrail tripwire is triggered, a GuardrailTripwireTriggered exception is raised.
+        Note that 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.
+            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.
+        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_RUNNER or DefaultRunner()
+        return runner.run_sync_impl(
             starting_agent,
             input,
             context=context,
@@ -204,7 +270,34 @@ def run_streamed(
         run_config: RunConfig | None = None,
         previous_response_id: str | None = None,
     ) -> RunResultStreaming:
-        return DefaultRunner().run_streaming_impl(
+        """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.
+        2. If a guardrail tripwire is triggered, a GuardrailTripwireTriggered exception is raised.
+        Note that 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.
+            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.
+        Returns:
+            A result object that contains data about the run, as well as a method to stream events.
+        """
+        runner = DEFAULT_RUNNER or DefaultRunner()
+        return runner.run_streaming_impl(
             starting_agent,
             input,
             context=context,
