[liramon2]

Description

Deprecates nine tools in favor of their migration paths. Each tool logs a deprecation warning when invoked and carries a @deprecated marker for type checkers and IDEs, following the existing pattern.

Tool	Migration path
file_read	from strands.vended_tools import read
file_write	from strands.vended_tools import write
editor	from strands.vended_tools import edit, read, write (previously pointed at file_editor, which the SDK now deprecates)
graph, workflow, agent_graph	from strands.vended_tools import graph
stop	from strands.vended_tools import stop
use_aws	AWS API MCP server
mongodb_memory (mongodb_memory, MongoDBMemoryTool)	no replacement; implement a custom MemoryStore over pymongo

• src/strands_tools/*: _DEPRECATION_MESSAGE, @deprecated marker, and runtime logger.warning; MongoDBMemoryTool uses category=None so construction does not warn. agent_graph's ad-hoc warning now uses the shared message.
• src/strands_tools/__init__.py: TYPE_CHECKING re-exports for the new deprecations.
• README.md: tool table markers, Deprecations table rows (warning in v0.8.12), behavior notes per tool, and the Before/After example now uses edit, read, write.
• tests/*: new entries in DEPRECATED_TOOLS, plus per-tool warning and marker tests.

Related Issues

N/A

Documentation PR

N/A

Type of Change

Other (please describe): deprecation

Testing

• hatch fmt --check passes
• hatch test: 1767 passed, 25 skipped, 6 failed (the test_migration_import_resolves cases above, which need the unreleased SDK)
• test_migration_import_resolves against SDK main source: 56 passed

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[liramon2]

@strandly-the-agent Review this PR. Check whether the behavior differences are accurate or need updating.

[strandly-the-agent]

TL;DR: code side is clean and matches the existing deprecation pattern exactly; the README behavior notes are mostly accurate against SDK main, but 5 of the 9 bullets need updating — one points at a server AWS has itself superseded, and four miss or misstate something a migrating user would hit. Inline suggestions on each.

• 🟡 use_aws → the linked AWS API MCP server is marked superseded by the managed AWS MCP Server; its migration guide drops READ_OPERATIONS_ONLY/REQUIRE_MUTATION_CONSENT in favour of IAM. Same link in the table row (README:246) and use_aws.py:91.
• 🟡 stop → omits the user-visible change: old tool ended with stop_reason == "tool_use" and an empty final message; new one ends with "cancelled" and message as the final assistant text.
• 🟡 workflow → says pause/resume are lost, but they were never implemented (workflow.py:1176-1180 returns "not yet implemented").
• 🟡 file_read → "documents come back as content blocks" is only true for pdf/doc/docx/xls/xlsx; the old document mode's csv/html/txt/md now return as numbered text.
• 🟡 editor → silent on the consent prompt and .bak backups going away, and that str_replace replaced all occurrences while edit replaces one.

Everything else in the bullets (graph, agent_graph, file_write, mongodb_memory, the table, the Before/After imports) checks out — details below.

✅ Verified (5b5a1aa vs d036ff9; SDK main 0a50a80)

README claims traced to source (accurate):

• read: absolute-only + .. rejected (vended_tools/_paths.py:15-20), cat -n lines, offset/limit (read/read.py:107-125), sandbox at call time (:126); old modes exactly find, view, lines, chunk, search, stats, preview, diff, time_machine, document (file_read.py:283-295).
• write: absolute-only (write/write.py:72), no prompt/preview anywhere; old BYPASS_TOOL_CONSENT + prompt (file_write.py:215,244). BeforeToolCallEvent is _Interruptible (hooks/events.py:221), so the hook-interrupt recipe is real.
• edit: uniqueness enforced, 0 or >1 matches → ValueError (edit/edit.py:73-77).
• graph: params task/nodes/edges (graph/graph.py:162-166), entry points = no incoming edges (:47), cycles rejected (:314-317), make_graph(tools=Choice(..., multiple=True), model=Choice(...), max_nodes, max_edges, max_node_executions, execution_timeout, node_timeout) (:86-101), tools/model default to Inherit() (multiagent/spec.py:277-280). Old lifecycle create/execute/status/list/delete (strands_tools/graph.py:553-654), entry_points, per-node model_provider/model_settings all real.
• workflow: ~/.strands/workflows (workflow.py:135), priority (:586-587), ready batch runs in parallel (multiagent/graph.py:839-843).
• agent_graph: actions create/list/stop/message/status (agent_graph.py:113), topologies star/mesh/hierarchical (:126).
• stop: agent.cancel(message, after_current_tools=True), "cancelled", 4096 default, make_stop(max_message_length=) (stop/stop.py:4-6,21,59,97). Old tool set request_state["stop_event_loop"], which the SDK still honours with a DeprecationWarning (event_loop.py:1184-1198).
• mongodb_memory: MemoryStore protocol search/add, writable (memory/types.py:263-301), add_tool_config default False (memory_manager.py:94), tools named search_memory/add_memory, ## Custom Stores anchor exists (managing-memory.mdx:376). Old actions record/retrieve/list/get/delete.
• AWS API MCP README: call_aws, suggest_aws_commands, both env vars default "false", consent via elicitation — accurate for that server; but its README line 4 says it is superseded, and MIGRATION.md:103-104 maps READ_OPERATIONS_ONLY → IAM / proxy --read-only, REQUIRE_MUTATION_CONSENT → "Not needed — use IAM policies".
• from strands.vended_tools import edit, read, shell, sleep, write, graph, stop imports in a fresh venv off SDK main. Latest tag is v0.8.11, so v0.8.12 is right.

Code/tests (independent reviewer pass):

• Pattern matches batch.py/shell.py precedent byte-for-byte (literal @deprecated message + 5-line comment; @tool outermost for the 4 @tool tools, bare @deprecated for the 5 TOOL_SPEC tools; MongoDBMemoryTool mirrors ElasticsearchMemoryTool).
• pytest tests/test_{agent_graph,editor,file_read,file_write,graph,mongodb_memory,stop,use_aws,workflow}.py → 273 passed. tests/test_deprecations.py → 300 passed / 4 skipped / 7 failed: the 6 known unreleased-SDK test_migration_import_resolves cases + a2a_client, which also fails on base (missing a2a extra in the venv). ruff check / ruff format --check clean.
• mypy --enable-error-code deprecated reports all 10 new markers (incl. the @tool-wrapped ones). Five TOOL_SPEC tools still register in ToolRegistry after wrapping; invoking stop logs the warning and returns success.
• README ⚠️ markers, Deprecations rows and DEPRECATED_TOOLS cross-checked programmatically: consistent.

Questions (non-blocking)

• Should use_aws's _DEPRECATION_MESSAGE and table row point at the managed AWS MCP Server (with the migration guide) rather than the superseded self-hosted one? I verified the successor docs and MIGRATION.md resolve, but did not test Strands' MCPClient against mcp-proxy-for-aws end to end — worth a quick check before committing to that wording.

Reading order

1. README #### Behavior differences new bullets (411-444) and the edited editor bullet (271-273) — the substance.
2. One @tool tool (graph.py:415-416) and one TOOL_SPEC tool (stop.py:67-71) — the rest are copies of the pattern.
3. tests/test_deprecations.py DEPRECATED_TOOLS additions.

Appendix — non-blocking (7)

• ⚪ stop bullet: "sibling tool calls in the same batch still run" was also true of the old tool (flag checked after the batch, event_loop.py:1184); reads as a change when it isn't.
• ⚪ file_read bullet: ~ is no longer expanded (old expanduser, file_read.py:241; read rejects as non-absolute).
• ⚪ editor bullet: view of a directory (tree listing, editor.py:514-516) has no read equivalent — shell covers it.
• ⚪ graph bullet: old tool already auto-detected entry_points when omitted (strands_tools/graph.py:468), so "go away" is a smaller change than it reads; edge keys change from/to → from_node/to_node.
• ⚪ file_write bullet: a link to the Interrupts page would help — "raise an interrupt from a hook" compresses a multi-step recipe.
• ⚪ agent_graph.py:532: the logger.warning sits 10 lines into the body (edited in place) rather than first-after-docstring like every other tool here; no behavioural difference.
• ⚪ tests/test_mongodb_memory.py:895: target.__deprecated__ lacks the getattr(..., None)/is not None guard the test_elasticsearch_memory.py:88-91 original has — a missing marker would surface as AttributeError, not an assertion.

[liramon2]

@strandly-the-agent Review this PR.

[strandly-the-agent]

TL;DR: approve. All five README findings from my first review are fixed in c5ce50a, the two code nits too, and with strands-agents 1.63.0 now on PyPI (released 19:53Z today) the previously-failing test_migration_import_resolves cases pass — the full touched suite is green.

Status of previous findings:

• use_aws → fixed (bullet, table row, _DEPRECATION_MESSAGE, test all point at the managed AWS MCP Server; aws___call_aws / --read-only match MIGRATION.md).
• stop → fixed ("tool_use" → "cancelled", message as final text, request_state note).
• workflow → fixed (pause/resume gone; status + re-start named as the real loss).
• editor → fixed (unique vs replace-all, no prompt/.bak, directory views → shell). One grammar slip inline.
• file_read → fixed-but-trimmed: "binary documents" is now correct, but the clause saying csv/html/txt/md come back as numbered text was dropped — that was the trap. ⚪ suggestion inline.
• Nits: agent_graph.py warning moved first, mongodb marker guard added, from_node/to_node and the Interrupts link added.

✅ Verified (c5ce50a; strands-agents 1.63.0)

• strands-agents==1.63.0 on PyPI: from strands.vended_tools import edit, read, write, graph, stop, make_stop, make_graph imports in a fresh venv, so the >=1.63.0 floor in pyproject.toml:154 is satisfiable.
• pytest tests/test_{deprecations,agent_graph,mongodb_memory,use_aws,stop,graph,workflow,file_read,file_write,editor}.py with 1.63.0 → 580 passed, 4 skipped, 0 failed (incl. all test_migration_import_resolves). ruff check / ruff format --check clean.
• Re-read every edited bullet (README:271-274, 412-440) against the sources cited in my first review; no new inaccuracies introduced. Interrupts #hooks anchor exists (site/.../sdk/interrupts.mdx:21).

Appendix — non-blocking (2)

• ⚪ PR description still says read/write/edit/graph are unreleased and lists 6 expected failures; 1.63.0 shipped, so that paragraph and the unchecked "dependent changes published" box are stale.
• ⚪ stop bullet dropped the make_stop(max_message_length=...) pointer when it was rewritten; "capped at 4096 by default" now has no "how to raise it". Optional.