Merge branch 'main' of https://github.com/strands-agents/sdk-python into swarm-interrupt

Author: pgrayy

.github/workflows/test-lint.yml

@@ -59,6 +59,20 @@ jobs:
         uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
+      - name: Install system audio dependencies (Linux)
+        if: matrix.os-name == 'linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y portaudio19-dev libasound2-dev
+      - name: Install system audio dependencies (macOS)
+        if: matrix.os-name == 'macOS'
+        run: |
+          brew install portaudio
+      - name: Install system audio dependencies (Windows)
+        if: matrix.os-name == 'windows'
+        run: |
+          # Windows typically has audio libraries available by default
+          echo "Windows audio dependencies handled by PyAudio wheels"
       - name: Install dependencies
         run: |
           pip install --no-cache-dir hatch
@@ -89,6 +103,11 @@ jobs:
           python-version: '3.10'
           cache: 'pip'
 
+      - name: Install system audio dependencies (Linux)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y portaudio19-dev libasound2-dev
+
       - name: Install dependencies
         run: |
           pip install --no-cache-dir hatch
@@ -97,3 +116,4 @@ jobs:
         id: lint
         run: hatch fmt --linter --check
         continue-on-error: false
+

.gitignore

@@ -13,3 +13,4 @@ dist
 repl_state
 .kiro
 uv.lock
+.audio_cache

README.md

@@ -197,6 +197,74 @@ agent("What is the square root of 1764")
 
 It's also available on GitHub via [strands-agents/tools](https://github.com/strands-agents/tools).
 
+### Bidirectional Streaming
+
+> **⚠️ Experimental Feature**: Bidirectional streaming is currently in experimental status. APIs may change in future releases as we refine the feature based on user feedback and evolving model capabilities.
+
+Build real-time voice and audio conversations with persistent streaming connections. Unlike traditional request-response patterns, bidirectional streaming maintains long-running conversations where users can interrupt, provide continuous input, and receive real-time audio responses. Get started with your first BidiAgent by following the [Quickstart](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/experimental/bidirectional-streaming/quickstart) guide. 
+
+**Supported Model Providers:**
+- Amazon Nova Sonic (`amazon.nova-sonic-v1:0`)
+- Google Gemini Live (`gemini-2.5-flash-native-audio-preview-09-2025`)
+- OpenAI Realtime API (`gpt-realtime`)
+
+**Quick Example:**
+
+```python
+import asyncio
+from strands.experimental.bidi import BidiAgent
+from strands.experimental.bidi.models import BidiNovaSonicModel
+from strands.experimental.bidi.io import BidiAudioIO, BidiTextIO
+from strands.experimental.bidi.tools import stop_conversation
+from strands_tools import calculator
+
+async def main():
+    # Create bidirectional agent with audio model
+    model = BidiNovaSonicModel()
+    agent = BidiAgent(model=model, tools=[calculator, stop_conversation])
+
+    # Setup audio and text I/O
+    audio_io = BidiAudioIO()
+    text_io = BidiTextIO()
+
+    # Run with real-time audio streaming
+    # Say "stop conversation" to gracefully end the conversation
+    await agent.run(
+        inputs=[audio_io.input()],
+        outputs=[audio_io.output(), text_io.output()]
+    )
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+**Configuration Options:**
+
+```python
+# Configure audio settings
+model = BidiNovaSonicModel(
+    provider_config={
+        "audio": {
+            "input_rate": 16000,
+            "output_rate": 16000,
+            "voice": "matthew"
+        },
+        "inference": {
+            "max_tokens": 2048,
+            "temperature": 0.7
+        }
+    }
+)
+
+# Configure I/O devices
+audio_io = BidiAudioIO(
+    input_device_index=0,  # Specific microphone
+    output_device_index=1,  # Specific speaker
+    input_buffer_size=10,
+    output_buffer_size=10
+)
+```
+
 ## Documentation
 
 For detailed guidance & examples, explore our documentation:

pyproject.toml

@@ -69,7 +69,18 @@ a2a = [
     "fastapi>=0.115.12,<1.0.0",
     "starlette>=0.46.2,<1.0.0",
 ]
+
+bidi = [
+    "aws_sdk_bedrock_runtime; python_version>='3.12'",
+    "prompt_toolkit>=3.0.0,<4.0.0",
+    "pyaudio>=0.2.13,<1.0.0",
+    "smithy-aws-core>=0.0.1; python_version>='3.12'",
+]
+bidi-gemini = ["google-genai>=1.32.0,<2.0.0"]
+bidi-openai = ["websockets>=15.0.0,<16.0.0"]
+
 all = ["strands-agents[a2a,anthropic,docs,gemini,litellm,llamaapi,mistral,ollama,openai,writer,sagemaker,otel]"]
+bidi-all = ["strands-agents[a2a,bidi,bidi-gemini,bidi-openai,docs,otel]"]
 
 dev = [
     "commitizen>=4.4.0,<5.0.0",
@@ -104,9 +115,10 @@ features = ["all"]
 dependencies = [
   "mypy>=1.15.0,<2.0.0",
   "ruff>=0.13.0,<0.14.0",
-  # Include required pacakge dependencies for mypy
+  # Include required package dependencies for mypy
   "strands-agents @ {root:uri}",
 ]
+python = "3.10"
 
 # Define static-analysis scripts so we can include mypy as part of the linting check
 [tool.hatch.envs.hatch-static-analysis.scripts]
@@ -118,7 +130,7 @@ format-fix = [
 ]
 lint-check = [
     "ruff check",
-    "mypy -p src"
+    "mypy ./src"
 ]
 lint-fix = [
     "ruff check --fix"
@@ -192,11 +204,16 @@ warn_no_return = true
 warn_unreachable = true
 follow_untyped_imports = true
 ignore_missing_imports = false
+exclude = ["src/strands/experimental/bidi"]
 
+[[tool.mypy.overrides]]
+module = ["strands.experimental.bidi.*"]
+follow_imports = "skip"
 
 [tool.ruff]
 line-length = 120
 include = ["examples/**/*.py", "src/**/*.py", "tests/**/*.py", "tests_integ/**/*.py"]
+exclude = ["src/strands/experimental/bidi/**/*.py", "tests/strands/experimental/bidi/**/*.py", "tests_integ/bidi/**/*.py"]
 
 [tool.ruff.lint]
 select = [
@@ -219,6 +236,7 @@ convention = "google"
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 asyncio_default_fixture_loop_scope = "function"
+addopts = "--ignore=tests/strands/experimental/bidi --ignore=tests_integ/bidi"
 
 
 [tool.coverage.run]
@@ -227,6 +245,7 @@ source = ["src"]
 context = "thread"
 parallel = true
 concurrency = ["thread", "multiprocessing"]
+omit = ["src/strands/experimental/bidi/*"]
 
 [tool.coverage.report]
 show_missing = true
@@ -256,3 +275,48 @@ style = [
     ["text", ""],
     ["disabled", "fg:#858585 italic"]
 ]
+
+# =========================
+# Bidi development configs
+# =========================
+
+[tool.hatch.envs.bidi]
+dev-mode = true
+features = ["dev", "bidi-all"]
+installer = "uv"
+
+[tool.hatch.envs.bidi.scripts]
+prepare = [
+    "hatch run bidi-lint:format-fix",
+    "hatch run bidi-lint:quality-fix",
+    "hatch run bidi-lint:type-check",
+    "hatch run bidi-test:test-cov",
+]
+
+[tools.hatch.envs.bidi-lint]
+template = "bidi"
+
+[tool.hatch.envs.bidi-lint.scripts]
+format-check = "format-fix --check"
+format-fix = "ruff format {args} --target-version py312 ./src/strands/experimental/bidi/**/*.py"
+quality-check = "ruff check {args} --target-version py312 ./src/strands/experimental/bidi/**/*.py"
+quality-fix = "quality-check --fix"
+type-check = "mypy {args} --python-version 3.12 ./src/strands/experimental/bidi/**/*.py"
+
+[tool.hatch.envs.bidi-test]
+template = "bidi"
+
+[tool.hatch.envs.bidi-test.scripts]
+test = "pytest {args} tests/strands/experimental/bidi"
+test-cov = """
+test \
+    --cov=strands.experimental.bidi \
+    --cov-config= \
+    --cov-branch \
+    --cov-report=term-missing \
+    --cov-report=xml:build/coverage/bidi-coverage.xml \
+    --cov-report=html:build/coverage/bidi-html
+"""
+
+[[tool.hatch.envs.bidi-test.matrix]]
+python = ["3.13", "3.12"]

src/strands/agent/state.py

@@ -1,97 +1,6 @@
 """Agent state management."""
 
-import copy
-import json
-from typing import Any, Dict, Optional
+from ..types.json_dict import JSONSerializableDict
 
-
-class AgentState:
-    """Represents an Agent's stateful information outside of context provided to a model.
-
-    Provides a key-value store for agent state with JSON serialization validation and persistence support.
-    Key features:
-    - JSON serialization validation on assignment
-    - Get/set/delete operations
-    """
-
-    def __init__(self, initial_state: Optional[Dict[str, Any]] = None):
-        """Initialize AgentState."""
-        self._state: Dict[str, Dict[str, Any]]
-        if initial_state:
-            self._validate_json_serializable(initial_state)
-            self._state = copy.deepcopy(initial_state)
-        else:
-            self._state = {}
-
-    def set(self, key: str, value: Any) -> None:
-        """Set a value in the state.
-
-        Args:
-            key: The key to store the value under
-            value: The value to store (must be JSON serializable)
-
-        Raises:
-            ValueError: If key is invalid, or if value is not JSON serializable
-        """
-        self._validate_key(key)
-        self._validate_json_serializable(value)
-
-        self._state[key] = copy.deepcopy(value)
-
-    def get(self, key: Optional[str] = None) -> Any:
-        """Get a value or entire state.
-
-        Args:
-            key: The key to retrieve (if None, returns entire state object)
-
-        Returns:
-            The stored value, entire state dict, or None if not found
-        """
-        if key is None:
-            return copy.deepcopy(self._state)
-        else:
-            # Return specific key
-            return copy.deepcopy(self._state.get(key))
-
-    def delete(self, key: str) -> None:
-        """Delete a specific key from the state.
-
-        Args:
-            key: The key to delete
-        """
-        self._validate_key(key)
-
-        self._state.pop(key, None)
-
-    def _validate_key(self, key: str) -> None:
-        """Validate that a key is valid.
-
-        Args:
-            key: The key to validate
-
-        Raises:
-            ValueError: If key is invalid
-        """
-        if key is None:
-            raise ValueError("Key cannot be None")
-        if not isinstance(key, str):
-            raise ValueError("Key must be a string")
-        if not key.strip():
-            raise ValueError("Key cannot be empty")
-
-    def _validate_json_serializable(self, value: Any) -> None:
-        """Validate that a value is JSON serializable.
-
-        Args:
-            value: The value to validate
-
-        Raises:
-            ValueError: If value is not JSON serializable
-        """
-        try:
-            json.dumps(value)
-        except (TypeError, ValueError) as e:
-            raise ValueError(
-                f"Value is not JSON serializable: {type(value).__name__}. "
-                f"Only JSON-compatible types (str, int, float, bool, list, dict, None) are allowed."
-            ) from e
+# Type alias for agent state
+AgentState = JSONSerializableDict

src/strands/experimental/__init__.py

@@ -3,7 +3,7 @@
 This module implements experimental features that are subject to change in future revisions without notice.
 """
 
-from . import tools
+from . import steering, tools
 from .agent_config import config_to_agent
 
-__all__ = ["config_to_agent", "tools"]
+__all__ = ["config_to_agent", "tools", "steering"]