Feature/bidirectional streaming (#180)

* feat: add WebSocket support with @app.websocket decorator (#41)

* feat: add WebSocket support with @app.websocket decorator

Add bidirectional streaming support for agent invocations:
- Add @app.websocket decorator for registering WebSocket handlers
- Register /ws endpoint in BedrockAgentCoreApp constructor
- Implement _handle_websocket method with proper error handling
- Follow existing decorator patterns (entrypoint, ping) for consistency
- Support WebSocketDisconnect for graceful connection handling
- Integrate with existing RequestContext for session management

test: add unit and integration tests for WebSocket support

Add comprehensive test coverage for WebSocket decorator:

Unit tests (10 tests):
- WebSocket route initialization and registration
- Decorator functionality and handler storage
- Basic send/receive communication
- Context integration with session IDs
- Exception handling and error cases
- Multiple message handling
- Graceful disconnect handling
- Custom request headers via context
- Streaming data functionality

Integration test:
- End-to-end WebSocket echo server
- Streaming multiple messages
- Session ID propagation through headers
- Real WebSocket client connection testing

All tests pass successfully.

* fix: remove exception details from WebSocket close reason

Don't send exception messages to clients when closing WebSocket connections
with code 1011. This prevents leaking internal error details to clients.

Changes:
- Remove reason parameter from websocket.close() calls
- Exception details are still logged server-side
- Tests continue to pass as they only check for disconnect exceptions

---------

Co-authored-by: Abishek Kumar <kumabish@amazon.com>

* feat: add AgentRuntimeClient for WebSocket authentication (#42)

* feat: add AgentRuntimeClient for WebSocket authentication

- Implemented AgentRuntimeClient with methods for generating WebSocket credentials
- Added generate_ws_connection() for backend services (returns URL + SigV4 headers)
- Added generate_presigned_url() for frontend clients (returns presigned URL)
- Support for endpoint qualifiers and custom query parameters (presigned URLs only)
- Comprehensive unit tests with 22 test cases covering all functionality
- Integration tests for validating credential format
- Complete documentation with usage examples

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: move websockets to dev dependencies for CI

The websockets package was in optional dependencies which caused
CI test failures. Moving it to dev dependencies ensures it's
installed during CI test runs.

* fix: skip integration tests when AWS credentials unavailable

Add skipif decorator to integration tests that require AWS credentials.
This prevents CI failures when credentials are not configured.

* refactor: use mocked credentials instead of skipping tests

Replace skipif decorators with pytest fixture that mocks boto3 credentials
using botocore.credentials.Credentials class. This ensures integration tests
run in all environments (local and CI) while still validating URL and header
generation logic.

Benefits:
- Tests always run, providing better coverage
- Uses real Credentials class for proper SigV4 signing
- No need for AWS credentials to be configured

* refactor: rename AgentRuntimeClient to AgentCoreRuntimeClient

- Rename class from AgentRuntimeClient to AgentCoreRuntimeClient
- Rename module from agent_runtime_client.py to agent_core_runtime_client.py
- Update all unit and integration tests to use new class name
- Update __init__.py exports
- Update documentation examples

This provides a more accurate name that reflects the AgentCore Runtime service.

---------

Co-authored-by: Abishek Kumar <kumabish@amazon.com>
Co-authored-by: Claude <noreply@anthropic.com>

* chore: exclude integration testing workflow changes

* fix: add websockets to integration test

---------

Co-authored-by: Abishek K <Abishek10@users.noreply.github.com>
Co-authored-by: Abishek Kumar <kumabish@amazon.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Sundar Raghavan <sdraghav@amazon.com>

Author: 5 people

.github/workflows/integration-testing.yml

@@ -130,7 +130,7 @@ jobs:
       - name: Install dependencies
         run: |
           pip install -e .
-          pip install --no-cache-dir pytest requests strands-agents uvicorn httpx starlette
+          pip install --no-cache-dir pytest requests strands-agents uvicorn httpx starlette websockets
 
       - name: Run integration tests
         env:

docs/examples/agent_runtime_client_examples.md

@@ -0,0 +1,206 @@
+# AgentCoreRuntimeClient Examples
+
+This document provides practical examples for using the `AgentCoreRuntimeClient` to authenticate WebSocket connections to AgentCore Runtime.
+
+## Basic Usage
+
+### Backend Service (SigV4 Headers)
+
+```python
+from bedrock_agentcore.runtime import AgentCoreRuntimeClient
+import websockets
+import asyncio
+
+async def main():
+    # Initialize client
+    client = AgentCoreRuntimeClient(region="us-west-2")
+
+    # Generate WebSocket connection with authentication
+    ws_url, headers = client.generate_ws_connection(
+        runtime_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-runtime"
+    )
+
+    # Connect using any WebSocket library
+    async with websockets.connect(ws_url, extra_headers=headers) as ws:
+        # Send message
+        await ws.send('{"inputText": "Hello!"}')
+
+        # Receive response
+        response = await ws.recv()
+        print(f"Received: {response}")
+
+asyncio.run(main())
+```
+
+### Frontend Client (Presigned URL)
+
+```python
+from bedrock_agentcore.runtime import AgentCoreRuntimeClient
+
+# Backend: Generate presigned URL
+client = AgentCoreRuntimeClient(region="us-west-2")
+
+presigned_url = client.generate_presigned_url(
+    runtime_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-runtime",
+    expires=300  # 5 minutes
+)
+
+# Share presigned_url with frontend
+# Frontend JavaScript: new WebSocket(presigned_url)
+```
+
+## Advanced Usage
+
+### With Endpoint Qualifier
+
+```python
+client = AgentCoreRuntimeClient(region="us-west-2")
+
+# For generate_ws_connection (header-based auth)
+ws_url, headers = client.generate_ws_connection(
+    runtime_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-runtime",
+    endpoint_name="DEFAULT"
+)
+# URL will include: ?qualifier=DEFAULT
+
+# For generate_presigned_url (query-based auth)
+presigned_url = client.generate_presigned_url(
+    runtime_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-runtime",
+    endpoint_name="DEFAULT"
+)
+# URL will include: ?qualifier=DEFAULT&X-Amz-Algorithm=...
+```
+
+### With Custom Query Parameters (Presigned URL only)
+
+```python
+client = AgentCoreRuntimeClient(region="us-west-2")
+
+# custom_headers parameter is only available for presigned URLs
+presigned_url = client.generate_presigned_url(
+    runtime_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-runtime",
+    custom_headers={"custom_param": "value", "another": "param"}
+)
+
+# URL will include: ?custom_param=value&another=param&X-Amz-Algorithm=...
+```
+
+### With Explicit Session ID
+
+```python
+client = AgentCoreRuntimeClient(region="us-west-2")
+
+ws_url, headers = client.generate_ws_connection(
+    runtime_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-runtime",
+    session_id="my-custom-session-id"
+)
+```
+
+## Error Handling
+
+```python
+from bedrock_agentcore.runtime import AgentCoreRuntimeClient
+
+client = AgentCoreRuntimeClient(region="us-west-2")
+
+try:
+    ws_url, headers = client.generate_ws_connection(
+        runtime_arn="invalid-arn"
+    )
+except ValueError as e:
+    print(f"Invalid ARN format: {e}")
+except RuntimeError as e:
+    print(f"AWS credentials error: {e}")
+```
+
+## Custom Boto3 Session
+
+You can provide your own boto3 session for custom credential handling:
+
+```python
+import boto3
+from bedrock_agentcore.runtime import AgentCoreRuntimeClient
+
+# Create a custom session with specific profile
+session = boto3.Session(profile_name="my-profile")
+
+# Or with specific credentials
+session = boto3.Session(
+    aws_access_key_id="YOUR_ACCESS_KEY",
+    aws_secret_access_key="YOUR_SECRET_KEY",
+    aws_session_token="YOUR_SESSION_TOKEN"
+)
+
+# Initialize client with custom session
+client = AgentCoreRuntimeClient(region="us-west-2", session=session)
+
+# Use the client normally
+ws_url, headers = client.generate_ws_connection(runtime_arn)
+```
+
+## OAuth Authentication
+
+For scenarios using OAuth bearer tokens instead of AWS credentials:
+
+```python
+from bedrock_agentcore.runtime import AgentCoreRuntimeClient
+import websockets
+import asyncio
+
+async def main():
+    # Initialize client
+    client = AgentCoreRuntimeClient(region="us-west-2")
+
+    # Your OAuth bearer token (e.g., from JWT authentication)
+    bearer_token = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
+
+    # Generate WebSocket connection with OAuth
+    ws_url, headers = client.generate_ws_connection_oauth(
+        runtime_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-runtime",
+        bearer_token=bearer_token,
+        endpoint_name="DEFAULT"  # Optional
+    )
+
+    # Connect using OAuth authentication
+    async with websockets.connect(ws_url, extra_headers=headers) as ws:
+        await ws.send('{"inputText": "Hello!"}')
+        response = await ws.recv()
+        print(f"Received: {response}")
+
+asyncio.run(main())
+```
+
+### OAuth with Custom Session ID
+
+```python
+client = AgentCoreRuntimeClient(region="us-west-2")
+
+ws_url, headers = client.generate_ws_connection_oauth(
+    runtime_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-runtime",
+    bearer_token="your-oauth-token",
+    session_id="custom-oauth-session-id"
+)
+```
+
+## Using Different WebSocket Libraries
+
+### With websockets library
+
+```python
+import websockets
+
+ws_url, headers = client.generate_ws_connection(runtime_arn)
+async with websockets.connect(ws_url, extra_headers=headers) as ws:
+    await ws.send(message)
+```
+
+### With aiohttp library
+
+```python
+import aiohttp
+
+ws_url, headers = client.generate_ws_connection(runtime_arn)
+async with aiohttp.ClientSession() as session:
+    async with session.ws_connect(ws_url, headers=headers) as ws:
+        await ws.send_str(message)
+```

pyproject.toml

@@ -33,6 +33,7 @@ dependencies = [
     "starlette>=0.46.2",
     "typing-extensions>=4.13.2,<5.0.0",
     "uvicorn>=0.34.2",
+    "pre-commit>=4.2.0",
 ]
 
 [project.scripts]
@@ -143,6 +144,7 @@ dev = [
     "pytest-asyncio>=0.24.0",
     "pytest-cov>=6.0.0",
     "ruff>=0.12.0",
+    "websockets>=14.1",
     "wheel>=0.45.1",
     "strands-agents>=1.18.0",
 ]

src/bedrock_agentcore/runtime/__init__.py

@@ -6,8 +6,15 @@
 - BedrockAgentCoreContext: Agent identity context
 """
 
+from .agent_core_runtime_client import AgentCoreRuntimeClient
 from .app import BedrockAgentCoreApp
 from .context import BedrockAgentCoreContext, RequestContext
 from .models import PingStatus
 
-__all__ = ["BedrockAgentCoreApp", "RequestContext", "BedrockAgentCoreContext", "PingStatus"]
+__all__ = [
+    "AgentCoreRuntimeClient",
+    "BedrockAgentCoreApp",
+    "RequestContext",
+    "BedrockAgentCoreContext",
+    "PingStatus",
+]