Merge branch 'main' of https://github.com/openai/openai-agents-python into fix/parallel_tool_calls

Author: Rehan-Ul-Haq

docs/ja/tracing.md

@@ -119,4 +119,5 @@ async def main():
 -   [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents)
 -   [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents)
 -   [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk)
--   [Okahu‑Monocle](https://github.com/monocle2ai/monocle)
+-   [Okahu‑Monocle](https://github.com/monocle2ai/monocle)
+-   [Portkey AI](https://portkey.ai/docs/integrations/agents/openai-agents)

docs/mcp.md

@@ -8,7 +8,7 @@ The Agents SDK has support for MCP. This enables you to use a wide range of MCP
 
 ## MCP servers
 
-Currently, the MCP spec defines two kinds of servers, based on the transport mechanism they use:
+Currently, the MCP spec defines three kinds of servers, based on the transport mechanism they use:
 
 1. **stdio** servers run as a subprocess of your application. You can think of them as running "locally".
 2. **HTTP over SSE** servers run remotely. You connect to them via a URL.

docs/tools.md

@@ -270,7 +270,7 @@ The `agent.as_tool` function is a convenience method to make it easy to turn an
 ```python
 @function_tool
 async def run_my_agent() -> str:
-  """A tool that runs the agent with custom configs".
+    """A tool that runs the agent with custom configs"""
 
     agent = Agent(name="My agent", instructions="...")
 

docs/tracing.md

@@ -116,3 +116,4 @@ To customize this default setup, to send traces to alternative or additional bac
 -   [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk)
 -   [Okahu-Monocle](https://github.com/monocle2ai/monocle)
 -   [Galileo](https://v2docs.galileo.ai/integrations/openai-agent-integration#openai-agent-integration)
+-   [Portkey AI](https://portkey.ai/docs/integrations/agents/openai-agents)

examples/agent_patterns/input_guardrails.py

@@ -20,7 +20,7 @@
 Guardrails are checks that run in parallel to the agent's execution.
 They can be used to do things like:
 - Check if input messages are off-topic
-- Check that output messages don't violate any policies
+- Check that input messages don't violate any policies
 - Take over control of the agent's execution if an unexpected input is detected
 
 In this example, we'll setup an input guardrail that trips if the user is asking to do math homework.

src/agents/__init__.py

@@ -14,6 +14,7 @@
     MaxTurnsExceeded,
     ModelBehaviorError,
     OutputGuardrailTripwireTriggered,
+    RunErrorDetails,
     UserError,
 )
 from .guardrail import (
@@ -204,6 +205,7 @@ def enable_verbose_stdout_logging():
     "AgentHooks",
     "RunContextWrapper",
     "TContext",
+    "RunErrorDetails",
     "RunResult",
     "RunResultStreaming",
     "RunConfig",

src/agents/agent_output.py

@@ -38,7 +38,7 @@ def json_schema(self) -> dict[str, Any]:
     @abc.abstractmethod
     def is_strict_json_schema(self) -> bool:
         """Whether the JSON schema is in strict mode. Strict mode constrains the JSON schema
-        features, but guarantees valis JSON. See here for details:
+        features, but guarantees valid JSON. See here for details:
         https://platform.openai.com/docs/guides/structured-outputs#supported-schemas
         """
         pass

src/agents/exceptions.py

@@ -1,11 +1,39 @@
-from typing import TYPE_CHECKING
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
+    from .agent import Agent
     from .guardrail import InputGuardrailResult, OutputGuardrailResult
+    from .items import ModelResponse, RunItem, TResponseInputItem
+    from .run_context import RunContextWrapper
+
+from .util._pretty_print import pretty_print_run_error_details
+
+
+@dataclass
+class RunErrorDetails:
+    """Data collected from an agent run when an exception occurs."""
+    input: str | list[TResponseInputItem]
+    new_items: list[RunItem]
+    raw_responses: list[ModelResponse]
+    last_agent: Agent[Any]
+    context_wrapper: RunContextWrapper[Any]
+    input_guardrail_results: list[InputGuardrailResult]
+    output_guardrail_results: list[OutputGuardrailResult]
+
+    def __str__(self) -> str:
+        return pretty_print_run_error_details(self)
 
 
 class AgentsException(Exception):
     """Base class for all exceptions in the Agents SDK."""
+    run_data: RunErrorDetails | None
+
+    def __init__(self, *args: object) -> None:
+        super().__init__(*args)
+        self.run_data = None
 
 
 class MaxTurnsExceeded(AgentsException):
@@ -15,6 +43,7 @@ class MaxTurnsExceeded(AgentsException):
 
     def __init__(self, message: str):
         self.message = message
+        super().__init__(message)
 
 
 class ModelBehaviorError(AgentsException):
@@ -26,6 +55,7 @@ class ModelBehaviorError(AgentsException):
 
     def __init__(self, message: str):
         self.message = message
+        super().__init__(message)
 
 
 class UserError(AgentsException):
@@ -35,15 +65,16 @@ class UserError(AgentsException):
 
     def __init__(self, message: str):
         self.message = message
+        super().__init__(message)
 
 
 class InputGuardrailTripwireTriggered(AgentsException):
     """Exception raised when a guardrail tripwire is triggered."""
 
-    guardrail_result: "InputGuardrailResult"
+    guardrail_result: InputGuardrailResult
     """The result data of the guardrail that was triggered."""
 
-    def __init__(self, guardrail_result: "InputGuardrailResult"):
+    def __init__(self, guardrail_result: InputGuardrailResult):
         self.guardrail_result = guardrail_result
         super().__init__(
             f"Guardrail {guardrail_result.guardrail.__class__.__name__} triggered tripwire"
@@ -53,10 +84,10 @@ def __init__(self, guardrail_result: "InputGuardrailResult"):
 class OutputGuardrailTripwireTriggered(AgentsException):
     """Exception raised when a guardrail tripwire is triggered."""
 
-    guardrail_result: "OutputGuardrailResult"
+    guardrail_result: OutputGuardrailResult
     """The result data of the guardrail that was triggered."""
 
-    def __init__(self, guardrail_result: "OutputGuardrailResult"):
+    def __init__(self, guardrail_result: OutputGuardrailResult):
         self.guardrail_result = guardrail_result
         super().__init__(
             f"Guardrail {guardrail_result.guardrail.__class__.__name__} triggered tripwire"

src/agents/extensions/models/litellm_model.py

@@ -5,7 +5,6 @@
 from collections.abc import AsyncIterator
 from typing import Any, Literal, cast, overload
 
-import litellm.types
 from openai.types.responses.response_usage import InputTokensDetails, OutputTokensDetails
 
 from agents.exceptions import ModelBehaviorError

src/agents/handoffs.py

@@ -168,7 +168,7 @@ def handoff(
         input_filter: a function that filters the inputs that are passed to the next agent.
     """
     assert (on_handoff and input_type) or not (on_handoff and input_type), (
-        "You must provide either both on_input and input_type, or neither"
+        "You must provide either both on_handoff and input_type, or neither"
     )
     type_adapter: TypeAdapter[Any] | None
     if input_type is not None:

src/agents/result.py

@@ -11,14 +11,22 @@
 from ._run_impl import QueueCompleteSentinel
 from .agent import Agent
 from .agent_output import AgentOutputSchemaBase
-from .exceptions import InputGuardrailTripwireTriggered, MaxTurnsExceeded
+from .exceptions import (
+    AgentsException,
+    InputGuardrailTripwireTriggered,
+    MaxTurnsExceeded,
+    RunErrorDetails,
+)
 from .guardrail import InputGuardrailResult, OutputGuardrailResult
 from .items import ItemHelpers, ModelResponse, RunItem, TResponseInputItem
 from .logger import logger
 from .run_context import RunContextWrapper
 from .stream_events import StreamEvent
 from .tracing import Trace
-from .util._pretty_print import pretty_print_result, pretty_print_run_result_streaming
+from .util._pretty_print import (
+    pretty_print_result,
+    pretty_print_run_result_streaming,
+)
 
 if TYPE_CHECKING:
     from ._run_impl import QueueCompleteSentinel
@@ -206,31 +214,53 @@ async def stream_events(self) -> AsyncIterator[StreamEvent]:
         if self._stored_exception:
             raise self._stored_exception
 
+    def _create_error_details(self) -> RunErrorDetails:
+        """Return a `RunErrorDetails` object considering the current attributes of the class."""
+        return RunErrorDetails(
+            input=self.input,
+            new_items=self.new_items,
+            raw_responses=self.raw_responses,
+            last_agent=self.current_agent,
+            context_wrapper=self.context_wrapper,
+            input_guardrail_results=self.input_guardrail_results,
+            output_guardrail_results=self.output_guardrail_results,
+        )
+
     def _check_errors(self):
         if self.current_turn > self.max_turns:
-            self._stored_exception = MaxTurnsExceeded(f"Max turns ({self.max_turns}) exceeded")
+            max_turns_exc = MaxTurnsExceeded(f"Max turns ({self.max_turns}) exceeded")
+            max_turns_exc.run_data = self._create_error_details()
+            self._stored_exception = max_turns_exc
 
         # Fetch all the completed guardrail results from the queue and raise if needed
         while not self._input_guardrail_queue.empty():
             guardrail_result = self._input_guardrail_queue.get_nowait()
             if guardrail_result.output.tripwire_triggered:
-                self._stored_exception = InputGuardrailTripwireTriggered(guardrail_result)
+                tripwire_exc = InputGuardrailTripwireTriggered(guardrail_result)
+                tripwire_exc.run_data = self._create_error_details()
+                self._stored_exception = tripwire_exc
 
         # Check the tasks for any exceptions
         if self._run_impl_task and self._run_impl_task.done():
-            exc = self._run_impl_task.exception()
-            if exc and isinstance(exc, Exception):
-                self._stored_exception = exc
+            run_impl_exc = self._run_impl_task.exception()
+            if run_impl_exc and isinstance(run_impl_exc, Exception):
+                if isinstance(run_impl_exc, AgentsException) and run_impl_exc.run_data is None:
+                    run_impl_exc.run_data = self._create_error_details()
+                self._stored_exception = run_impl_exc
 
         if self._input_guardrails_task and self._input_guardrails_task.done():
-            exc = self._input_guardrails_task.exception()
-            if exc and isinstance(exc, Exception):
-                self._stored_exception = exc
+            in_guard_exc = self._input_guardrails_task.exception()
+            if in_guard_exc and isinstance(in_guard_exc, Exception):
+                if isinstance(in_guard_exc, AgentsException) and in_guard_exc.run_data is None:
+                    in_guard_exc.run_data = self._create_error_details()
+                self._stored_exception = in_guard_exc
 
         if self._output_guardrails_task and self._output_guardrails_task.done():
-            exc = self._output_guardrails_task.exception()
-            if exc and isinstance(exc, Exception):
-                self._stored_exception = exc
+            out_guard_exc = self._output_guardrails_task.exception()
+            if out_guard_exc and isinstance(out_guard_exc, Exception):
+                if isinstance(out_guard_exc, AgentsException) and out_guard_exc.run_data is None:
+                    out_guard_exc.run_data = self._create_error_details()
+                self._stored_exception = out_guard_exc
 
     def _cleanup_tasks(self):
         if self._run_impl_task and not self._run_impl_task.done():
@@ -244,3 +274,4 @@ def _cleanup_tasks(self):
 
     def __str__(self) -> str:
         return pretty_print_run_result_streaming(self)
+

src/agents/run.py

@@ -1,3 +1,4 @@
+
 from __future__ import annotations
 
 import asyncio
@@ -26,6 +27,7 @@
     MaxTurnsExceeded,
     ModelBehaviorError,
     OutputGuardrailTripwireTriggered,
+    RunErrorDetails,
 )
 from .guardrail import InputGuardrail, InputGuardrailResult, OutputGuardrail, OutputGuardrailResult
 from .handoffs import Handoff, HandoffInputFilter, handoff
@@ -208,7 +210,9 @@ async def run(
                                 data={"max_turns": max_turns},
                             ),
                         )
-                        raise MaxTurnsExceeded(f"Max turns ({max_turns}) exceeded")
+                        raise MaxTurnsExceeded(
+                            f"Max turns ({max_turns}) exceeded"
+                        )
 
                     logger.debug(
                         f"Running agent {current_agent.name} (turn {current_turn})",
@@ -283,6 +287,17 @@ async def run(
                         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)
@@ -609,6 +624,19 @@ async def _run_streamed_impl(
                         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(

src/agents/stream_events.py

@@ -31,6 +31,7 @@ class RunItemStreamEvent:
     name: Literal[
         "message_output_created",
         "handoff_requested",
+        # This is misspelled, but we can't change it because that would be a breaking change
         "handoff_occured",
         "tool_called",
         "tool_output",

src/agents/util/_pretty_print.py

@@ -3,6 +3,7 @@
 from pydantic import BaseModel
 
 if TYPE_CHECKING:
+    from ..exceptions import RunErrorDetails
     from ..result import RunResult, RunResultBase, RunResultStreaming
 
 
@@ -38,6 +39,17 @@ def pretty_print_result(result: "RunResult") -> str:
     return output
 
 
+def pretty_print_run_error_details(result: "RunErrorDetails") -> str:
+    output = "RunErrorDetails:"
+    output += f'\n- Last agent: Agent(name="{result.last_agent.name}", ...)'
+    output += f"\n- {len(result.new_items)} new item(s)"
+    output += f"\n- {len(result.raw_responses)} raw response(s)"
+    output += f"\n- {len(result.input_guardrail_results)} input guardrail result(s)"
+    output += "\n(See `RunErrorDetails` for more details)"
+
+    return output
+
+
 def pretty_print_run_result_streaming(result: "RunResultStreaming") -> str:
     output = "RunResultStreaming:"
     output += f'\n- Current agent: Agent(name="{result.current_agent.name}", ...)'