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

[abdul-kabir-jawed]

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

[seratch]

Thanks for the feedback. The docstring of the clone() method can mention this and the reference page can have the information for developers. I will be working on the class enhancement for #1238, so I will improve the code comment as well.

[abdul-kabir-jawed]

Thanks for the update! Glad to hear this will be improved in the upcoming enhancement for #1238.

I'd be happy to help by opening a small PR that:

• Updates the Agent.clone() docstring to clarify that tools and handoffs are shallow‑copied,

• Adds the clarification to the reference docs, and

• Includes a simple test verifying the shallow‑copy behavior.

[seratch]

Thanks for sending the PR! Once the lint issue is resolved, your change will be merged

[abdul-kabir-jawed]

Fixed the lint issues. Ready for review again!