[BUG] Allow graceful recovery from MaxTokensReachedException without full agent reset

[awsbelle]

Checks

• I have updated to the latest minor and patch version of Strands
• I have checked the documentation and this is not expected behavior
• I have searched ./issues and there are no duplicates of my issue

Strands Version

1.36.0

Python Version

3.12+

Operating System

All

Installation Method

pip

Steps to Reproduce

1. Create an agent with tools
2. Invoke the agent with input that causes the model to hit the max_tokens limit
3. Catch the MaxTokensReachedException
4. Attempt to invoke the same agent instance again with a new prompt

Expected Behavior

1. When max_tokens is reached, the agent raises an exception (this is fine)
2. The caller catches the exception and can continue using the same agent instance for subsequent calls without reinitializing
3. The exception message should not say "unrecoverable state" — hitting a token budget is a recoverable, expected condition

Actual Behavior

The exception declares an "unrecoverable state" at event_loop.py line 177:

MaxTokensReachedException: Agent has reached an unrecoverable state due to max_tokens limit.

Depending on the context, the agent may not be reusable after this exception without a full reset. In hosted environments where the agent loop runs inside a managed runtime, an unrecoverable state means the entire invocation fails with no way to return partial results or gracefully degrade.

Additional Context

• Related to [BUG] MaxTokensReachedException thrown instead of returning generated content when max_tokens limit reached with OllamaModel #1320, which addressed the case where generated content was discarded on max_tokens. That issue is closed, but the recoverability concern remains.
• In the AgentCore Harness context, there are two levels of maxTokens: a per-LLM-call cap (bedrockModelConfig.maxTokens) and a top-level agent loop budget (maxTokens). Both should result in recoverable states.
• The relevant code path is in src/strands/event_loop/event_loop.py lines 167-180 where stop_reason == "max_tokens" triggers the exception.
• Recovery logic exists in src/strands/event_loop/_recover_message_on_max_tokens_reached.py but only handles tool use cleanup — it does not help the caller access partial results.

Possible Solution

1. Make the agent instance reusable after MaxTokensReachedException is raised — no internal state should be corrupted
2. Rename or update the exception message to remove "unrecoverable state" (e.g., "Agent loop stopped: max_tokens limit reached")
3. Add partial results to the exception object by accepting an optional Message dict in MaxTokensReachedException.__init__ so callers can extract whatever was generated before the limit was hit

Related Issues

#1320

[awsbelle]

/strands implement

[github-actions]

Unable to create pull request via API. You can create it manually by clicking here.

[agent-of-mkmeral]

Thanks for the detailed report @awsbelle.

We agree the error message saying "unrecoverable state" is misleading and should be updated — hitting max_tokens is a recoverable, expected condition. However, we were unable to reproduce the agent actually being in an unrecoverable state after this exception.

Could you clarify this part of your report?

Depending on the context, the agent may not be reusable after this exception without a full reset.

What context causes this? What does "not reusable" look like concretely — does the next agent("...") call raise an error? If so, what error? Or does it produce incorrect results? A minimal reproduction script showing the agent failing on a second invocation after catching MaxTokensReachedException would be very helpful.

🔍 Our reproduction attempts and findings (click to expand)

What we tested

We ran 11 adversarial test scenarios against the SDK (main branch), using mock models with the correct streaming protocol to trigger max_tokens in various situations:

#	Scenario	State Valid?	Re-invoke?
1	Pure text response hits max_tokens → re-invoke	✅	✅
2	Single tool use mid-generation → re-invoke	✅	✅
3	Multiple tool uses (3 tools) → re-invoke	✅	✅
4	Partial/broken tool input (truncated JSON) → re-invoke	✅	✅
5	Normal turn → max_tokens → normal turn (3-turn lifecycle)	✅	✅
6	5x consecutive max_tokens → normal turn	✅	✅
7	SlidingWindowConversationManager + max_tokens → re-invoke	✅	✅
8	reasoningContent + toolUse — reasoning preserved, toolUse replaced	✅	✅
9	Empty content (model returns nothing) → re-invoke	✅	✅
10	Tool round-trip → max_tokens → tool round-trip (full lifecycle)	✅	✅
11	recover_message_on_max_tokens_reached — 10 edge cases (normal toolUse, multiple toolUse, pure text, empty content, None content, missing name, broken input, metadata preservation, reasoningContent, only text)	✅	N/A

After every MaxTokensReachedException, we verified:

• 🔓 _invocation_lock — released (in stream_async finally block)
• 🚫 _cancel_signal — cleared (in stream_async finally block)
• 🧹 No orphaned toolUse blocks in agent.messages[-1] (all replaced with text by recover_message_on_max_tokens_reached)
• ↔️ No consecutive assistant messages (proper role alternation)
• ⏸️ _interrupt_state — not activated
• 🔄 Agent successfully re-invoked with a new prompt

Why it works today

Tracing the execution flow when max_tokens is hit:

1. _handle_model_execution() receives stop_reason="max_tokens" and the original message
2. It calls recover_message_on_max_tokens_reached(message) which creates a new Message dict — replacing all toolUse blocks with explanatory text
3. The recovered message (no toolUse blocks) is appended to agent.messages ✅
4. MessageAddedEvent fires → session managers persist the clean state ✅
5. event_loop_cycle() then raises MaxTokensReachedException
6. _run_loop finally block runs:
   • conversation_manager.apply_management(agent) ✅
   • AfterInvocationEvent fires → session manager syncs ✅
7. stream_async finally block runs:
   • _cancel_signal.clear() ✅
   • _invocation_lock.release() ✅

The agent state after the exception is valid: no orphaned tool calls, no lock contention, clean conversation history. Calling agent("new prompt") works correctly in every scenario we tested.

What we do agree on

1. The error message is wrong — "unrecoverable state" is factually incorrect and should be updated to something like "Agent loop stopped: max_tokens limit reached"
2. Adding last_message to the exception is a useful API improvement for callers who want partial output

We'd like to understand the specific scenario where the agent is actually not reusable before merging a fix, so we can add a targeted regression test for it. If the issue is purely about the misleading error message (which we agree is a bug), we can scope the fix accordingly.