@@ -103,11 +103,18 @@ def clone(self, **kwargs: Any) -> RealtimeAgent[TContext]:
103103 """Make a copy of the agent, with the given arguments changed.
104104
105105 Notes:
106- - Uses `dataclasses.replace`, which performs a **shallow copy**.
107- - Mutable attributes like `tools` and `handoffs` are shallow-copied:
108- new list objects are created only if overridden, but their contents
109- (tool functions and handoff objects) are shared with the original.
110- - To modify these independently, pass new lists when calling `clone()`.
106+ - Uses `dataclasses.replace`, which performs a **shallow copy** and never copies a
107+ list attribute such as `tools`, `handoffs`, `mcp_servers`, or `output_guardrails`.
108+ Each of those attributes is whatever the merged arguments hold.
109+ - An attribute you do not pass arrives as the original agent's own list, so both
110+ agents hold that one list and its entries. Appending through either agent, for
111+ example `cloned.tools.append(extra_tool)`, therefore also changes the other.
112+ - An attribute you do pass is used exactly as given, so it shares a list or an entry
113+ with the original agent only where you reused one. `agent.clone(tools=agent.tools)`
114+ still shares that list, while `agent.clone(tools=[other_tool])` shares nothing.
115+ - To give the clone a list that no other agent holds, pass a new one, for example
116+ `agent.clone(tools=[*agent.tools, extra_tool])`. The entries copied into it remain
117+ the same objects the original agent holds.
111118
112119 Example:
113120 ```python
0 commit comments