feat(bidi): support request_state stop_event_loop flag

[agent-of-mkmeral]

Summary

Replace the hard-coded stop_conversation tool name check with a generic request_state["stop_event_loop"] mechanism, while keeping stop_conversation with a deprecation warning for backward compatibility.

Motivation

The previous approach hard-coded a stop_conversation tool name check in the bidi agent loop. This was:

• Inflexible: Only one specific tool could stop the conversation
• Tightly coupled: The loop checked tool names instead of a generic signal
• Redundant: strands_tools already has a stop tool that uses request_state

Changes

Deprecated (kept for backward compatibility)

• stop_conversation tool now emits DeprecationWarning when called
• Tool name check in loop also emits DeprecationWarning as a fallback
• Both the tool and its export in bidi/__init__.py are preserved

Changed

• agent/loop.py:
  • Initialize request_state in _invocation_state before tool execution
  • Primary: Check request_state.get("stop_event_loop", False) flag
  • Fallback: Check tool_use["name"] == "stop_conversation" with deprecation warning
• tools/stop_conversation.py: Added DeprecationWarning pointing users to strands_tools.stop
• tools/__init__.py: Updated docstring with deprecation notice
• io/text.py: Updated log message

Added

• test_bidi_agent_loop_stop_conversation_deprecated_but_works — verifies backward compatibility with deprecation
• test_bidi_agent_loop_stop_event_loop_flag — verifies new flag mechanism
• test_bidi_agent_loop_request_state_initialized_for_tools — verifies request_state availability
• test_bidi_agent_loop_request_state_preserved_with_invocation_state — verifies existing state preserved

Migration Path

Before (deprecated):

from strands.experimental.bidi import stop_conversation, BidiAgent
agent = BidiAgent(tools=[stop_conversation, ...])

After (recommended):

from strands_tools import stop
from strands.experimental.bidi import BidiAgent
agent = BidiAgent(tools=[stop, ...])

Or any custom tool:

@tool
def my_stop_tool(request_state: dict) -> str:
    request_state["stop_event_loop"] = True
    return "Goodbye!"

Based on: 657ddcd

[mkmeral]

also check the docs, if we need to update anything there, create a related PR. check if stop event loop is documented somewhere. also check if stop conversation tool is used, etc.

[mkmeral]

@agent-of-mkmeral we should probably keep it for now, but add a warning that we will remove in next versions. So we support both, and we can remove the tool later.

It gives users who depend on it some time

[agent-of-mkmeral]

Done! Commit 1381ba1 keeps stop_conversation with backward compatibility:

What	How
stop_conversation tool	Restored — emits DeprecationWarning when called
bidi/__init__.py export	Restored — from strands.experimental.bidi import stop_conversation works
Loop check	Primary: request_state["stop_event_loop"] flag. Fallback: tool_use["name"] == "stop_conversation" with deprecation warning
Tests	New test_bidi_agent_loop_stop_conversation_deprecated_but_works verifies both the tool works AND the warning is emitted

Users who depend on stop_conversation get a clear deprecation message pointing them to strands_tools.stop or request_state["stop_event_loop"].

[mkmeral]

@agent-of-mkmeral do we need docs update for this?

[agent-of-mkmeral]

Yes — docs definitely need updating. I found stop_conversation referenced in 7 docs files with zero mention of stop_event_loop or request_state:

File	What needs changing
agent.mdx	Line 170: "The special stop_conversation tool triggers agent shutdown" → needs update to describe request_state["stop_event_loop"] as primary, stop_conversation as deprecated fallback
events.mdx	Line 167: "user_request" reason references stop_conversation
quickstart.mdx	Lines 417-429: Full "Graceful Shutdown" section imports and uses stop_conversation
gemini_live.mdx	Example imports stop_conversation from strands.experimental.bidi.tools
openai_realtime.mdx	Same pattern — imports stop_conversation
nova_sonic.mdx	Same pattern — imports stop_conversation
io.mdx	6 separate code examples using stop_conversation

I'll create a docs PR now that:

1. Updates examples to show strands_tools.stop as the recommended approach
2. Adds deprecation notices for stop_conversation imports
3. Documents the request_state["stop_event_loop"] mechanism for custom tools
4. Keeps stop_conversation mentions with deprecation context (matching the SDK backward compat)

[agent-of-mkmeral]

📝 Docs PR created: strands-agents/docs#696

Updated 7 files across the bidi streaming docs:

• agent.mdx — primary shutdown mechanism now describes request_state["stop_event_loop"]
• events.mdx — user_request close reason updated
• quickstart.mdx — full "Graceful Shutdown" rewrite with migration examples
• nova_sonic.mdx, gemini_live.mdx, openai_realtime.mdx — all examples migrated
• io.mdx — all 6 code examples migrated

All from strands.experimental.bidi.tools import stop_conversation → from strands_tools import stop, with deprecation notices added.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[agent-of-mkmeral]

📊 PR Status Summary

Item	Status
CI	✅ All 12 checks passing (Python 3.10-3.14, Linux/macOS/Windows)
Codecov	✅ All modified lines covered
Mergeable	✅ Yes (blocked — needs maintainer approval)
Review feedback	✅ All addressed
Docs PR	✅ strands-agents/docs#696 created (awaiting review)

What was done

1. stop_conversation kept with DeprecationWarning for backward compatibility (commit 1381ba1)
2. Primary mechanism: request_state["stop_event_loop"] flag
3. Fallback: tool_use["name"] == "stop_conversation" check with deprecation warning
4. Tests added: Backward compat test + new flag mechanism test + request_state initialization tests
5. Docs PR: Updated 7 files across bidi streaming docs to reflect migration path

Ready for merge when you're ready! 🚀

[mkmeral]

/strands review

[github-actions]

Assessment: Approve

This PR cleanly aligns the BidiAgent loop with the standard event loop's stop_event_loop mechanism while maintaining backward compatibility for existing stop_conversation users.

Review Summary

• Design: Follows the established pattern from event_loop.py for request_state initialization (lines 123-124)
• Backward Compatibility: Graceful deprecation path with clear warnings pointing to strands_tools.stop
• Testing: Four new comprehensive tests covering initialization, stop flag mechanism, deprecation path, and state preservation
• Documentation: PR created at docs(bidi): migrate stop_conversation to strands_tools.stop and request_state docs#696

The dual deprecation warning approach (from both the tool and the loop) provides good visibility for migration. 🚀