Second round of corrections

Author: DanieleMorotti

src/agents/items.py

@@ -73,6 +73,9 @@
 
 T = TypeVar("T", bound=Union[TResponseOutputItem, TResponseInputItem])
 
+# Distinguish a missing dict entry from an explicit None value.
+_MISSING_ATTR_SENTINEL = object()
+
 
 @dataclass
 class RunItemBase(Generic[T], abc.ABC):
@@ -95,18 +98,38 @@ def __post_init__(self) -> None:
         # Store a weak reference so we can release the strong reference later if desired.
         self._agent_ref = weakref.ref(self.agent)
 
-    def __getattr__(self, name: str) -> Any:
+    def __getattribute__(self, name: str) -> Any:
         if name == "agent":
-            return self._agent_ref() if self._agent_ref else None
-        raise AttributeError(name)
+            return self._get_agent_via_weakref("agent", "_agent_ref")
+        return super().__getattribute__(name)
 
     def release_agent(self) -> None:
         """Release the strong reference to the agent while keeping a weak reference."""
         if "agent" not in self.__dict__:
             return
         agent = self.__dict__["agent"]
+        if agent is None:
+            return
         self._agent_ref = weakref.ref(agent) if agent is not None else None
-        object.__delattr__(self, "agent")
+        # Set to None instead of deleting so dataclass repr/asdict keep working.
+        self.__dict__["agent"] = None
+
+    def _get_agent_via_weakref(self, attr_name: str, ref_name: str) -> Any:
+        # Preserve the dataclass field so repr/asdict still read it, but lazily resolve the weakref
+        # when the stored value is None (meaning release_agent already dropped the strong ref).
+        # If the attribute was never overridden we fall back to the default descriptor chain.
+        data = object.__getattribute__(self, "__dict__")
+        value = data.get(attr_name, _MISSING_ATTR_SENTINEL)
+        if value is _MISSING_ATTR_SENTINEL:
+            return object.__getattribute__(self, attr_name)
+        if value is not None:
+            return value
+        ref = object.__getattribute__(self, ref_name)
+        if ref is not None:
+            agent = ref()
+            if agent is not None:
+                return agent
+        return None
 
     def to_input_item(self) -> TResponseInputItem:
         """Converts this item into an input item suitable for passing to the model."""
@@ -172,23 +195,30 @@ def __post_init__(self) -> None:
         self._source_agent_ref = weakref.ref(self.source_agent)
         self._target_agent_ref = weakref.ref(self.target_agent)
 
-    def __getattr__(self, name: str) -> Any:
+    def __getattribute__(self, name: str) -> Any:
         if name == "source_agent":
-            return self._source_agent_ref() if self._source_agent_ref else None
+            # Provide lazy weakref access like the base `agent` field so HandoffOutputItem
+            # callers keep seeing the original agent until GC occurs.
+            return self._get_agent_via_weakref("source_agent", "_source_agent_ref")
         if name == "target_agent":
-            return self._target_agent_ref() if self._target_agent_ref else None
-        return super().__getattr__(name)
+            # Same as above but for the target of the handoff.
+            return self._get_agent_via_weakref("target_agent", "_target_agent_ref")
+        return super().__getattribute__(name)
 
     def release_agent(self) -> None:
         super().release_agent()
         if "source_agent" in self.__dict__:
             source_agent = self.__dict__["source_agent"]
-            self._source_agent_ref = weakref.ref(source_agent) if source_agent is not None else None
-            object.__delattr__(self, "source_agent")
+            if source_agent is not None:
+                self._source_agent_ref = weakref.ref(source_agent)
+            # Preserve dataclass fields for repr/asdict while dropping strong refs.
+            self.__dict__["source_agent"] = None
         if "target_agent" in self.__dict__:
             target_agent = self.__dict__["target_agent"]
-            self._target_agent_ref = weakref.ref(target_agent) if target_agent is not None else None
-            object.__delattr__(self, "target_agent")
+            if target_agent is not None:
+                self._target_agent_ref = weakref.ref(target_agent)
+            # Preserve dataclass fields for repr/asdict while dropping strong refs.
+            self.__dict__["target_agent"] = None
 
 
 ToolCallItemTypes: TypeAlias = Union[

src/agents/result.py

@@ -75,24 +75,27 @@ class RunResultBase(abc.ABC):
     def last_agent(self) -> Agent[Any]:
         """The last agent that was run."""
 
-    def release_agents(self) -> None:
+    def release_agents(self, *, release_new_items: bool = True) -> None:
         """
         Release strong references to agents held by this result. After calling this method,
         accessing `item.agent` or `last_agent` may return `None` if the agent has been garbage
         collected. Callers can use this when they are done inspecting the result and want to
         eagerly drop any associated agent graph.
         """
-        for item in self.new_items:
-            release = getattr(item, "release_agent", None)
-            if callable(release):
-                release()
+        if release_new_items:
+            for item in self.new_items:
+                release = getattr(item, "release_agent", None)
+                if callable(release):
+                    release()
         self._release_last_agent_reference()
 
     def __del__(self) -> None:
         try:
             # Fall back to releasing agents automatically in case the caller never invoked
-            # `release_agents()` explicitly. This keeps the no-leak guarantee confirmed by tests.
-            self.release_agents()
+            # `release_agents()` explicitly so GC of the RunResult drops the last strong reference.
+            # We pass `release_new_items=False` so RunItems that the user intentionally keeps
+            # continue exposing their originating agent until that agent itself is collected.
+            self.release_agents(release_new_items=False)
         except Exception:
             # Avoid raising from __del__.
             pass
@@ -164,7 +167,8 @@ def _release_last_agent_reference(self) -> None:
         if agent is None:
             return
         self._last_agent_ref = weakref.ref(agent)
-        object.__delattr__(self, "_last_agent")
+        # Preserve dataclass field so repr/asdict continue to succeed.
+        self.__dict__["_last_agent"] = None
 
     def __str__(self) -> str:
         return pretty_print_result(self)
@@ -244,7 +248,8 @@ def _release_last_agent_reference(self) -> None:
         if agent is None:
             return
         self._current_agent_ref = weakref.ref(agent)
-        object.__delattr__(self, "current_agent")
+        # Preserve dataclass field so repr/asdict continue to succeed.
+        self.__dict__["current_agent"] = None
 
     def cancel(self, mode: Literal["immediate", "after_turn"] = "immediate") -> None:
         """Cancel the streaming run.

src/agents/run.py

@@ -648,51 +648,60 @@ async def run(
                     tool_input_guardrail_results.extend(turn_result.tool_input_guardrail_results)
                     tool_output_guardrail_results.extend(turn_result.tool_output_guardrail_results)
 
-                    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,
-                        )
-                        result = RunResult(
-                            input=original_input,
-                            new_items=generated_items,
-                            raw_responses=model_responses,
-                            final_output=turn_result.next_step.output,
-                            _last_agent=current_agent,
-                            input_guardrail_results=input_guardrail_results,
-                            output_guardrail_results=output_guardrail_results,
-                            tool_input_guardrail_results=tool_input_guardrail_results,
-                            tool_output_guardrail_results=tool_output_guardrail_results,
-                            context_wrapper=context_wrapper,
-                        )
-                        if not any(
-                            guardrail_result.output.tripwire_triggered
-                            for guardrail_result in input_guardrail_results
-                        ):
-                            await self._save_result_to_session(
-                                session, [], turn_result.new_step_items
+                    try:
+                        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,
+                            )
+                            result = RunResult(
+                                input=original_input,
+                                new_items=generated_items,
+                                raw_responses=model_responses,
+                                final_output=turn_result.next_step.output,
+                                _last_agent=current_agent,
+                                input_guardrail_results=input_guardrail_results,
+                                output_guardrail_results=output_guardrail_results,
+                                tool_input_guardrail_results=tool_input_guardrail_results,
+                                tool_output_guardrail_results=tool_output_guardrail_results,
+                                context_wrapper=context_wrapper,
                             )
+                            if not any(
+                                guardrail_result.output.tripwire_triggered
+                                for guardrail_result in input_guardrail_results
+                            ):
+                                await self._save_result_to_session(
+                                    session, [], turn_result.new_step_items
+                                )
 
-                        return result
-                    elif isinstance(turn_result.next_step, NextStepHandoff):
-                        current_agent = cast(Agent[TContext], turn_result.next_step.new_agent)
-                        current_span.finish(reset_current=True)
-                        current_span = None
-                        should_run_agent_start_hooks = True
-                    elif isinstance(turn_result.next_step, NextStepRunAgain):
-                        if not any(
-                            guardrail_result.output.tripwire_triggered
-                            for guardrail_result in input_guardrail_results
-                        ):
-                            await self._save_result_to_session(
-                                session, [], turn_result.new_step_items
+                            return result
+                        elif isinstance(turn_result.next_step, NextStepHandoff):
+                            current_agent = cast(Agent[TContext], turn_result.next_step.new_agent)
+                            current_span.finish(reset_current=True)
+                            current_span = None
+                            should_run_agent_start_hooks = True
+                        elif isinstance(turn_result.next_step, NextStepRunAgain):
+                            if not any(
+                                guardrail_result.output.tripwire_triggered
+                                for guardrail_result in input_guardrail_results
+                            ):
+                                await self._save_result_to_session(
+                                    session, [], turn_result.new_step_items
+                                )
+                        else:
+                            raise AgentsException(
+                                f"Unknown next step type: {type(turn_result.next_step)}"
                             )
-                    else:
-                        raise AgentsException(
-                            f"Unknown next step type: {type(turn_result.next_step)}"
-                        )
+                    finally:
+                        # RunImpl.execute_tools_and_side_effects returns a SingleStepResult that
+                        # stores direct references to the `pre_step_items` and `new_step_items`
+                        # lists it manages internally. Clear them here so the next turn does not
+                        # hold on to items from previous turns and to avoid leaking agent refs.
+                        turn_result.pre_step_items.clear()
+                        turn_result.new_step_items.clear()
             except AgentsException as exc:
                 exc.run_data = RunErrorDetails(
                     input=original_input,

tests/test_items_helpers.py

@@ -2,6 +2,7 @@
 
 import gc
 import json
+import weakref
 
 from openai.types.responses.response_computer_tool_call import (
     ActionScreenshot,
@@ -30,6 +31,7 @@
 
 from agents import (
     Agent,
+    HandoffOutputItem,
     ItemHelpers,
     MessageOutputItem,
     ModelResponse,
@@ -152,14 +154,59 @@ def test_text_message_outputs_across_list_of_runitems() -> None:
 def test_message_output_item_retains_agent_until_release() -> None:
     # Construct the run item with an inline agent to ensure the run item keeps a strong reference.
     message = make_message([ResponseOutputText(annotations=[], text="hello", type="output_text")])
-    item = MessageOutputItem(agent=Agent(name="inline"), raw_item=message)
-    assert item.agent is not None
+    agent = Agent(name="inline")
+    item = MessageOutputItem(agent=agent, raw_item=message)
+    assert item.agent is agent
     assert item.agent.name == "inline"
 
-    # After explicitly releasing, the weak reference should drop once GC runs.
+    # Releasing the agent should keep the weak reference alive while strong refs remain.
     item.release_agent()
+    assert item.agent is agent
+
+    agent_ref = weakref.ref(agent)
+    del agent
     gc.collect()
+
+    # Once the original agent is collected, the weak reference should drop.
+    assert agent_ref() is None
+    assert item.agent is None
+
+
+def test_handoff_output_item_retains_agents_until_gc() -> None:
+    raw_item: TResponseInputItem = {
+        "call_id": "call1",
+        "output": "handoff",
+        "type": "function_call_output",
+    }
+    owner_agent = Agent(name="owner")
+    source_agent = Agent(name="source")
+    target_agent = Agent(name="target")
+    item = HandoffOutputItem(
+        agent=owner_agent,
+        raw_item=raw_item,
+        source_agent=source_agent,
+        target_agent=target_agent,
+    )
+
+    item.release_agent()
+    assert item.agent is owner_agent
+    assert item.source_agent is source_agent
+    assert item.target_agent is target_agent
+
+    owner_ref = weakref.ref(owner_agent)
+    source_ref = weakref.ref(source_agent)
+    target_ref = weakref.ref(target_agent)
+    del owner_agent
+    del source_agent
+    del target_agent
+    gc.collect()
+
+    assert owner_ref() is None
+    assert source_ref() is None
+    assert target_ref() is None
     assert item.agent is None
+    assert item.source_agent is None
+    assert item.target_agent is None
 
 
 def test_tool_call_output_item_constructs_function_call_output_dict():