docs(production): add agent execution boundaries

[March-77]

Motivation

Production agents need explicit execution boundaries for predictable cost,
latency, and resource usage. The production operations guide covered general
performance practices but did not explain how to prevent runaway model/tool
loops or unbounded multi-agent execution.

Fixes #2593

Changes

• add an Execution Limits section under Performance Optimization
• cover per-invocation turn, output-token, and total-token budgets in Python and
  TypeScript
• distinguish invocation token budgets from per-response model limits
• point to the cross-language tool-count hook pattern
• explain deadline cancellation and cooperative cancellation inside tools
• document orchestrator- and node-level boundaries for Swarm and Graph
• link directly to the existing limits, cancellation, stop-reason, hook, and
  multi-agent references

Documentation PR

This is a documentation-only change. It uses the current first-class invocation
limits and current Python/TypeScript multi-agent configuration rather than
introducing new examples or APIs.

Type of Change

Documentation

Testing

• Documentation TypeScript checks passed

• Documentation snippet type-checks passed

• Site build: 857 pages, 856 HTML files, no broken links

• Verified the rendered page contains the new sections and cross-links

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have reviewed and understand every line of code in this PR, including any generated by AI tools, and I can explain why it works
• My change is focused and reasonably small; I have split unrelated work into separate PRs
• 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]

Documentation Preview Ready

Your documentation preview has been successfully deployed!

Changed pages:

• user-guide/deploy/operating-agents-in-production

Updated at: 2026-08-14T16:01:58.570Z

[JackYPCOnline]

@strandly-the-agent does this PR match our newest codebase? Is this guideline correct and meaningful?

[strandly-the-agent]

Verdict: accurate against current main — nothing technical is wrong. 3 × 🟡 wording fixes before merge.

JackYPCOnline asked two things. Short answers: yes, it matches the newest codebase (every API name, parameter, stop reason, semantic claim and cross-link anchor in the new section traces to main @ 14d2759), and yes, the guidance is correct and meaningful — it's a pointer-style summary that defers to agent-loop.mdx rather than duplicating it, and "don't rely on only one boundary" is the non-obvious operational point. Fixes #2593 is the right keyword: every acceptance criterion on that issue is met.

The three 🟡 are wording, not substance: two spell out both language variants in prose where .agents/references/mdx-authoring.md:38 requires <Syntax>, and one leaves the TypeScript option unnamed. Suggestions are inline.

✅ Reviewed PR head f389d5c against main 14d2759 · ✅ all 12 factual claims traced to file:line (table below) · ✅ all 6 links + anchors resolve · ✅ git merge-tree main pr3457 → no conflicts; no commit has touched this file since 2026-07-24 · ⚠️ site build not run (no npm install in this sandbox) — link style validated from site/src/util/links.ts:94-95 instead, where .md is stripped during slug resolution

Is the missing <Tabs>/<Syntax> treatment in scope? <Syntax> yes — it's a hard repo rule and a one-line fix per site (the 🟡s). Converting the section to full <Tabs> with code blocks is out of scope here: the section has no code blocks at all, and #2593's clarifying exchange chose conceptual-only. Flagged as a question below rather than a change request.

Claim-by-claim: added prose vs. current main (12/12 accurate)

Added prose (operating-agents-in-production.mdx)	Source of truth	Status
:74-75 limits argument (Py) / option (TS) bounds turns	strands-py/src/strands/types/agent.py:17-49 — Limits TypedDict (turns, output_tokens, total_tokens); strands-ts/src/types/agent.ts:154-190 — limits?: { turns, outputTokens, totalTokens }	✅ same name both SDKs
:78-81 Limit Tool Counts hook "same pattern for Python and TypeScript … resets counts for each invocation"	concepts/agents/hooks.mdx:852 (both tabs); TS snippet limit_tool_counts_class in hooks.ts resets on BeforeInvocationEvent, Python does the same	✅
:84-86 "Invocation token limits are checked between turns, so one model call can exceed the configured total"	types/agent.py:22-24 ("checked at the top of each loop iteration") + :39-40 ("Soft cap: a single oversized response can overshoot the budget"); enforced at event_loop/event_loop.py:67-101 (_check_limits, priority turns → total → output)	✅ exactly right, including the soft-cap caveat
:83-84 model max_tokens/maxTokens caps a single response	strands-py/src/strands/models/bedrock.py:158; strands-ts/src/models/model.ts:99 (BaseModelConfig.maxTokens)	✅ (wording → 🟡 #2)
:88 Python agent.cancel() from a watchdog	strands-py/src/strands/agent/agent.py:592, backed by a thread-safe threading.Event at :357; the watchdog-thread pattern is the documented one at agent-loop.mdx:129-147	✅
:89 TS "pass an AbortSignal or call agent.cancel()"	strands-ts/src/types/agent.ts:136 (cancelSignal?: AbortSignal), composed with the internal controller via AbortSignal.any at strands-ts/src/agent/agent.ts:1098-1099	✅ (under-specified → 🟡 #3)
:87 "Enforce a deadline outside the invocation"	Correct: there is no timeout option on either invoke surface — none in strands-ts/src/types/agent.ts, none in strands-py/.../agent.py	✅
:89-91 cancellation is cooperative inside a running tool	TS: strands-ts/src/agent/agent.ts:975-978 (tools forward agent.cancelSignal); Py: agent-loop.mdx checkpoint table — "Non-MCP tools finish before cancellation is observed"	✅ (one caveat, appendix)
:102-104 Swarm — Py handoffs/iterations + total/per-node time; TS maxSteps, timeout, nodeTimeout	multi-agent/swarm.mdx:113-119 (max_handoffs, max_iterations, execution_timeout, node_timeout) and :130-138 (TS)	✅ exact match
:105-107 Graph — total node executions + total/per-node time, "names differ by SDK"	multi-agent/graph.mdx:76-78 (set_max_node_executions(), set_execution_timeout(), set_node_timeout()) and :105-108 (maxSteps, timeout, nodeTimeout)	✅
:93-96 Stop Reasons link "for handling exhausted limits as expected outcomes"	agent-loop.mdx:94-96 lists the three limit stop reasons, matching strands-py/src/strands/types/event_loop.py:46-48 and event_loop.py:93-99	✅ the link delivers what it promises
6 cross-links + anchors	agent-loop.mdx:191 (#invocation-limits), :110 (#cancellation), :87 (#stop-reasons), hooks.mdx:852, swarm.mdx:375, graph.mdx:45 — all real headings; .md suffix is stripped at site/src/util/links.ts:94-95	✅ all resolve

Scope check — Fixes #2593

#2593 is a docs request from Unshure, so a docs section can close it. Its acceptance criteria map 1:1 onto this diff: an "Execution Limits" subsection under "## Performance Optimization" (:65-67, which is the placement the requester explicitly picked), all four limit types (:74-91), cross-refs to the hook docs and to Swarm/Graph safety mechanisms (:78, :102-107), and both languages named. Nothing in the diff goes beyond the issue.

No duplicate ownership: agent-loop.mdx#invocation-limits remains the source of truth (the limits feature was documented by #2638 on 2026-06-08) and this section links to it instead of restating it — which is also why it introduces no new examples. A repo-wide grep for "Execution Limits"/"Invocation Limits" finds only those two places, and git log --since=2026-07-01 on this file is empty.

Questions (non-blocking)

❓ Every sibling section on this page (Agent Initialization, Tool Management, Conversation Management, Streaming, Error Handling) carries a code block; this one carries none, and #2593's criteria list "Python examples included" / "TypeScript equivalents included" as separate checkboxes — though the clarifying answer on the issue chose conceptual-only, so prose is a defensible reading. Worth an explicit call: inlining the short limits={...} snippet that already exists at agent-loop.mdx:196-208 would make the section match its neighbours without turning it into a tutorial.

Appendix — non-blocking (2)

• ⚪ :89-91 — "propagate the same deadline to downstream network calls" is true for both SDKs, but only TypeScript exposes a signal a tool can forward (agent.cancelSignal, strands-ts/src/agent/agent.ts:975-978). Python's is private (agent._cancel_signal, strands-py/src/strands/agent/agent.py:357) with no public accessor, so a Python tool has to enforce its own deadline. One clause would save a reader hunting for a Python equivalent that isn't there.
• ⚪ Not a defect, just to close the loop on the staleness question: the branch is ~2 weeks behind main, but nothing it describes drifted in that window and it merges clean, so no rebase is needed for correctness.

Suppressed as noise: "Execution Limits" as a heading next to the existing "Invocation Limits" (broader scope — covers tool counts and wall clock too — so not a terminology-lock violation); TS provider-specific maxOutputTokens spellings (the SDK-facing name really is maxTokens, per strands-ts/src/models/vercel.ts:72).

How this was reviewed

Routing triage and the issue-alignment pass ran as independent fresh-context subagents. The docs-accuracy subagent hung past its budget and was cancelled, so that pass and the aggregation stage ran in my own context against their role files — warm, not independent. Flagging it so "no inaccuracies found" can be read for what it is. Everything in the table above I checked directly against the clone.

This is agent-generated review output — a human maintainer should approve before merge.

[March-77]

Addressed the three wording findings in e4284b5: shared limits naming is consolidated, model token settings use Syntax, and the TypeScript cancellation option is named as cancelSignal with an AbortSignal.timeout example. The documentation site build completed with no broken links. @strandly-the-agent could you re-review?