strands.experimental.bidi.models.model

Bidirectional streaming model interface.

Defines the abstract interface for models that support real-time bidirectional communication with persistent connections. Unlike traditional request-response models, bidirectional models maintain an open connection for streaming audio, text, and tool interactions.

Features:

• Persistent connection management with connect/close lifecycle
• Real-time bidirectional communication (send and receive simultaneously)
• Provider-agnostic event normalization
• Support for audio, text, image, and tool result streaming

BidiModel

@runtime_checkable
class BidiModel(Protocol)

Defined in: src/strands/experimental/bidi/models/model.py:31

Protocol for bidirectional streaming models.

This interface defines the contract for models that support persistent streaming connections with real-time audio and text communication. Implementations handle provider-specific protocols while exposing a standardized event-based API.

Attributes:

• config - Configuration dictionary with provider-specific settings.

start

async def start(system_prompt: str | None = None,
                tools: list[ToolSpec] | None = None,
                messages: Messages | None = None,
                **kwargs: Any) -> None

Defined in: src/strands/experimental/bidi/models/model.py:44

Establish a persistent streaming connection with the model.

Opens a bidirectional connection that remains active for real-time communication. The connection supports concurrent sending and receiving of events until explicitly closed. Must be called before any send() or receive() operations.

Arguments:

• system_prompt - System instructions to configure model behavior.
• tools - Tool specifications that the model can invoke during the conversation.
• messages - Initial conversation history to provide context.
• **kwargs - Provider-specific configuration options.

stop

async def stop() -> None

Defined in: src/strands/experimental/bidi/models/model.py:65

Close the streaming connection and release resources.

Terminates the active bidirectional connection and cleans up any associated resources such as network connections, buffers, or background tasks. After calling close(), the model instance cannot be used until start() is called again.

receive

def receive() -> AsyncIterable[BidiOutputEvent]

Defined in: src/strands/experimental/bidi/models/model.py:74

Receive streaming events from the model.

Continuously yields events from the model as they arrive over the connection. Events are normalized to a provider-agnostic format for uniform processing. This method should be called in a loop or async task to process model responses.

The stream continues until the connection is closed or an error occurs.

Yields:

• BidiOutputEvent - Standardized event objects containing audio output, transcripts, tool calls, or control signals.

send

async def send(content: BidiInputEvent | ToolResultEvent) -> None

Defined in: src/strands/experimental/bidi/models/model.py:89

Send content to the model over the active connection.

Transmits user input or tool results to the model during an active streaming session. Supports multiple content types including text, audio, images, and tool execution results. Can be called multiple times during a conversation.

Arguments:

• content - The content to send. Must be one of:

  • BidiTextInputEvent: Text message from the user
  • BidiAudioInputEvent: Audio data for speech input
  • BidiImageInputEvent: Image data for visual understanding
  • ToolResultEvent: Result from a tool execution

Example:

await model.send(BidiTextInputEvent(text="Hello", role="user"))
await model.send(BidiAudioInputEvent(audio=bytes, format="pcm", sample_rate=16000, channels=1))
await model.send(BidiImageInputEvent(image=bytes, mime_type="image/jpeg", encoding="raw"))
await model.send(ToolResultEvent(tool_result))

BidiModelTimeoutError

class BidiModelTimeoutError(Exception)

Defined in: src/strands/experimental/bidi/models/model.py:118

Model timeout error.

Bidirectional models are often configured with a connection time limit. Nova sonic for example keeps the connection open for 8 minutes max. Upon receiving a timeout, the agent loop is configured to restart the model connection so as to create a seamless, uninterrupted experience for the user.

__init__

def __init__(message: str, **restart_config: Any) -> None

Defined in: src/strands/experimental/bidi/models/model.py:126

Initialize error.

Arguments:

• message - Timeout message from model.
• **restart_config - Configure restart specific behaviors in the call to model start.