Use Cloud SDK Extras

What the Cloud Clients Add

The cloud clients share the Messages API with the direct client, and most application code runs on any of them unchanged. Each one also adds things that are specific to its platform: a way to pick where a model is served, a way to supply the platform's identity, a way to route traffic through the platform's network, and sometimes an option that exists only on that cloud. These additions are the extras. They are useful, but each one ties the code to a platform, so they should be used deliberately and kept in the adapter layer from Lesson 166.

This lesson covers the most common extras, shows how a geographic choice maps onto a Bedrock model identifier, explains how to supply a custom network client, and gives guidance on keeping the platform-specific parts contained so that the rest of the application stays portable.

Routing Within a Platform

Several platforms let a request be served from more than one place, and the choice of place is an extra setting. On Vertex AI, the region setting selects the global endpoint, a multi-region group, or a single region (Lesson 162). On Bedrock, a model can be reached through a cross-region inference profile, identified by a geographic prefix in the model name. The prefix lets Bedrock route the request among the regions in that geography, which improves availability and capacity.

The prefix must match the geography, and not every model is available with every prefix. The mapping below expresses the common rule for choosing it from the region, and it is a starting point to be confirmed against the model's availability in the platform's documentation:

"""cloud_extras.py: pick the geographic inference prefix for a Bedrock model from its region."""

PREFIX_BY_REGION_GROUP = {"us-": "us", "eu-": "eu", "ap-": "apac"}


def bedrock_model_id(base_model: str, region: str) -> str:
    for start, prefix in PREFIX_BY_REGION_GROUP.items():
        if region.startswith(start):
            return f"{prefix}.{base_model}"
    raise ValueError(f"no inference prefix is known for region {region}")


if __name__ == "__main__":
    base = "anthropic.claude-sonnet-4-5-20250929-v1:0"
    for region in ["us-east-1", "eu-west-1", "ap-south-1", "sa-east-1"]:
        try:
            print(f"{region}: {bedrock_model_id(base, region)}")
        except ValueError as error:
            print(f"{region}: error: {error}")

Output:

us-east-1: us.anthropic.claude-sonnet-4-5-20250929-v1:0
eu-west-1: eu.anthropic.claude-sonnet-4-5-20250929-v1:0
ap-south-1: apac.anthropic.claude-sonnet-4-5-20250929-v1:0
sa-east-1: error: no inference prefix is known for region sa-east-1

How It Works

1. The region decides the geography. Regions beginning with us-, eu-, and ap- map to the US, EU, and Asia-Pacific prefixes, and the function attaches the matching prefix to the base model identifier.
2. The base identifier is unchanged. The prefix is added in front of it, so the model's version suffix is preserved exactly.
3. An unknown region raises an error rather than guessing. A guessed prefix could route data to a geography the organization did not choose, which is a compliance problem, not only a technical one.
4. The table is a rule to be confirmed. Whether a particular model is available under a given prefix is a property of the platform, and the code cannot know it. The function only encodes the naming rule.

Supplying Identity

Each cloud client accepts the platform's identity in its own way, and the default chain (Lesson 164) is correct for most deployments. The extras appear when the default is not enough: a named profile for a machine with several accounts, a specific role to assume for one service, or a credential object created by the platform's library and passed to the client. The principle is that the identity is passed as an object created by the platform's tools, never as a string copied from a file into code.

Custom Network Clients

The SDK builds on a standard HTTP library, and it accepts a custom client for the network layer. A custom client is the way to set a proxy, add certificates for an internal network, or change connection pooling. It is the advanced form of the timeout settings from Lesson 144, and it affects every request the client makes. The configuration belongs in the factory from Lesson 167, so that every client in the application receives the same network behavior.

A custom network client is a powerful setting, and a mistake in it affects all traffic. Proxy and certificate settings should be tested against the actual network path, and changes should be rolled out the same way as code changes.

Keeping the Extras Contained

Every extra ties the code to a platform. The discipline that keeps an application portable is to confine extras to the factory and the adapter layer, and to keep the rest of the code platform-neutral. A function that takes a client and a model name works everywhere. A function that builds a Bedrock-specific identifier belongs in the adapter, where it is the only place that knows about the platform.

The test for whether an extra belongs in the core is simple: if removing it would require changes to business logic, the extra has leaked. Keeping the boundary clean costs little at the start and saves a great deal when a platform changes.

Summary

The cloud clients add platform-specific extras: routing options such as cross-region inference profiles, identity options beyond the default chain, and custom network clients for proxies and certificates. The geographic prefix for a Bedrock model follows from its region, and an unknown region should raise an error rather than guess, since the choice has compliance consequences. Extras belong in the factory and adapter layer, where they can be tested and where they keep the rest of the application portable. The final lesson of the section covers deploying an application that uses these clients.