lexsi-sdk 0.1.16__py3-none-any.whl

lexsi_sdk/core/guardrails/openai_runner.py

@@ -0,0 +1,1328 @@
+import inspect
+
+from agents import (
+    Agent,
+    AgentOutputSchema,
+    AgentOutputSchemaBase,
+    AgentSpanData,
+    AgentsException,
+    Handoff,
+    Model,
+    ModelBehaviorError,
+    ModelResponse,
+    OutputGuardrail,
+    OutputGuardrailResult,
+    OutputGuardrailTripwireTriggered,
+    RunConfig,
+    RunContextWrapper,
+    RunErrorDetails,
+    RunHooks,
+    RunItem,
+    RunResult,
+    RunResultStreaming,
+    Session,
+    Span,
+    SpanError,
+    Tool,
+    Usage,
+    agent_span,
+    trace,
+)
+from openai.types.responses import ResponseCompletedEvent
+from openai.types.responses.response_prompt_param import (
+    ResponsePromptParam,
+)
+from agents.exceptions import (
+    AgentsException,
+    InputGuardrailTripwireTriggered,
+    MaxTurnsExceeded,
+    ModelBehaviorError,
+    OutputGuardrailTripwireTriggered,
+    RunErrorDetails,
+    UserError,
+)
+from agents.guardrail import (
+    InputGuardrail,
+    InputGuardrailResult,
+    OutputGuardrail,
+    OutputGuardrailResult,
+)
+
+from agents.handoffs import Handoff, HandoffInputFilter, handoff
+
+from typing import Any, cast, Generic
+from agents.run import (
+    TResponseInputItem,
+    TContext,
+    DEFAULT_MAX_TURNS,
+    RunOptions,
+    AgentToolUseTracker,
+    _error_tracing,
+    TraceCtxManager,
+    get_model_tracing_impl,
+    AgentToolUseTracker,
+    NextStepFinalOutput,
+    NextStepHandoff,
+    NextStepRunAgain,
+    QueueCompleteSentinel,
+    RunImpl,
+    SingleStepResult,
+    TraceCtxManager,
+)
+from agents.stream_events import AgentUpdatedStreamEvent
+from agents.items import ItemHelpers, ModelResponse, RunItem, TResponseInputItem
+from agents.lifecycle import RunHooks
+from agents.logger import logger
+from agents.memory import Session
+from agents.model_settings import ModelSettings
+from agents.models.interface import Model, ModelProvider
+from agents.models.multi_provider import MultiProvider
+from agents.result import RunResult, RunResultStreaming
+from agents.run_context import RunContextWrapper, TContext
+from agents.stream_events import AgentUpdatedStreamEvent, RawResponsesStreamEvent
+from agents.tool import Tool
+from agents.tracing import Span, SpanError, agent_span, get_current_trace, trace
+from agents.tracing.span_data import AgentSpanData
+from agents.usage import Usage
+from agents.util import _coro, _error_tracing
+from agents.util._types import MaybeAwaitable
+
+from typing_extensions import Unpack
+import asyncio
+from agents.tracing import (
+    get_current_trace,
+)
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ModelInputData:
+    """Container for the data that will be sent to the model."""
+
+    input: list[TResponseInputItem]
+    instructions: str | None
+
+@dataclass
+class CallModelData(Generic[TContext]):
+    """Data passed to `RunConfig.call_model_input_filter` prior to model call."""
+
+    model_data: ModelInputData
+    agent: Agent[TContext]
+    context: TContext | None
+
+class Runner:
+    """Orchestrates agent execution loops for OpenAI Agents."""
+    @classmethod
+    async def run(
+        cls,
+        starting_agent: Agent[TContext],
+        input: str | list[TResponseInputItem],
+        *,
+        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,
+        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.
+        2. If a guardrail tripwire is triggered, a GuardrailTripwireTriggered exception is raised.
+        Note that only the first agent's input guardrails are run.
+
+        :param starting_agent: The starting agent to run.
+        :param input: The initial input to the agent; string user message or list of items.
+        :param context: Optional context to run the agent with.
+        :param max_turns: Maximum number of turns to run the agent.
+        :param hooks: Callbacks for lifecycle events.
+        :param run_config: Global settings for the entire agent run.
+        :param previous_response_id: Prior response id to continue Responses API runs.
+        :param session: Optional session used by the runner.
+        :return: Run result containing inputs, guardrail results, and final output.
+        """
+        runner = DEFAULT_AGENT_RUNNER
+        return await runner.run(
+            starting_agent,
+            input,
+            context=context,
+            max_turns=max_turns,
+            hooks=hooks,
+            run_config=run_config,
+            previous_response_id=previous_response_id,
+            session=session,
+        )
+
+    @classmethod
+    def run_sync(
+        cls,
+        starting_agent: Agent[TContext],
+        input: str | list[TResponseInputItem],
+        *,
+        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,
+        session: Session | None = None,
+    ) -> RunResult:
+        """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.
+
+        :param starting_agent: The starting agent to run.
+        :param input: The initial input to the agent; string user message or list of items.
+        :param context: Optional context to run the agent with.
+        :param max_turns: Maximum number of turns to run the agent.
+        :param hooks: Callbacks for lifecycle events.
+        :param run_config: Global settings for the entire agent run.
+        :param previous_response_id: Prior response id to continue Responses API runs.
+        :param session: Optional session used by the runner.
+        :return: Run result containing inputs, guardrail results, and final output.
+        """
+        runner = DEFAULT_AGENT_RUNNER
+        return runner.run_sync(
+            starting_agent,
+            input,
+            context=context,
+            max_turns=max_turns,
+            hooks=hooks,
+            run_config=run_config,
+            previous_response_id=previous_response_id,
+            session=session,
+        )
+
+    @classmethod
+    def run_streamed(
+        cls,
+        starting_agent: Agent[TContext],
+        input: str | list[TResponseInputItem],
+        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,
+        session: Session | 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.
+        2. If a guardrail tripwire is triggered, a GuardrailTripwireTriggered exception is raised.
+        Note that only the first agent's input guardrails are run.
+
+        :param starting_agent: The starting agent to run.
+        :param input: Initial input; string user message or list of items.
+        :param context: Optional context to run the agent with.
+        :param max_turns: Maximum number of turns to run the agent.
+        :param hooks: Callbacks for lifecycle events.
+        :param run_config: Global settings for the entire agent run.
+        :param previous_response_id: Prior response id to continue Responses API runs.
+        :param session: Optional session used by the runner.
+        :return: Result object containing run data and streaming method.
+        """
+        runner = DEFAULT_AGENT_RUNNER
+        return runner.run_streamed(
+            starting_agent,
+            input,
+            context=context,
+            max_turns=max_turns,
+            hooks=hooks,
+            run_config=run_config,
+            previous_response_id=previous_response_id,
+            session=session,
+        )
+
+
+class AgentRunner:
+    """Async runner that manages the OpenAI Agents control loop."""
+    async def run(
+        self,
+        starting_agent: Agent[TContext],
+        input: str | list[TResponseInputItem],
+        **kwargs: Unpack[RunOptions[TContext]],
+    ) -> RunResult:
+        """Run the agent workflow asynchronously until completion."""
+        context = kwargs.get("context")
+        max_turns = kwargs.get("max_turns", DEFAULT_MAX_TURNS)
+        hooks = kwargs.get("hooks")
+        run_config = kwargs.get("run_config")
+        previous_response_id = kwargs.get("previous_response_id")
+        session = kwargs.get("session")
+        if hooks is None:
+            hooks = RunHooks[Any]()
+        if run_config is None:
+            run_config = RunConfig()
+
+        # Prepare input with session if enabled
+        prepared_input = await self._prepare_input_with_session(input, session)
+
+        tool_use_tracker = AgentToolUseTracker()
+
+        with TraceCtxManager(
+            workflow_name=run_config.workflow_name,
+            trace_id=run_config.trace_id,
+            group_id=run_config.group_id,
+            metadata=run_config.trace_metadata,
+            disabled=run_config.tracing_disabled,
+        ):
+            current_turn = 0
+            original_input: str | list[TResponseInputItem] = _copy_str_or_list(prepared_input)
+            generated_items: list[RunItem] = []
+            model_responses: list[ModelResponse] = []
+
+            context_wrapper: RunContextWrapper[TContext] = RunContextWrapper(
+                context=context  # type: ignore
+            )
+
+            input_guardrail_results: list[InputGuardrailResult] = []
+
+            current_span: Span[AgentSpanData] | None = None
+            current_agent = starting_agent
+            should_run_agent_start_hooks = True
+
+            try:
+                while True:
+                    all_tools = await AgentRunner._get_all_tools(current_agent, context_wrapper)
+
+                    # Start an agent span if we don't have one
+                    if current_span is None:
+                        handoff_names = [
+                            h.agent_name
+                            for h in await AgentRunner._get_handoffs(current_agent, context_wrapper)
+                        ]
+                        if output_schema := AgentRunner._get_output_schema(current_agent):
+                            output_type_name = output_schema.name()
+                        else:
+                            output_type_name = "str"
+
+                        current_span = agent_span(
+                            name=current_agent.name,
+                            handoffs=handoff_names,
+                            output_type=output_type_name,
+                        )
+                        current_span.start(mark_as_current=True)
+                        current_span.span_data.tools = [t.name for t in all_tools]
+
+                    current_turn += 1
+                    if current_turn > max_turns:
+                        _error_tracing.attach_error_to_span(
+                            current_span,
+                            SpanError(
+                                message="Max turns exceeded",
+                                data={"max_turns": max_turns},
+                            ),
+                        )
+                        raise MaxTurnsExceeded(f"Max turns ({max_turns}) exceeded")
+
+                    # Run input guardrails for the first turn or after a handoff
+                    if current_turn == 1 or isinstance(turn_result.next_step, NextStepHandoff):
+                        input_guardrail_results.extend(
+                            await self._run_input_guardrails(
+                                current_agent,
+                                current_agent.input_guardrails + (run_config.input_guardrails or []),
+                                _copy_str_or_list(prepared_input if current_turn == 1 else original_input),
+                                context_wrapper,
+                            )
+                        )
+                        # Update original_input with sanitized content if any guardrail used 'retry'
+                        for result in input_guardrail_results:
+                            if hasattr(result.output, 'sanitized_content') and result.output.sanitized_content:
+                                original_input = result.output.sanitized_content
+
+                    turn_result = await self._run_single_turn(
+                        agent=current_agent,
+                        all_tools=all_tools,
+                        original_input=original_input,
+                        generated_items=generated_items,
+                        hooks=hooks,
+                        context_wrapper=context_wrapper,
+                        run_config=run_config,
+                        should_run_agent_start_hooks=should_run_agent_start_hooks,
+                        tool_use_tracker=tool_use_tracker,
+                        previous_response_id=previous_response_id,
+                    )
+                    should_run_agent_start_hooks = False
+
+                    model_responses.append(turn_result.model_response)
+                    original_input = turn_result.original_input
+                    generated_items = turn_result.generated_items
+
+                    if isinstance(turn_result.next_step, NextStepFinalOutput):
+                        output_guardrail_results = await self._run_output_guardrails(
+                            current_agent.output_guardrails + (run_config.output_guardrails or []),
+                            current_agent,
+                            turn_result.next_step.output,
+                            context_wrapper,
+                        )
+                        # Use sanitized content as final output if available
+                        final_output = turn_result.next_step.output
+                        for result in output_guardrail_results:
+                            if hasattr(result.output, 'sanitized_content') and result.output.sanitized_content:
+                                final_output = result.output.sanitized_content
+
+                        result = RunResult(
+                            input=original_input,
+                            new_items=generated_items,
+                            raw_responses=model_responses,
+                            final_output=final_output,
+                            _last_agent=current_agent,
+                            input_guardrail_results=input_guardrail_results,
+                            output_guardrail_results=output_guardrail_results,
+                            context_wrapper=context_wrapper,
+                        )
+
+                        # Save the conversation to session if enabled
+                        await self._save_result_to_session(session, input, result)
+
+                        return result
+                    elif isinstance(turn_result.next_step, NextStepHandoff):
+                        current_agent = cast(Agent[TContext], turn_result.next_step.new_agent)
+                        # Pass sanitized input to the handoff agent
+                        for result in input_guardrail_results:
+                            if hasattr(result.output, 'sanitized_content') and result.output.sanitized_content:
+                                original_input = result.output.sanitized_content
+                        current_span.finish(reset_current=True)
+                        current_span = None
+                        should_run_agent_start_hooks = True
+                    elif isinstance(turn_result.next_step, NextStepRunAgain):
+                        pass
+                    else:
+                        raise AgentsException(
+                            f"Unknown next step type: {type(turn_result.next_step)}"
+                        )
+            except AgentsException as exc:
+                exc.run_data = RunErrorDetails(
+                    input=original_input,
+                    new_items=generated_items,
+                    raw_responses=model_responses,
+                    last_agent=current_agent,
+                    context_wrapper=context_wrapper,
+                    input_guardrail_results=input_guardrail_results,
+                    output_guardrail_results=[],
+                )
+                raise
+            finally:
+                if current_span:
+                    current_span.finish(reset_current=True)
+
+    def run_sync(
+        self,
+        starting_agent: Agent[TContext],
+        input: str | list[TResponseInputItem],
+        **kwargs: Unpack[RunOptions[TContext]],
+    ) -> RunResult:
+        """Synchronous wrapper that runs the async agent loop to completion."""
+        context = kwargs.get("context")
+        max_turns = kwargs.get("max_turns", DEFAULT_MAX_TURNS)
+        hooks = kwargs.get("hooks")
+        run_config = kwargs.get("run_config")
+        previous_response_id = kwargs.get("previous_response_id")
+        session = kwargs.get("session")
+
+        return asyncio.get_event_loop().run_until_complete(
+            self.run(
+                starting_agent,
+                input,
+                session=session,
+                context=context,
+                max_turns=max_turns,
+                hooks=hooks,
+                run_config=run_config,
+                previous_response_id=previous_response_id,
+            )
+        )
+
+    def run_streamed(
+        self,
+        starting_agent: Agent[TContext],
+        input: str | list[TResponseInputItem],
+        **kwargs: Unpack[RunOptions[TContext]],
+    ) -> RunResultStreaming:
+        """Run the agent loop while streaming intermediate responses."""
+        context = kwargs.get("context")
+        max_turns = kwargs.get("max_turns", DEFAULT_MAX_TURNS)
+        hooks = kwargs.get("hooks")
+        run_config = kwargs.get("run_config")
+        previous_response_id = kwargs.get("previous_response_id")
+        session = kwargs.get("session")
+
+        if hooks is None:
+            hooks = RunHooks[Any]()
+        if run_config is None:
+            run_config = RunConfig()
+
+        new_trace = (
+            None
+            if get_current_trace()
+            else trace(
+                workflow_name=run_config.workflow_name,
+                trace_id=run_config.trace_id,
+                group_id=run_config.group_id,
+                metadata=run_config.trace_metadata,
+                disabled=run_config.tracing_disabled,
+            )
+        )
+
+        output_schema = AgentRunner._get_output_schema(starting_agent)
+        context_wrapper: RunContextWrapper[TContext] = RunContextWrapper(
+            context=context  # type: ignore
+        )
+
+        streamed_result = RunResultStreaming(
+            input=_copy_str_or_list(input),
+            new_items=[],
+            current_agent=starting_agent,
+            raw_responses=[],
+            final_output=None,
+            is_complete=False,
+            current_turn=0,
+            max_turns=max_turns,
+            input_guardrail_results=[],
+            output_guardrail_results=[],
+            _current_agent_output_schema=output_schema,
+            trace=new_trace,
+            context_wrapper=context_wrapper,
+        )
+
+        streamed_result._run_impl_task = asyncio.create_task(
+            self._start_streaming(
+                starting_input=input,
+                streamed_result=streamed_result,
+                starting_agent=starting_agent,
+                max_turns=max_turns,
+                hooks=hooks,
+                context_wrapper=context_wrapper,
+                run_config=run_config,
+                previous_response_id=previous_response_id,
+                session=session,
+            )
+        )
+        return streamed_result
+
+    @classmethod
+    async def _maybe_filter_model_input(
+        cls,
+        *,
+        agent: Agent[TContext],
+        run_config: RunConfig,
+        context_wrapper: RunContextWrapper[TContext],
+        input_items: list[TResponseInputItem],
+        system_instructions: str | None,
+    ) -> ModelInputData:
+        """Apply optional call_model_input_filter to modify model input.
+
+        Returns a `ModelInputData` that will be sent to the model.
+        """
+        effective_instructions = system_instructions
+        effective_input: list[TResponseInputItem] = input_items
+
+        if run_config.call_model_input_filter is None:
+            return ModelInputData(input=effective_input, instructions=effective_instructions)
+
+        try:
+            model_input = ModelInputData(
+                input=effective_input.copy(),
+                instructions=effective_instructions,
+            )
+            filter_payload: CallModelData[TContext] = CallModelData(
+                model_data=model_input,
+                agent=agent,
+                context=context_wrapper.context,
+            )
+            maybe_updated = run_config.call_model_input_filter(filter_payload)
+            updated = await maybe_updated if inspect.isawaitable(maybe_updated) else maybe_updated
+            if not isinstance(updated, ModelInputData):
+                raise UserError("call_model_input_filter must return a ModelInputData instance")
+            return updated
+        except Exception as e:
+            _error_tracing.attach_error_to_current_span(
+                SpanError(message="Error in call_model_input_filter", data={"error": str(e)})
+            )
+            raise
+
+    @classmethod
+    async def _run_input_guardrails_with_queue(
+        cls,
+        agent: Agent[Any],
+        guardrails: list[InputGuardrail[TContext]],
+        input: str | list[TResponseInputItem],
+        context: RunContextWrapper[TContext],
+        streamed_result: RunResultStreaming,
+        parent_span: Span[Any],
+    ):
+        """Run input guardrails concurrently and enqueue results during streaming."""
+        queue = streamed_result._input_guardrail_queue
+
+        # We'll run the guardrails and push them onto the queue as they complete
+        guardrail_tasks = [
+            asyncio.create_task(
+                RunImpl.run_single_input_guardrail(agent, guardrail, input, context)
+            )
+            for guardrail in guardrails
+        ]
+        guardrail_results = []
+        try:
+            for done in asyncio.as_completed(guardrail_tasks):
+                result = await done
+                if result.output.tripwire_triggered:
+                    _error_tracing.attach_error_to_span(
+                        parent_span,
+                        SpanError(
+                            message="Guardrail tripwire triggered",
+                            data={
+                                "guardrail": result.guardrail.get_name(),
+                                "type": "input_guardrail",
+                            },
+                        ),
+                    )
+                queue.put_nowait(result)
+                guardrail_results.append(result)
+        except Exception:
+            for t in guardrail_tasks:
+                t.cancel()
+            raise
+
+        streamed_result.input_guardrail_results = guardrail_results
+        # Update streamed_result.input with sanitized content if available
+        for result in guardrail_results:
+            if hasattr(result.output, 'sanitized_content') and result.output.sanitized_content:
+                streamed_result.input = result.output.sanitized_content
+
+    @classmethod
+    async def _start_streaming(
+        cls,
+        starting_input: str | list[TResponseInputItem],
+        streamed_result: RunResultStreaming,
+        starting_agent: Agent[TContext],
+        max_turns: int,
+        hooks: RunHooks[TContext],
+        context_wrapper: RunContextWrapper[TContext],
+        run_config: RunConfig,
+        previous_response_id: str | None,
+        session: Session | None,
+    ):
+        """Primary loop for streaming agent executions."""
+        if streamed_result.trace:
+            streamed_result.trace.start(mark_as_current=True)
+
+        current_span: Span[AgentSpanData] | None = None
+        current_agent = starting_agent
+        current_turn = 0
+        should_run_agent_start_hooks = True
+        tool_use_tracker = AgentToolUseTracker()
+
+        streamed_result._event_queue.put_nowait(AgentUpdatedStreamEvent(new_agent=current_agent))
+
+        try:
+            # Prepare input with session if enabled
+            prepared_input = await AgentRunner._prepare_input_with_session(starting_input, session)
+
+            # Update the streamed result with the prepared input
+            streamed_result.input = prepared_input
+
+            while True:
+                if streamed_result.is_complete:
+                    break
+
+                all_tools = await cls._get_all_tools(current_agent, context_wrapper)
+
+                # Start an agent span if we don't have one
+                if current_span is None:
+                    handoff_names = [
+                        h.agent_name
+                        for h in await cls._get_handoffs(current_agent, context_wrapper)
+                    ]
+                    if output_schema := cls._get_output_schema(current_agent):
+                        output_type_name = output_schema.name()
+                    else:
+                        output_type_name = "str"
+
+                    current_span = agent_span(
+                        name=current_agent.name,
+                        handoffs=handoff_names,
+                        output_type=output_type_name,
+                    )
+                    current_span.start(mark_as_current=True)
+                    tool_names = [t.name for t in all_tools]
+                    current_span.span_data.tools = tool_names
+                current_turn += 1
+                streamed_result.current_turn = current_turn
+
+                if current_turn > max_turns:
+                    _error_tracing.attach_error_to_span(
+                        current_span,
+                        SpanError(
+                            message="Max turns exceeded",
+                            data={"max_turns": max_turns},
+                        ),
+                    )
+                    streamed_result._event_queue.put_nowait(QueueCompleteSentinel())
+                    break
+
+                if current_turn == 1 or isinstance(turn_result.next_step, NextStepHandoff):
+                    # Run input guardrails in the background and put the results on the queue
+                    streamed_result._input_guardrails_task = asyncio.create_task(
+                        cls._run_input_guardrails_with_queue(
+                            current_agent,
+                            current_agent.input_guardrails + (run_config.input_guardrails or []),
+                            ItemHelpers.input_to_new_input_list(prepared_input if current_turn == 1 else streamed_result.input),
+                            context_wrapper,
+                            streamed_result,
+                            current_span,
+                        )
+                    )
+                try:
+                    turn_result = await cls._run_single_turn_streamed(
+                        streamed_result,
+                        current_agent,
+                        hooks,
+                        context_wrapper,
+                        run_config,
+                        should_run_agent_start_hooks,
+                        tool_use_tracker,
+                        all_tools,
+                        previous_response_id,
+                    )
+                    should_run_agent_start_hooks = False
+
+                    streamed_result.raw_responses = streamed_result.raw_responses + [
+                        turn_result.model_response
+                    ]
+                    streamed_result.input = turn_result.original_input
+                    streamed_result.new_items = turn_result.generated_items
+
+                    if isinstance(turn_result.next_step, NextStepHandoff):
+                        current_agent = turn_result.next_step.new_agent
+                        # Update input with sanitized content from input guardrails for handoff
+                        for result in streamed_result.input_guardrail_results:
+                            if hasattr(result.output, 'sanitized_content') and result.output.sanitized_content:
+                                streamed_result.input = result.output.sanitized_content
+                        current_span.finish(reset_current=True)
+                        current_span = None
+                        should_run_agent_start_hooks = True
+                        streamed_result._event_queue.put_nowait(
+                            AgentUpdatedStreamEvent(new_agent=current_agent)
+                        )
+                    elif isinstance(turn_result.next_step, NextStepFinalOutput):
+                        streamed_result._output_guardrails_task = asyncio.create_task(
+                            cls._run_output_guardrails(
+                                current_agent.output_guardrails
+                                + (run_config.output_guardrails or []),
+                                current_agent,
+                                turn_result.next_step.output,
+                                context_wrapper,
+                            )
+                        )
+
+                        try:
+                            output_guardrail_results = await streamed_result._output_guardrails_task
+                        except Exception:
+                            output_guardrail_results = []
+
+                        streamed_result.output_guardrail_results = output_guardrail_results
+                        # Use sanitized content as final output if available
+                        final_output = turn_result.next_step.output
+                        for result in output_guardrail_results:
+                            if hasattr(result.output, 'sanitized_content') and result.output.sanitized_content:
+                                final_output = result.output.sanitized_content
+                        streamed_result.final_output = final_output
+                        streamed_result.is_complete = True
+
+                        # Save the conversation to session if enabled
+                        temp_result = RunResult(
+                            input=streamed_result.input,
+                            new_items=streamed_result.new_items,
+                            raw_responses=streamed_result.raw_responses,
+                            final_output=streamed_result.final_output,
+                            _last_agent=current_agent,
+                            input_guardrail_results=streamed_result.input_guardrail_results,
+                            output_guardrail_results=streamed_result.output_guardrail_results,
+                            context_wrapper=context_wrapper,
+                        )
+                        await AgentRunner._save_result_to_session(
+                            session, starting_input, temp_result
+                        )
+
+                        streamed_result._event_queue.put_nowait(QueueCompleteSentinel())
+                    elif isinstance(turn_result.next_step, NextStepRunAgain):
+                        pass
+                except AgentsException as exc:
+                    streamed_result.is_complete = True
+                    streamed_result._event_queue.put_nowait(QueueCompleteSentinel())
+                    exc.run_data = RunErrorDetails(
+                        input=streamed_result.input,
+                        new_items=streamed_result.new_items,
+                        raw_responses=streamed_result.raw_responses,
+                        last_agent=current_agent,
+                        context_wrapper=context_wrapper,
+                        input_guardrail_results=streamed_result.input_guardrail_results,
+                        output_guardrail_results=streamed_result.output_guardrail_results,
+                    )
+                    raise
+                except Exception as e:
+                    if current_span:
+                        _error_tracing.attach_error_to_span(
+                            current_span,
+                            SpanError(
+                                message="Error in agent run",
+                                data={"error": str(e)},
+                            ),
+                        )
+                    streamed_result.is_complete = True
+                    streamed_result._event_queue.put_nowait(QueueCompleteSentinel())
+                    raise
+
+            streamed_result.is_complete = True
+        finally:
+            if current_span:
+                current_span.finish(reset_current=True)
+            if streamed_result.trace:
+                streamed_result.trace.finish(reset_current=True)
+
+    @classmethod
+    async def _run_single_turn_streamed(
+        cls,
+        streamed_result: RunResultStreaming,
+        agent: Agent[TContext],
+        hooks: RunHooks[TContext],
+        context_wrapper: RunContextWrapper[TContext],
+        run_config: RunConfig,
+        should_run_agent_start_hooks: bool,
+        tool_use_tracker: AgentToolUseTracker,
+        all_tools: list[Tool],
+        previous_response_id: str | None,
+    ) -> SingleStepResult:
+        """Execute a single streamed agent turn including tools and guardrails."""
+        if should_run_agent_start_hooks:
+            await asyncio.gather(
+                hooks.on_agent_start(context_wrapper, agent),
+                (
+                    agent.hooks.on_start(context_wrapper, agent)
+                    if agent.hooks
+                    else _coro.noop_coroutine()
+                ),
+            )
+
+        output_schema = cls._get_output_schema(agent)
+
+        streamed_result.current_agent = agent
+        streamed_result._current_agent_output_schema = output_schema
+
+        system_prompt, prompt_config = await asyncio.gather(
+            agent.get_system_prompt(context_wrapper),
+            agent.get_prompt(context_wrapper),
+        )
+
+        handoffs = await cls._get_handoffs(agent, context_wrapper)
+        model = cls._get_model(agent, run_config)
+        model_settings = agent.model_settings.resolve(run_config.model_settings)
+        model_settings = RunImpl.maybe_reset_tool_choice(agent, tool_use_tracker, model_settings)
+
+        final_response: ModelResponse | None = None
+
+        input = ItemHelpers.input_to_new_input_list(streamed_result.input)
+        input.extend([item.to_input_item() for item in streamed_result.new_items])
+
+        filtered = await cls._maybe_filter_model_input(
+            agent=agent,
+            run_config=run_config,
+            context_wrapper=context_wrapper,
+            input_items=input,
+            system_instructions=system_prompt,
+        )
+
+        # Call hook just before the model is invoked, with the correct system_prompt.
+        if agent.hooks:
+            await agent.hooks.on_llm_start(
+                context_wrapper, agent, filtered.instructions, filtered.input
+            )
+
+        # 1. Stream the output events
+        async for event in model.stream_response(
+            filtered.instructions,
+            filtered.input,
+            model_settings,
+            all_tools,
+            output_schema,
+            handoffs,
+            get_model_tracing_impl(
+                run_config.tracing_disabled, run_config.trace_include_sensitive_data
+            ),
+            previous_response_id=previous_response_id,
+            prompt=prompt_config,
+        ):
+            if isinstance(event, ResponseCompletedEvent):
+                usage = (
+                    Usage(
+                        requests=1,
+                        input_tokens=event.response.usage.input_tokens,
+                        output_tokens=event.response.usage.output_tokens,
+                        total_tokens=event.response.usage.total_tokens,
+                        input_tokens_details=event.response.usage.input_tokens_details,
+                        output_tokens_details=event.response.usage.output_tokens_details,
+                    )
+                    if event.response.usage
+                    else Usage()
+                )
+                final_response = ModelResponse(
+                    output=event.response.output,
+                    usage=usage,
+                    response_id=event.response.id,
+                )
+                context_wrapper.usage.add(usage)
+
+            streamed_result._event_queue.put_nowait(RawResponsesStreamEvent(data=event))
+
+        # Call hook just after the model response is finalized.
+        if agent.hooks and final_response is not None:
+            await agent.hooks.on_llm_end(context_wrapper, agent, final_response)
+
+        # 2. At this point, the streaming is complete for this turn of the agent loop.
+        if not final_response:
+            raise ModelBehaviorError("Model did not produce a final response!")
+
+        # 3. Now, we can process the turn as we do in the non-streaming case
+        return await cls._get_single_step_result_from_streamed_response(
+            agent=agent,
+            streamed_result=streamed_result,
+            new_response=final_response,
+            output_schema=output_schema,
+            all_tools=all_tools,
+            handoffs=handoffs,
+            hooks=hooks,
+            context_wrapper=context_wrapper,
+            run_config=run_config,
+            tool_use_tracker=tool_use_tracker,
+        )
+
+    @classmethod
+    async def _run_single_turn(
+        cls,
+        *,
+        agent: Agent[TContext],
+        all_tools: list[Tool],
+        original_input: str | list[TResponseInputItem],
+        generated_items: list[RunItem],
+        hooks: RunHooks[TContext],
+        context_wrapper: RunContextWrapper[TContext],
+        run_config: RunConfig,
+        should_run_agent_start_hooks: bool,
+        tool_use_tracker: AgentToolUseTracker,
+        previous_response_id: str | None,
+    ) -> SingleStepResult:
+        """Run one non-streaming agent turn including guardrails and tools."""
+        # Ensure we run the hooks before anything else
+        if should_run_agent_start_hooks:
+            await asyncio.gather(
+                hooks.on_agent_start(context_wrapper, agent),
+                (
+                    agent.hooks.on_start(context_wrapper, agent)
+                    if agent.hooks
+                    else _coro.noop_coroutine()
+                ),
+            )
+
+        system_prompt, prompt_config = await asyncio.gather(
+            agent.get_system_prompt(context_wrapper),
+            agent.get_prompt(context_wrapper),
+        )
+
+        output_schema = cls._get_output_schema(agent)
+        handoffs = await cls._get_handoffs(agent, context_wrapper)
+        input = ItemHelpers.input_to_new_input_list(original_input)
+        input.extend([generated_item.to_input_item() for generated_item in generated_items])
+
+        new_response = await cls._get_new_response(
+            agent,
+            system_prompt,
+            input,
+            output_schema,
+            all_tools,
+            handoffs,
+            context_wrapper,
+            run_config,
+            tool_use_tracker,
+            previous_response_id,
+            prompt_config,
+        )
+
+        return await cls._get_single_step_result_from_response(
+            agent=agent,
+            original_input=original_input,
+            pre_step_items=generated_items,
+            new_response=new_response,
+            output_schema=output_schema,
+            all_tools=all_tools,
+            handoffs=handoffs,
+            hooks=hooks,
+            context_wrapper=context_wrapper,
+            run_config=run_config,
+            tool_use_tracker=tool_use_tracker,
+        )
+
+    @classmethod
+    async def _get_single_step_result_from_response(
+        cls,
+        *,
+        agent: Agent[TContext],
+        all_tools: list[Tool],
+        original_input: str | list[TResponseInputItem],
+        pre_step_items: list[RunItem],
+        new_response: ModelResponse,
+        output_schema: AgentOutputSchemaBase | None,
+        handoffs: list[Handoff],
+        hooks: RunHooks[TContext],
+        context_wrapper: RunContextWrapper[TContext],
+        run_config: RunConfig,
+        tool_use_tracker: AgentToolUseTracker,
+    ) -> SingleStepResult:
+        """Process a model response and execute any resulting tool calls."""
+        processed_response = RunImpl.process_model_response(
+            agent=agent,
+            all_tools=all_tools,
+            response=new_response,
+            output_schema=output_schema,
+            handoffs=handoffs,
+        )
+
+        tool_use_tracker.add_tool_use(agent, processed_response.tools_used)
+
+        return await RunImpl.execute_tools_and_side_effects(
+            agent=agent,
+            original_input=original_input,
+            pre_step_items=pre_step_items,
+            new_response=new_response,
+            processed_response=processed_response,
+            output_schema=output_schema,
+            hooks=hooks,
+            context_wrapper=context_wrapper,
+            run_config=run_config,
+        )
+
+    @classmethod
+    async def _get_single_step_result_from_streamed_response(
+        cls,
+        *,
+        agent: Agent[TContext],
+        all_tools: list[Tool],
+        streamed_result: RunResultStreaming,
+        new_response: ModelResponse,
+        output_schema: AgentOutputSchemaBase | None,
+        handoffs: list[Handoff],
+        hooks: RunHooks[TContext],
+        context_wrapper: RunContextWrapper[TContext],
+        run_config: RunConfig,
+        tool_use_tracker: AgentToolUseTracker,
+    ) -> SingleStepResult:
+        """Process a streamed model response and enqueue resulting events."""
+        original_input = streamed_result.input
+        pre_step_items = streamed_result.new_items
+        event_queue = streamed_result._event_queue
+
+        processed_response = RunImpl.process_model_response(
+            agent=agent,
+            all_tools=all_tools,
+            response=new_response,
+            output_schema=output_schema,
+            handoffs=handoffs,
+        )
+        new_items_processed_response = processed_response.new_items
+        tool_use_tracker.add_tool_use(agent, processed_response.tools_used)
+        RunImpl.stream_step_items_to_queue(new_items_processed_response, event_queue)
+
+        single_step_result = await RunImpl.execute_tools_and_side_effects(
+            agent=agent,
+            original_input=original_input,
+            pre_step_items=pre_step_items,
+            new_response=new_response,
+            processed_response=processed_response,
+            output_schema=output_schema,
+            hooks=hooks,
+            context_wrapper=context_wrapper,
+            run_config=run_config,
+        )
+        new_step_items = [
+            item
+            for item in single_step_result.new_step_items
+            if item not in new_items_processed_response
+        ]
+        RunImpl.stream_step_items_to_queue(new_step_items, event_queue)
+
+        return single_step_result
+
+    @classmethod
+    async def _run_input_guardrails(
+        cls,
+        agent: Agent[Any],
+        guardrails: list[InputGuardrail[TContext]],
+        input: str | list[TResponseInputItem],
+        context: RunContextWrapper[TContext],
+    ) -> list[InputGuardrailResult]:
+        """Run configured input guardrails for a given agent."""
+        if not guardrails:
+            return []
+
+        guardrail_tasks = [
+            asyncio.create_task(
+                RunImpl.run_single_input_guardrail(agent, guardrail, input, context)
+            )
+            for guardrail in guardrails
+        ]
+
+        guardrail_results = []
+
+        for done in asyncio.as_completed(guardrail_tasks):
+            result = await done
+            if result.output.tripwire_triggered:
+                # Cancel all guardrail tasks if a tripwire is triggered.
+                for t in guardrail_tasks:
+                    t.cancel()
+                _error_tracing.attach_error_to_current_span(
+                    SpanError(
+                        message="Guardrail tripwire triggered",
+                        data={"guardrail": result.guardrail.get_name()},
+                    )
+                )
+                raise InputGuardrailTripwireTriggered(result)
+            else:
+                guardrail_results.append(result)
+
+        return guardrail_results
+
+    @classmethod
+    async def _run_output_guardrails(
+        cls,
+        guardrails: list[OutputGuardrail[TContext]],
+        agent: Agent[TContext],
+        agent_output: Any,
+        context: RunContextWrapper[TContext],
+    ) -> list[OutputGuardrailResult]:
+        """Run configured output guardrails for a given agent output."""
+        if not guardrails:
+            return []
+
+        guardrail_tasks = [
+            asyncio.create_task(
+                RunImpl.run_single_output_guardrail(guardrail, agent, agent_output, context)
+            )
+            for guardrail in guardrails
+        ]
+
+        guardrail_results = []
+
+        for done in asyncio.as_completed(guardrail_tasks):
+            result = await done
+            if result.output.tripwire_triggered:
+                # Cancel all guardrail tasks if a tripwire is triggered.
+                for t in guardrail_tasks:
+                    t.cancel()
+                _error_tracing.attach_error_to_current_span(
+                    SpanError(
+                        message="Guardrail tripwire triggered",
+                        data={"guardrail": result.guardrail.get_name()},
+                    )
+                )
+                raise OutputGuardrailTripwireTriggered(result)
+            else:
+                guardrail_results.append(result)
+
+        return guardrail_results
+
+    @classmethod
+    async def _get_new_response(
+        cls,
+        agent: Agent[TContext],
+        system_prompt: str | None,
+        input: list[TResponseInputItem],
+        output_schema: AgentOutputSchemaBase | None,
+        all_tools: list[Tool],
+        handoffs: list[Handoff],
+        context_wrapper: RunContextWrapper[TContext],
+        run_config: RunConfig,
+        tool_use_tracker: AgentToolUseTracker,
+        previous_response_id: str | None,
+        prompt_config: ResponsePromptParam | None,
+    ) -> ModelResponse:
+        """Call the model provider to obtain a new response for this turn."""
+        # Allow user to modify model input right before the call, if configured
+        filtered = await cls._maybe_filter_model_input(
+            agent=agent,
+            run_config=run_config,
+            context_wrapper=context_wrapper,
+            input_items=input,
+            system_instructions=system_prompt,
+        )
+
+        model = cls._get_model(agent, run_config)
+        model_settings = agent.model_settings.resolve(run_config.model_settings)
+        model_settings = RunImpl.maybe_reset_tool_choice(agent, tool_use_tracker, model_settings)
+        # If the agent has hooks, we need to call them before and after the LLM call
+        if agent.hooks:
+            await agent.hooks.on_llm_start(
+                context_wrapper,
+                agent,
+                filtered.instructions,  # Use filtered instructions
+                filtered.input,  # Use filtered input
+            )
+
+        new_response = await model.get_response(
+            system_instructions=filtered.instructions,
+            input=filtered.input,
+            model_settings=model_settings,
+            tools=all_tools,
+            output_schema=output_schema,
+            handoffs=handoffs,
+            tracing=get_model_tracing_impl(
+                run_config.tracing_disabled, run_config.trace_include_sensitive_data
+            ),
+            previous_response_id=previous_response_id,
+            prompt=prompt_config,
+        )
+        # If the agent has hooks, we need to call them after the LLM call
+        if agent.hooks:
+            await agent.hooks.on_llm_end(context_wrapper, agent, new_response)
+
+        context_wrapper.usage.add(new_response.usage)
+
+        return new_response
+
+    @classmethod
+    def _get_output_schema(cls, agent: Agent[Any]) -> AgentOutputSchemaBase | None:
+        """Resolve the output schema for the provided agent."""
+        if agent.output_type is None or agent.output_type is str:
+            return None
+        elif isinstance(agent.output_type, AgentOutputSchemaBase):
+            return agent.output_type
+
+        return AgentOutputSchema(agent.output_type)
+
+    @classmethod
+    async def _get_handoffs(
+        cls, agent: Agent[Any], context_wrapper: RunContextWrapper[Any]
+    ) -> list[Handoff]:
+        """Collect enabled handoffs for the given agent."""
+        handoffs = []
+        for handoff_item in agent.handoffs:
+            if isinstance(handoff_item, Handoff):
+                handoffs.append(handoff_item)
+            elif isinstance(handoff_item, Agent):
+                handoffs.append(handoff(handoff_item))
+
+        async def _check_handoff_enabled(handoff_obj: Handoff) -> bool:
+            """Determine whether a handoff should run for the current context."""
+            attr = handoff_obj.is_enabled
+            if isinstance(attr, bool):
+                return attr
+            res = attr(context_wrapper, agent)
+            if inspect.isawaitable(res):
+                return bool(await res)
+            return bool(res)
+
+        results = await asyncio.gather(*(_check_handoff_enabled(h) for h in handoffs))
+        enabled: list[Handoff] = [h for h, ok in zip(handoffs, results) if ok]
+        return enabled
+
+    @classmethod
+    async def _get_all_tools(
+        cls, agent: Agent[Any], context_wrapper: RunContextWrapper[Any]
+    ) -> list[Tool]:
+        """Gather all tools available to the agent from hooks and config."""
+        return await agent.get_all_tools(context_wrapper)
+
+    @classmethod
+    def _get_model(cls, agent: Agent[Any], run_config: RunConfig) -> Model:
+        """Resolve which model to call for this agent run."""
+        if isinstance(run_config.model, Model):
+            return run_config.model
+        elif isinstance(run_config.model, str):
+            return run_config.model_provider.get_model(run_config.model)
+        elif isinstance(agent.model, Model):
+            return agent.model
+
+        return run_config.model_provider.get_model(agent.model)
+
+    @classmethod
+    async def _prepare_input_with_session(
+        cls,
+        input: str | list[TResponseInputItem],
+        session: Session | None,
+    ) -> str | list[TResponseInputItem]:
+        """Prepare input by combining it with session history if enabled."""
+        if session is None:
+            return input
+
+        # Validate that we don't have both a session and a list input, as this creates
+        # ambiguity about whether the list should append to or replace existing session history
+        if isinstance(input, list):
+            raise UserError(
+                "Cannot provide both a session and a list of input items. "
+                "When using session memory, provide only a string input to append to the "
+                "conversation, or use session=None and provide a list to manually manage "
+                "conversation history."
+            )
+
+        # Get previous conversation history
+        history = await session.get_items()
+
+        # Convert input to list format
+        new_input_list = ItemHelpers.input_to_new_input_list(input)
+
+        # Combine history with new input
+        combined_input = history + new_input_list
+
+        return combined_input
+
+    @classmethod
+    async def _save_result_to_session(
+        cls,
+        session: Session | None,
+        original_input: str | list[TResponseInputItem],
+        result: RunResult,
+    ) -> None:
+        """Save the conversation turn to session."""
+        if session is None:
+            return
+
+        # Convert original input to list format if needed
+        input_list = ItemHelpers.input_to_new_input_list(original_input)
+
+        # Convert new items to input format
+        new_items_as_input = [item.to_input_item() for item in result.new_items]
+
+        # Save all items from this turn
+        items_to_save = input_list + new_items_as_input
+        await session.add_items(items_to_save)
+
+
+DEFAULT_AGENT_RUNNER = AgentRunner()
+
+
+def _copy_str_or_list(input: str | list[TResponseInputItem]) -> str | list[TResponseInputItem]:
+    """Return a shallow copy of list inputs while leaving strings untouched."""
+    if isinstance(input, str):
+        return input
+    return input.copy()