Added RunErrorDetails object for MaxTurnsExceeded exception

Author: DanieleMorotti

src/agents/__init__.py

@@ -44,7 +44,7 @@
 from .models.openai_chatcompletions import OpenAIChatCompletionsModel
 from .models.openai_provider import OpenAIProvider
 from .models.openai_responses import OpenAIResponsesModel
-from .result import RunResult, RunResultStreaming
+from .result import RunErrorDetails, RunResult, RunResultStreaming
 from .run import RunConfig, Runner
 from .run_context import RunContextWrapper, TContext
 from .stream_events import (
@@ -204,6 +204,7 @@ def enable_verbose_stdout_logging():
     "AgentHooks",
     "RunContextWrapper",
     "TContext",
+    "RunErrorDetails",
     "RunResult",
     "RunResultStreaming",
     "RunConfig",

src/agents/exceptions.py

@@ -1,7 +1,8 @@
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Optional
 
 if TYPE_CHECKING:
     from .guardrail import InputGuardrailResult, OutputGuardrailResult
+    from .result import RunErrorDetails
 
 
 class AgentsException(Exception):
@@ -12,9 +13,11 @@ class MaxTurnsExceeded(AgentsException):
     """Exception raised when the maximum number of turns is exceeded."""
 
     message: str
+    run_error_details: Optional["RunErrorDetails"]
 
-    def __init__(self, message: str):
+    def __init__(self, message: str, run_error_details: Optional["RunErrorDetails"] = None):
         self.message = message
+        self.run_error_details = run_error_details
 
 
 class ModelBehaviorError(AgentsException):

src/agents/result.py

@@ -18,7 +18,11 @@
 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_error_details,
+    pretty_print_run_result_streaming,
+)
 
 if TYPE_CHECKING:
     from ._run_impl import QueueCompleteSentinel
@@ -244,3 +248,15 @@ def _cleanup_tasks(self):
 
     def __str__(self) -> str:
         return pretty_print_run_result_streaming(self)
+
+@dataclass
+class RunErrorDetails(RunResultBase):
+    _last_agent: Agent[Any]
+
+    @property
+    def last_agent(self) -> Agent[Any]:
+        """The last agent that was run."""
+        return self._last_agent
+
+    def __str__(self) -> str:
+        return pretty_print_run_error_details(self)

src/agents/run.py

@@ -35,7 +35,7 @@
 from .model_settings import ModelSettings
 from .models.interface import Model, ModelProvider
 from .models.multi_provider import MultiProvider
-from .result import RunResult, RunResultStreaming
+from .result import RunErrorDetails, RunResult, RunResultStreaming
 from .run_context import RunContextWrapper, TContext
 from .stream_events import AgentUpdatedStreamEvent, RawResponsesStreamEvent
 from .tool import Tool
@@ -208,7 +208,20 @@ async def run(
                                 data={"max_turns": max_turns},
                             ),
                         )
-                        raise MaxTurnsExceeded(f"Max turns ({max_turns}) exceeded")
+                        run_error_details = RunErrorDetails(
+                            input=original_input,
+                            new_items=generated_items,
+                            raw_responses=model_responses,
+                            final_output=None,
+                            input_guardrail_results=input_guardrail_results,
+                            output_guardrail_results=[],
+                            context_wrapper=context_wrapper,
+                            _last_agent=current_agent
+                        )
+                        raise MaxTurnsExceeded(
+                            f"Max turns ({max_turns}) exceeded",
+                            run_error_details
+                        )
 
                     logger.debug(
                         f"Running agent {current_agent.name} (turn {current_turn})",

src/agents/util/_pretty_print.py

@@ -3,7 +3,7 @@
 from pydantic import BaseModel
 
 if TYPE_CHECKING:
-    from ..result import RunResult, RunResultBase, RunResultStreaming
+    from ..result import RunErrorDetails, RunResult, RunResultBase, RunResultStreaming
 
 
 def _indent(text: str, indent_level: int) -> str:
@@ -37,6 +37,15 @@ 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:"