docs(agent): document clone() sharing model + address review by cogwirrel · Pull Request #2 · cogwirrel/sdk-python

cogwirrel · 2026-06-23T21:16:41Z

Self-review PR against the fork — addresses @JackYPCOnline's feedback on the upstream PR (strands-agents/harness-sdk#2902). Targets feat/agent-clone so the diff is just the review delta. Not yet pushed to the upstream PR — raised here for your review first.

Review comments addressed

1. Document the sharing model beyond inline comments (Jack: "It will be helpful if we document it other than just docstring or inline comments")

Added a user-guide page site/.../concepts/agents/clone.mdx (+ typechecked clone.ts snippets, nav entry). It covers:

the template→clone pattern and basic usage,
config, not runtime state — conversation history / accumulated state / post-construction hooks are not carried over,
a shared-vs-isolated table making explicit that model / tools / sessionManager / memoryManager / constructor plugins are shared by reference unless overridden, with the sessionManager and stateful-plugin sharp edges called out and the overrides / additionalPlugins escape hatches shown,
the lazy-MCP-resolution rationale,
how clone() relates to snapshots.

Also tightened the clone() docstring to state the shallow-share semantics directly.

2. Test assertion style (Jack: "Could you please also address this comment" — re: per-field assertions vs. TESTING.md "Object Assertion")

Collapsed the per-field assertions in the "replays the template config" test into a single toEqual shape assertion (so a dropped/extra field fails), keeping the clone.model reference-identity check as a separate toBe.

Notes

clone() is TypeScript-only, so the doc page is TS-only (marked with an Aside).
The two larger process asks from the review bot — api/needs-review label and an API reviewer — are repo-side actions for the upstream PR, not code changes; flagging here rather than actioning.

Testing

Pre-commit (build + test:coverage + lint + format + type-check) passed.
New doc snippet typechecks via test-snippets (resolves the local SDK build, which exposes clone() / AgentCloneOptions).
agent.clone.test.ts (6 tests) pass with the reworked assertion.

Add `clone(options?: CloneOptions)` to `Agent`, which builds a new agent by replaying the original `AgentConfig` through the constructor — merging `overrides` (last-wins) and appending `additionalPlugins`. The constructor now retains a shallow copy of its config so the replay carries the caller's original `tools` entries by reference. This is what lets a clone resolve unconnected `McpClient` tools lazily on its own first `stream()`: the MCP clients live in the replayed config, so each clone runs tool resolution via `initialize()` without the template ever being initialized. AG-UI's aws-strands adapter relies on this when it builds a per-thread agent from a shared template — previously callers had to call `agent.initialize()` on the template up front as a workaround. The clone replays CONFIG, not live runtime state: messages, accumulated model state, and post-construction hook registrations do not carry over. Seed those explicitly via `overrides`. Example: const template = new Agent({ model, tools: [mcpClient] }); const perThread = template.clone({ overrides: { sessionManager, printer: false }, });

github-actions · 2026-06-23T21:23:36Z