Principle:Anthropics Anthropic sdk python Client Initialization
| Knowledge Sources | |
|---|---|
| Domains | API_Client, LLM |
| Last Updated | 2026-02-15 00:00 GMT |
Overview
The Client Initialization principle defines how the Anthropic Python SDK establishes a configured gateway to the Anthropic API. The SDK follows a client-server architecture pattern in which a single client object encapsulates all connection-level concerns -- authentication credentials, base URL routing, timeout policies, retry strategies, and HTTP transport configuration -- so that downstream API calls are free from boilerplate.
Theoretical Basis
Client-Server Architecture with Sensible Defaults
The SDK adopts the principle of convention over configuration. Every parameter required to communicate with the Anthropic API ships with a production-ready default:
- Authentication defaults to reading the
ANTHROPIC_API_KEYenvironment variable. A secondaryANTHROPIC_AUTH_TOKENvariable supports bearer-token flows. - Base URL defaults to
https://api.anthropic.com, with anANTHROPIC_BASE_URLoverride for proxy or staging environments. - Timeout defaults to 10 minutes total with a 5-second connect timeout (
httpx.Timeout(timeout=600, connect=5.0)). - Retry policy defaults to 2 automatic retries with exponential back-off.
This design means that the simplest valid initialization is a zero-argument constructor -- Anthropic() -- provided the environment variable is set.
Environment Variable Fallback
The SDK reads credentials from the process environment at construction time, not at request time. This follows the fail-fast principle: if neither an explicit argument nor an environment variable is present, the client raises a TypeError at construction rather than allowing invalid requests to reach the network. The lookup chain is:
- Explicit keyword argument (
api_key="sk-ant-...") - Environment variable (
os.environ.get("ANTHROPIC_API_KEY")) - Raise an error if both are absent and no header override is provided
Lazy Construction of Resource Accessors
Once the client is constructed, API resource namespaces such as client.messages, client.completions, and client.models are exposed as cached properties. The @cached_property decorator ensures:
- The resource class is imported and instantiated only on first access, keeping startup cost minimal.
- Subsequent accesses return the same instance, so there is no overhead from repeated attribute lookups.
- Circular import issues are avoided because imports happen inside the property body rather than at module level.
This pattern is sometimes called lazy initialization or virtual proxy in design-pattern literature.
Sync and Async Duality
The SDK provides two parallel client classes -- Anthropic (synchronous, backed by httpx.Client) and AsyncAnthropic (asynchronous, backed by httpx.AsyncClient). Both classes share the same constructor signature and the same default values, differing only in their underlying transport and the coroutine-vs-function nature of their methods. This allows developers to choose the concurrency model that fits their application without learning a different API surface.
Client Copying and Option Overrides
The copy() method (aliased as with_options()) creates a new client instance that inherits all settings from the original but allows selective overrides. This supports patterns such as:
- Per-request timeout adjustments:
client.with_options(timeout=120).messages.create(...) - Temporary credential rotation without modifying the shared client
Design Constraints
- At least one of
api_keyorauth_tokenmust be resolvable, or the corresponding header must be explicitly omitted. Otherwise, header validation raises aTypeError. - The
http_clientparameter accepts a pre-configuredhttpx.Clientfor advanced use cases (custom TLS, proxies, connection pooling), but the SDK providesDefaultHttpxClientandDefaultAsyncHttpxClienthelpers to retain recommended defaults. - The
anthropic-versionheader is always set to2023-06-01and cannot be overridden throughdefault_headers-- it is injected by the client automatically.