feat: add Bedrock Runtime endpoint support (SDK-290) (#3623)

## Summary

Add first-class Amazon Bedrock Runtime support to the Python SDK while
preserving the existing Mantle endpoint and legacy clients.

- Add `bedrock(endpoint="runtime" | "mantle")`; Mantle remains the
default.
- Select Runtime hostnames and SigV4 signing atomically:
`bedrock-runtime.<region>.<partition>/openai/v1` signs with `bedrock`;
Mantle continues to sign with `bedrock-mantle`.
- Infer canonical endpoint families from explicit/environment base URLs
and recognize FIPS, dual-stack, trailing-dot, China, European sovereign,
ISO, ISOB, ISOE, and ISOF endpoints.
- Reject invalid/injected regions, canonical HTTP, family/region
mismatches, cross-origin requests, and ambiguous custom-host SigV4
configuration.
- Preserve bearer keys, environment bearer precedence, refreshable
sync/async token providers, named AWS profiles, default chains,
static/session credentials, retry re-signing, and legacy custom-host
compatibility.
- Document Runtime installation, API versions/routes, Chat Completions,
streaming, async use, bearer/SigV4 authentication, profiles, inference
profiles, and deployment limitations in `bedrock.md` and
`examples/bedrock_runtime.py`.
- Extend the explicitly opt-in live harness across
`us.openai.gpt-5.6-{sol,terra,luna}`,
bearer/provider/profile/static/default-chain authentication, streaming,
and Runtime Responses.
- Extend packaged-wheel CI smoke coverage to verify both endpoint
families, both auth modes, correct signing services, and botocore-free
bearer authentication.

### Example

```python
from openai import OpenAI
from openai.providers import bedrock

client = OpenAI(
    provider=bedrock(endpoint="runtime", region="us-west-2", api_key=None)
)

completion = client.chat.completions.create(
    model="us.openai.gpt-5.6-sol",
    messages=[{"role": "user", "content": "Say hello!"}],
    stream=True,
)
for chunk in completion:
    print(chunk.choices[0].delta.content or "", end="")
```

## Verification

- `pytest -q -n 0 tests/lib/test_bedrock_runtime.py
tests/lib/test_bedrock_provider.py
tests/lib/test_bedrock_auth_conformance.py
tests/lib/test_bedrock_credential_chain.py tests/lib/test_bedrock.py` —
**197 passed**, including **56 new Runtime cases**.
- `pytest -q -n auto tests/lib tests/test_httpx2.py` — **330 passed**.
- `ruff check .` and Ruff format checks for every changed file — passed.
- Strict Pyright across all changed Python files — **0 errors**.
- mypy across changed production, example, and wheel-validator files —
passed.
- `uv build --python .venv/bin/python` — wheel and source distribution
built successfully.
- `python scripts/utils/validate-bedrock-wheel.py` — packaged
Mantle/Runtime bearer/SigV4 smoke checks passed.
- `python scripts/utils/validate-python-version-wheel.py` — wheel/source
Python metadata validated.

Live AWS requests were not executed because AWS credentials are
unavailable in this workspace; the guarded harness is ready for an
authorized Bedrock account.

## References

- [SDK-290: Add Bedrock Runtime support across OpenAI
SDKs](https://linear.app/openai/issue/SDK-290/add-bedrock-runtime-support-across-openai-sdks)
- [Reference Node implementation:
openai/openai-node#2348](openai/openai-node#2348)

Author: HAYDEN-OAI

README.md

@@ -1073,7 +1073,7 @@ client = OpenAI(
 
 You can also pass `access_key_id` and `secret_access_key`, with an optional `session_token`, or a refreshable `credential_provider` that returns botocore-compatible credentials. Explicit bearer and AWS credential options are mutually exclusive.
 
-Pass `base_url` to `bedrock(...)` or set `AWS_BEDROCK_BASE_URL` to override the derived `https://bedrock-mantle.<region>.api.aws/openai/v1` endpoint.
+Pass `base_url` to `bedrock(...)` or set `AWS_BEDROCK_BASE_URL` to override the derived `https://bedrock-mantle.<region>.api.aws/openai/v1` endpoint. Custom URLs retain Mantle signing by default; pass `endpoint="runtime"` to use Runtime signing.
 
 SigV4 requests require replayable, fully serialized request bodies. Standard JSON requests already meet this requirement, and response streaming is unaffected. Low-level one-shot request streams must be buffered before sending, or sent with bearer authentication and retries disabled.
 

bedrock.md

@@ -0,0 +1,189 @@
+# Amazon Bedrock
+
+The Bedrock provider connects the standard synchronous and asynchronous OpenAI clients to Amazon Bedrock's
+OpenAI-compatible endpoints. The provider supports bearer tokens without additional dependencies. AWS Signature
+Version 4 (SigV4) requires the optional Bedrock dependencies:
+
+```sh
+pip install 'openai[bedrock]'
+```
+
+Runtime endpoint selection requires a Python SDK release that includes SDK-290. The SDK supports Python 3.10 and newer.
+
+## Endpoint selection
+
+| `endpoint` | Default API root | SigV4 signing service |
+| --- | --- | --- |
+| `"mantle"` (default) | `https://bedrock-mantle.<region>.api.aws/openai/v1` | `bedrock-mantle` |
+| `"runtime"` | `https://bedrock-runtime.<region>.amazonaws.com/openai/v1` | `bedrock` |
+
+Runtime hostnames use the DNS suffix for the selected AWS partition. For example, the European sovereign region
+`eusc-de-east-1` uses `amazonaws.eu`. Canonical Runtime FIPS and dual-stack hostnames are also recognized.
+
+The region comes from `region`, `AWS_REGION`, `AWS_DEFAULT_REGION`, or, for AWS authentication, the selected AWS profile.
+Pass `base_url` or set `AWS_BEDROCK_BASE_URL` to override the derived API root. When `endpoint` is omitted, canonical
+Mantle and Runtime URLs select the corresponding endpoint and signing service automatically; otherwise Mantle remains
+the default. Custom or proxy URLs likewise use Mantle signing by default; pass `endpoint="runtime"` when a custom host
+requires Runtime signing.
+
+## Runtime Chat Completions
+
+Use an inference-profile ID such as `us.openai.gpt-5.6-sol`, `us.openai.gpt-5.6-terra`, or
+`us.openai.gpt-5.6-luna`. These deployments do not accept the corresponding bare model ID. Global inference profiles,
+such as `global.openai.gpt-5.6-sol`, require an AWS account and permissions that allow the corresponding profile.
+
+```python
+from openai import OpenAI
+from openai.providers import bedrock
+
+client = OpenAI(
+    provider=bedrock(
+        endpoint="runtime",
+        region="us-west-2",
+        api_key=None,
+    )
+)
+
+completion = client.chat.completions.create(
+    model="us.openai.gpt-5.6-sol",
+    messages=[{"role": "user", "content": "Say hello!"}],
+)
+print(completion.choices[0].message.content)
+```
+
+`api_key=None` prevents `AWS_BEARER_TOKEN_BEDROCK` from shadowing AWS credentials and forces SigV4 authentication. Omit
+`region` to use the normal environment or AWS profile region chain.
+
+For streaming, set `stream=True`:
+
+```python
+stream = client.chat.completions.create(
+    model="us.openai.gpt-5.6-sol",
+    messages=[{"role": "user", "content": "Say hello!"}],
+    stream=True,
+)
+for chunk in stream:
+    print(chunk.choices[0].delta.content or "", end="", flush=True)
+```
+
+The asynchronous client uses the same provider configuration:
+
+```python
+from openai import AsyncOpenAI
+
+client = AsyncOpenAI(provider=bedrock(endpoint="runtime", region="us-west-2", api_key=None))
+completion = await client.chat.completions.create(
+    model="us.openai.gpt-5.6-sol",
+    messages=[{"role": "user", "content": "Say hello!"}],
+)
+```
+
+See [`examples/bedrock_runtime.py`](examples/bedrock_runtime.py) for a runnable example supporting SigV4, bearer
+authentication, model selection, AWS profiles, and opt-in streaming.
+
+## Authentication
+
+Authentication is chosen in this order:
+
+1. Explicit bearer credentials, static AWS credentials, a named profile, or an AWS credential provider.
+2. The bearer token in `AWS_BEARER_TOKEN_BEDROCK`, unless `api_key=None` disables this fallback.
+3. The default AWS credential chain.
+
+Explicit bearer and AWS credential modes cannot be combined. A stale environment bearer token takes precedence over the
+implicit AWS credential chain; unset it or pass `api_key=None` when SigV4 is required.
+
+### Bearer credentials
+
+```python
+client = OpenAI(
+    provider=bedrock(
+        endpoint="runtime",
+        region="us-west-2",
+        api_key="your-bedrock-api-key",
+    )
+)
+```
+
+A callable token provider is invoked before every request attempt, including retries. `AsyncOpenAI` also accepts an
+asynchronous callable:
+
+```python
+client = AsyncOpenAI(
+    provider=bedrock(
+        endpoint="runtime",
+        region="us-west-2",
+        token_provider=refresh_bedrock_token,
+    )
+)
+```
+
+### AWS credentials and profiles
+
+Use the default AWS credential chain or select a named shared-config profile:
+
+```python
+client = OpenAI(
+    provider=bedrock(
+        endpoint="runtime",
+        profile="my-aws-profile",
+        api_key=None,
+    )
+)
+```
+
+Temporary static credentials can include a session token:
+
+```python
+client = OpenAI(
+    provider=bedrock(
+        endpoint="runtime",
+        region="us-west-2",
+        access_key_id="your-access-key",
+        secret_access_key="your-secret-key",
+        session_token="your-session-token",
+    )
+)
+```
+
+Pass `credential_provider` for refreshing AWS credentials. The provider is called for every signed request attempt.
+Signed requests require replayable request bodies and do not automatically follow redirects.
+
+## API routes and support limitations
+
+The SDK defaults to `/openai/v1`, matching
+[AWS's OpenAI model documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-openai.html).
+[AWS's Chat Completions documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-chat-completions-mantle.html)
+also describes a `/v1` Runtime route. Override `base_url` when a deployment requires that route:
+
+```python
+client = OpenAI(
+    provider=bedrock(
+        endpoint="runtime",
+        region="us-west-2",
+        base_url="https://bedrock-runtime.us-west-2.amazonaws.com/v1",
+        api_key=None,
+    )
+)
+```
+
+The provider exposes normal Chat Completions and Responses resources, but AWS determines which routes, models,
+inference profiles, authentication methods, and streaming features each deployment accepts. Runtime Responses and
+streaming should be live-validated for the selected model, profile, route, authentication mode, and AWS account.
+
+Canonical AWS endpoints must use HTTPS and match the configured endpoint family and region. Bedrock credentials are
+never attached to a request whose origin differs from the configured API root. Explicitly configured custom or local
+HTTP proxies remain available when required; use them only inside a trusted environment.
+
+## Opt-in live verification
+
+The existing live harness requires explicit opt-in and valid AWS credentials:
+
+```sh
+BEDROCK_LIVE_TEST=1 BEDROCK_LIVE_ENDPOINT=runtime AWS_REGION=us-west-2 \
+  rye run pytest -q -s tests/lib/bedrock_live.py
+```
+
+Runtime verification defaults to all three US GPT-5.6 inference profiles. Select authentication modes with
+`BEDROCK_LIVE_AUTHS=bearer,environment-bearer,token-provider,default-chain,profile,static`; select specific models with
+`BEDROCK_LIVE_MODELS`. Set `BEDROCK_LIVE_STREAM=1` to include streaming and `BEDROCK_LIVE_RESPONSES=1` to include
+Runtime Responses. Provide `AWS_PROFILE` or `BEDROCK_LIVE_PROFILE` for named-profile verification.

examples/bedrock_runtime.py

@@ -0,0 +1,41 @@
+"""Run Amazon Bedrock Runtime Chat Completions with bearer or AWS authentication.
+
+AWS_REGION=us-west-2 python examples/bedrock_runtime.py
+AWS_REGION=us-west-2 BEDROCK_MODEL=us.openai.gpt-5.6-terra BEDROCK_STREAM=1 python examples/bedrock_runtime.py
+AWS_REGION=us-west-2 BEDROCK_AUTH=bearer python examples/bedrock_runtime.py
+"""
+
+from __future__ import annotations
+
+import os
+
+from openai import OpenAI
+from openai.providers import bedrock
+from openai.types.chat import ChatCompletionMessageParam
+
+authentication = os.environ.get("BEDROCK_AUTH", "sigv4")
+region = os.environ.get("AWS_REGION") or os.environ.get("AWS_DEFAULT_REGION")
+profile = os.environ.get("AWS_PROFILE") or None
+
+if authentication == "bearer":
+    token = os.environ.get("AWS_BEARER_TOKEN_BEDROCK")
+    if not token:
+        raise RuntimeError("Bearer authentication requires AWS_BEARER_TOKEN_BEDROCK.")
+    provider = bedrock(endpoint="runtime", region=region, api_key=token)
+elif authentication == "sigv4":
+    provider = bedrock(endpoint="runtime", region=region, profile=profile, api_key=None)
+else:
+    raise RuntimeError("BEDROCK_AUTH must be either 'sigv4' or 'bearer'.")
+
+client = OpenAI(provider=provider)
+model = os.environ.get("BEDROCK_MODEL", "us.openai.gpt-5.6-sol")
+messages: list[ChatCompletionMessageParam] = [{"role": "user", "content": "Say hello from Amazon Bedrock Runtime!"}]
+
+if os.environ.get("BEDROCK_STREAM") == "1":
+    stream = client.chat.completions.create(model=model, messages=messages, stream=True)
+    for chunk in stream:
+        print(chunk.choices[0].delta.content or "", end="", flush=True)
+    print()
+else:
+    completion = client.chat.completions.create(model=model, messages=messages)
+    print(completion.choices[0].message.content)

scripts/utils/validate-bedrock-wheel.py

@@ -42,32 +42,41 @@ def handler(request):
     return httpx2.Response(200, request=request, json={})
 
 
-http_client = httpx2.Client(transport=httpx2.MockTransport(handler), trust_env=False)
-with OpenAI(
-    provider=bedrock(region="us-east-1", api_key="bearer-token"),
-    http_client=http_client,
-) as client:
-    client.get("/models", cast_to=httpx2.Response)
-
-assert requests[0].headers["Authorization"] == "Bearer bearer-token"
-assert not any(name == "botocore" or name.startswith("botocore.") for name in sys.modules)
+for endpoint, hostname in (
+    ("mantle", "bedrock-mantle.us-east-1.api.aws"),
+    ("runtime", "bedrock-runtime.us-east-1.amazonaws.com"),
+):
+    requests.clear()
+    http_client = httpx2.Client(transport=httpx2.MockTransport(handler), trust_env=False)
+    with OpenAI(
+        provider=bedrock(endpoint=endpoint, region="us-east-1", api_key="bearer-token"),
+        http_client=http_client,
+    ) as client:
+        client.get("/models", cast_to=httpx2.Response)
+
+    assert requests[0].url.host == hostname
+    assert requests[0].headers["Authorization"] == "Bearer bearer-token"
+    assert not any(name == "botocore" or name.startswith("botocore.") for name in sys.modules)
 
 sys.meta_path.remove(blocker)
-requests.clear()
-http_client = httpx2.Client(transport=httpx2.MockTransport(handler), trust_env=False)
-with OpenAI(
-    provider=bedrock(
-        region="us-east-1",
-        access_key_id="fixture-access-key",
-        secret_access_key="fixture-secret-key",
-        session_token="fixture-session-token",
-    ),
-    http_client=http_client,
-) as client:
-    client.get("/models", cast_to=httpx2.Response)
-
-assert "Credential=fixture-access-key/" in requests[0].headers["Authorization"]
-assert requests[0].headers["X-Amz-Security-Token"] == "fixture-session-token"
+for endpoint, signing_service in (("mantle", "bedrock-mantle"), ("runtime", "bedrock")):
+    requests.clear()
+    http_client = httpx2.Client(transport=httpx2.MockTransport(handler), trust_env=False)
+    with OpenAI(
+        provider=bedrock(
+            endpoint=endpoint,
+            region="us-east-1",
+            access_key_id="fixture-access-key",
+            secret_access_key="fixture-secret-key",
+            session_token="fixture-session-token",
+        ),
+        http_client=http_client,
+    ) as client:
+        client.get("/models", cast_to=httpx2.Response)
+
+    assert "Credential=fixture-access-key/" in requests[0].headers["Authorization"]
+    assert f"/{signing_service}/aws4_request" in requests[0].headers["Authorization"]
+    assert requests[0].headers["X-Amz-Security-Token"] == "fixture-session-token"
 """
 
 

src/openai/lib/_bedrock_auth.py

@@ -37,13 +37,14 @@ def _load_botocore() -> tuple[Any, Any, Any, Any]:
             "Install them with `pip install openai[bedrock]` and try again."
         ) from exc
 
-    return SigV4Auth, AWSRequest, Credentials, Session
+    return cast("tuple[Any, Any, Any, Any]", (SigV4Auth, AWSRequest, Credentials, Session))
 
 
 @dataclass(frozen=True)
 class BedrockAwsAuthConfig:
     region: str
     source: Literal["static", "profile", "provider", "default"]
+    service: Literal["bedrock-mantle", "bedrock"] = "bedrock-mantle"
     region_source: Literal["explicit", "environment", "profile"] = "explicit"
     profile: str | None = None
     access_key_id: str | None = field(default=None, repr=False)
@@ -87,6 +88,7 @@ def resolve(
         secret_access_key: str | None,
         session_token: str | None,
         credentials_provider: AwsCredentialsProvider | None,
+        service: Literal["bedrock-mantle", "bedrock"] = "bedrock-mantle",
     ) -> BedrockAwsAuth:
         _, _, _, session_cls = _load_botocore()
 
@@ -114,6 +116,7 @@ def resolve(
         config = BedrockAwsAuthConfig(
             region=resolved_region,
             source=source,
+            service=service,
             region_source=region_source,
             profile=profile,
             access_key_id=access_key_id,
@@ -151,7 +154,7 @@ def sign(self, *, method: str, url: str, headers: Mapping[str, str], body: bytes
                 data=body,
                 headers=signed_headers,
             )
-            self._sigv4_auth_cls(credentials, "bedrock-mantle", self.config.region).add_auth(aws_request)
+            self._sigv4_auth_cls(credentials, self.config.service, self.config.region).add_auth(aws_request)
         except OpenAIError:
             raise
         except Exception as exc: