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

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"