Clarify Copy Type for tools and handoffs in Agent.clone() Documentation #1293

Description

The documentation for Agent.clone() does not explain whether the tools and handoffs lists are shallow-copied or deep-copied.
This leads to ambiguity when cloning agents, as developers may accidentally share references to the same tool or handoff objects, causing unintended side effects.

From reviewing the implementation, both lists are shallow-copied:

• New list objects are created.

• The elements inside (tools and handoffs) remain the same references.

Steps to Reproduce

from openai.agents import Agent, function_tool, handoff

@function_tool
def greet(name: str) -> str:
    return f"Hello, {name}!"

target_agent = Agent(name="TargetAgent", instructions="Handle delegated work")
original = Agent(
    name="OriginalAgent",
    instructions="Uses tools and delegates",
    tools=[greet],
    handoffs=[handoff(target_agent)]
)

clone = original.clone(name="ClonedAgent")

print(clone.tools is original.tools)             # False (different list)
print(clone.tools[0] is original.tools[0])       # True (same tool object)
print(clone.handoffs is original.handoffs)       # False (different list)
print(clone.handoffs[0] is original.handoffs[0]) # True (same handoff object)

Result:

• tools and handoffs are shallow-copied: new list containers, same inner objects.

Expected Behavior

Documentation should clearly state:

• tools and handoffs are shallow-copied in Agent.clone().

• Cloned agents share the same tool and handoff objects.

• To customize independently, provide new lists in clone().

Suggested Fix

1. Update Agent.clone() documentation in Agents docs to include shallow-copy semantics.

2. Add inline comment in src/agents/agent.py:

   # Shallow-copy mutable lists: new lists, same elements.

3. Optional: Add a test verifying shallow-copy behavior.

Environment

• SDK Version: Latest (July 29, 2025)

• Python Version: 3.8+

• OS: Platform-independent

Labels: documentation, enhancement