docs: document concurrent invocations and idempotency in the agent loop

[BV-Venky]

Description

Documentation Update for idempotency semantics in Agent Loop

Related Issues

#1365

##Related PRs
#1937 #2932

Type of Change

Documentation update

[BV-Venky]

CC: @zastrowm

[github-actions]

Documentation Preview Ready

Your documentation preview has been successfully deployed!

Changed pages:

• user-guide/concepts/agents/agent-loop

Updated at: 2026-06-24T20:53:39.078Z

[zastrowm]

Content looks good - can we simplify and move to tabs to make it obvious when someone has TS selected as the language in the nav

[github-actions]

Assessment: Approve

Clean, well-scoped docs addition. I verified every technical claim against the Python SDK source and they all hold; nothing inline to flag.

Review detail

Accuracy (audited against strands-py source) — all correct:

• ConcurrencyException and IdempotencyAbortedError exist in strands.types.exceptions; import paths resolve.
• idempotency_token is a real param on __call__, invoke_async, and stream_async.
• ConcurrentInvocationMode (THROW default, UNSAFE_REENTRANT) and the concurrent_invocation_mode constructor arg exist in strands.types.agent.
• The subtle behavioral claims match the implementation: a deduplicated call gets the final result only (not streamed events), callback_handler still fires once with it (agent.py ~1138-1146), tokens compared by == (need not be hashable), and UNSAFE_REENTRANT ignores the token.
• The "Python SDK only" callout is accurate — strands-ts has no equivalent public API.

Voice/style — passes: concept-based headings, no em-dashes or banned phrases, code examples are structurally complete with realistic values. The long one-sentence-per-line paragraphs exceed 90 chars but match this file's established prose convention, so not a concern.

Nice job grounding the prose in the actual semantics — the note that a deduplicated call still drives its callback_handler is exactly the kind of non-obvious detail readers need.