Clarify shallow-copy behavior of tools and handoffs in Agent.clone() (#1296)

Author: abdul-kabir-jawed

src/agents/agent.py

@@ -222,10 +222,17 @@ class Agent(AgentBase, Generic[TContext]):
     to True. This ensures that the agent doesn't enter an infinite loop of tool usage."""
 
     def clone(self, **kwargs: Any) -> Agent[TContext]:
-        """Make a copy of the agent, with the given arguments changed. For example, you could do:
-        ```
-        new_agent = agent.clone(instructions="New instructions")
-        ```
+        """Make a copy of the agent, with the given arguments changed.
+        Notes:
+            - Uses `dataclasses.replace`, which performs a **shallow copy**.
+            - Mutable attributes like `tools` and `handoffs` are shallow-copied:
+              new list objects are created only if overridden, but their contents
+              (tool functions and handoff objects) are shared with the original.
+            - To modify these independently, pass new lists when calling `clone()`.
+        Example:
+            ```python
+            new_agent = agent.clone(instructions="New instructions")
+            ```
         """
         return dataclasses.replace(self, **kwargs)
 

tests/test_agent_clone_shallow_copy.py

@@ -0,0 +1,33 @@
+from agents import Agent, function_tool, handoff
+
+
+@function_tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+def test_agent_clone_shallow_copy():
+    """Test that clone creates shallow copy with tools.copy() workaround"""
+    target_agent = Agent(name="Target")
+    original = Agent(
+        name="Original",
+        instructions="Testing clone shallow copy",
+        tools=[greet],
+        handoffs=[handoff(target_agent)],
+    )
+
+    cloned = original.clone(
+        name="Cloned",
+        tools=original.tools.copy(),
+        handoffs=original.handoffs.copy()
+    )
+
+    # Basic assertions
+    assert cloned is not original
+    assert cloned.name == "Cloned"
+    assert cloned.instructions == original.instructions
+
+    # Shallow copy assertions
+    assert cloned.tools is not original.tools, "Tools should be different list"
+    assert cloned.tools[0] is original.tools[0], "Tool objects should be same instance"
+    assert cloned.handoffs is not original.handoffs, "Handoffs should be different list"
+    assert cloned.handoffs[0] is original.handoffs[0], "Handoff objects should be same instance"