feat: add documentation for interventions primitive in python

[mehtarac]

Description

• This PR adds documentation for the python interventions primitive added in this PR.

Related Issues

#2667

Documentation PR

Type of Change

Documentation update

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce new warnings.

• I ran hatch run prepare

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, or no new docs are needed
• 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.

[github-actions]

Assessment: Comment

Solid Python documentation addition for the interventions primitive. I verified the examples against the actual SDK source (strands-py/src/strands/interventions/) — the action signatures, tool_use keys, event.* attributes, on_error/OnError, the lifecycle/action compatibility table, the synchronous agent("...") call style, and all cross-page links all check out. Snippet markers also line up cleanly with the TypeScript counterpart. Just a few minor copy-paste/correctness nits below.

Review Categories

• Copy-paste completeness: Inline snippet imports omit the event types used in annotations, so pasted snippets NameError. Python snippets aren't type-checked by site tooling, so these aren't caught automatically.
• Public vs internal imports: OnError is imported from an internal module path despite being re-exported publicly.
• Formatting: A few rendered lines exceed the 90-char doc-snippet guideline.

Nice work keeping the Python and TypeScript examples structurally parallel — it makes the tabbed page very easy to follow.

[github-actions]

Re-review (after commits dc8d60c3 and a349096b)

Assessment: Comment — nearly there.

Thanks for the quick turnaround. Verified against the updated branch:

Status of prior feedback

• ✅ OnError public import — now from strands.interventions import Deny, InterventionHandler, OnError, Proceed (L180).
• ✅ Line length — all rendered snippet lines are now under 90 chars. (Only the module-level import on L2 is at 95, but it sits outside the snippet markers so it isn't rendered — no action needed.)
• ✅ Caution blocks → prose (notowen333) — no aside/caution blocks remain.
• ✅ Shared-section syntax (notowen333) — <Syntax py=... ts=... /> is used consistently across shared sections.
• ⚠️ Copy-paste completeness — still open: event-type annotations (BeforeToolCallEvent, AfterModelCallEvent) aren't imported inside the snippet markers, so a pasted snippet still NameErrors. Details in the inline thread.

Just the one copy-paste item left to close out.

[github-actions]

Documentation Preview Ready

Your documentation preview has been successfully deployed!

Changed pages:

• user-guide/concepts/agents/interventions

Updated at: 2026-06-15T15:35:12.014Z

[github-actions]

Re-review (after commit 9df7d72d — move inline examples to referenced snippets)

Assessment: Comment — one item left.

Nice restructure. Verified against the latest branch:

Status

• ✅ Inline → referenced snippets (notowen333) — all 10 code blocks in index.mdx are now --8<-- snippet references; no inline examples remain.
• ✅ New confirm snippet — API-accurate: Confirm(prompt=..., response=...) matches the Confirm dataclass fields, and the preemptive-response AutoApprove example matches the documented "agent never pauses" behavior in actions.py.
• ✅ Prior items (OnError public import, line length, caution-blocks→prose, shared-section <Syntax>) all remain resolved.
• ⚠️ Copy-paste completeness — still open, and the new confirm snippet (L237, L248) introduces the same gap: event-type annotations (BeforeToolCallEvent, AfterModelCallEvent) aren't imported inside any snippet marker, so pasted Python snippets still NameError. (The inline thread was marked resolved prematurely — re-opened with details.)

Everything else is in good shape — just the event-type imports to wrap up.

[notowen333]

small conventions callouts

[github-actions]

Re-review (after commit 5bace504 — rename snippet files + add TS imports file)

Assessment: Comment — one item left.

Verified the rename and new structure against the branch:

Status

• ✅ File naming convention (notowen333) — index.py/index.ts renamed to interventions.py/interventions.ts, matching the steering / human-in-the-loop pattern. All .mdx snippet references updated; no stale index.* references remain.
• ✅ TS imports file (notowen333 "this doesn't have imports") — new interventions_imports.ts added with per-snippet import blocks, referenced before each TS snippet in the .mdx.
• ⚠️ Copy-paste completeness (Python) — still open. The new TS interventions_imports.ts correctly imports the event types (BeforeToolCallEvent, AfterModelCallEvent, OnError), but the Python snippets in interventions.py still omit them despite using the annotations — so pasted Python snippets NameError, and there's now a Python↔TS asymmetry. Details in the inline thread.

Structure and naming are now in great shape — just the Python event-type imports to bring them in line with the TS side.