How anthropics/anthropic-sdk-java works
1. This is a multi-module JVM SDK repository for Anthropic’s Claude API. The root anthropic-java project is an aggregator; anthropic-java-core is the main library, with smaller adapter modules for specific runtimes/providers (okhttp, bedrock, vertex, foundry, aws, mcp) plus an example app and ProGuard compatibility test.
2. The architectural center is anthropic-java-core. It defines the public client surface (AnthropicClient, AnthropicClientAsync) and service APIs for the main API families: completions, messages, models, and the beta surface. Almost all higher-level modules depend on this core layer rather than reimplementing business logic.
3. Core is organized in a standard SDK layering: client interfaces at the top, service implementations beneath, then a transport-agnostic HTTP layer, then serialization/model types. That separation lets the same service code work with different HTTP backends and different authentication strategies.
4. The HTTP subsystem in core provides request/response abstractions, query/header/body handling, retrying, logging, SSE/stream handling, and async stream wrappers. This is the main data path: request params are converted into HttpRequests, passed through wrappers like AuthorizingHttpClient and RetryingHttpClient, then decoded into typed response models or streaming event objects.
5. Authentication and credential resolution are first-class concerns in core. There are credential providers and cache layers for API keys, OAuth-style tokens, workload identity, and profile/config-file resolution. The config, credentials, and internal/config packages indicate the SDK can resolve secrets from environment, files, or cached credential stores before the request leaves the client.
6. The model layer is very large and strongly typed. com.anthropic.models.messages and com.anthropic.models.beta contain the request/response DTOs, tool definitions, streaming event types, paging wrappers, and error shapes. This suggests the repo is effectively a generated or schema-driven SDK with explicit types for every API object and many versioned beta features.
7. Streaming is a major capability, not an afterthought. There are dedicated handlers and event models for SSE/message streams, including raw message deltas, content-block events, and managed-agents/session event streams. Architecture-wise, this means some endpoints return long-lived stream responses rather than ordinary JSON payloads, and those streams are decoded incrementally.
8. Pagination is another shared cross-cutting concern. The Page, PageAsync, AutoPager, and AutoPagerAsync utilities encapsulate “list all results” behavior so services can expose typed page objects while still allowing consumers to iterate through complete datasets without manually handling cursors.
9. Error handling is normalized across the SDK. Core defines a hierarchy of Anthropic exceptions plus mapped service-specific errors for common HTTP statuses and API error payloads. This means service implementations do not surface raw HTTP errors directly; they translate protocol failures into domain-specific exception types.
10. anthropic-java-okhttp is the default concrete HTTP client module. It adapts core’s transport abstractions onto OkHttp and exposes convenience entry points like AnthropicOkHttpClient and async variants. From an architecture perspective, it is the “wire-up” layer that turns the transport-agnostic core SDK into a usable JVM client.
11. The provider-specific modules are thin backend adapters. anthropic-java-bedrock, anthropic-java-vertex, and anthropic-java-foundry each define a backend implementation that plugs provider-specific endpoints/authentication into the core client model. These modules let the same high-level message/client APIs target AWS Bedrock, Google Vertex, and Microsoft Foundry without changing the core service contracts.
12. anthropic-java-aws is a support module for AWS-specific authentication and backend integration. Its placement separate from bedrock indicates shared AWS auth utilities are reused by the Bedrock adapter rather than being embedded in the core SDK.
13. anthropic-java-mcp is an auxiliary integration layer for MCP resources/tools. It sits outside the main API client flow and appears to provide MCP-related helpers and resource file handling, which likely support tool or agent workflows rather than standard Claude API calls.
14. anthropic-java-example is a consumer-facing sample app that exercises the main surfaces: messages, streaming, structured outputs, tool use, token counting, beta managed agents, Bedrock/Vertex/Foundry connectivity, and credential providers. It is useful as an end-to-end map of the intended runtime data flows across modules.
15. Build and release infrastructure is Kotlin/Gradle-based and fairly mature. The repo uses a centralized buildSrc convention setup, multiple CI workflows, release automation, breaking-change detection, Sonatype publishing, formatting/lint scripts, and a ProGuard compatibility test module. For architecture diagrams, those pieces are the operational boundary around the library, not part of the runtime SDK path.
16. In one sentence: consumers enter through a concrete client module, call typed services in core, which marshal model objects through the HTTP/credential/retry stack to Anthropic or provider-specific backends, then decode JSON or stream events back into strongly typed Java/Kotlin objects.
Main entry points: anthropic-java-core Core library · anthropic-java anthropic-java · anthropic-java-example Examples · anthropic-java-bedrock Bedrock adapter
Components 18
Workspace
Aggregator and build boundary
- anthropic-java · Multi-module JVM SDK workspace
anthropic-java - BuildSrc · Shared Gradle/Kotlin convention plugins
buildSrc
Core SDK
Transport-agnostic client, services, HTTP, auth, and models
- Core library · Main client, service, transport, auth, and model layer
anthropic-java-core - Clients · Blocking and async entry points for consumers
anthropic-java-core/src/main/kotlin/com/anthropic/client - Services · Completions, messages, models, and beta service implementations
anthropic-java-core/src/main/kotlin/com/anthropic/services - HTTP stack · Request/response abstractions, retry, logging, streams, SSE, and wrappers
anthropic-java-core/src/main/kotlin/com/anthropic/core/http - Auth · Access tokens, identity providers, credential caching, and resolution
anthropic-java-core/src/main/kotlin/com/anthropic/core/auth - Config · Profile and file-based configuration resolution
anthropic-java-core/src/main/kotlin/com/anthropic/config - Models · Strongly typed request/response objects and error shapes
anthropic-java-core/src/main/kotlin/com/anthropic/models - Helpers · Streaming accumulators, tool runners, structured outputs, and webhook helpers
anthropic-java-core/src/main/kotlin/com/anthropic/helpers
Adapters
Runtime and provider-specific client backends
- OkHttp client · Default concrete HTTP client for JVM usage
anthropic-java-client-okhttp - Bedrock adapter · AWS Bedrock backend integration
anthropic-java-bedrock - Vertex adapter · Google Vertex backend integration
anthropic-java-vertex - Foundry adapter · Microsoft Foundry backend integration
anthropic-java-foundry - AWS support · AWS-specific auth and backend utilities shared by Bedrock
anthropic-java-aws
Auxiliary
Examples, MCP integration, and compatibility checks
- MCP module · MCP resource and tool helpers outside the main client flow
anthropic-java-mcp - Examples · Consumer-facing sample app covering major SDK flows
anthropic-java-example - ProGuard test · Compatibility check for shrinking/obfuscation
anthropic-java-proguard-test
Connections 29
- anthropic-java → Core library: builds · Root workspace aggregates core library
- anthropic-java → OkHttp client: builds · Root workspace aggregates runtime adapter
- anthropic-java → Bedrock adapter: builds · Root workspace aggregates provider adapter
- anthropic-java → Vertex adapter: builds · Root workspace aggregates provider adapter
- anthropic-java → Foundry adapter: builds · Root workspace aggregates provider adapter
- anthropic-java → AWS support: builds · Root workspace aggregates AWS support module
- anthropic-java → MCP module: builds · Root workspace aggregates MCP integration
- anthropic-java → Examples: builds · Root workspace aggregates sample app
- anthropic-java → ProGuard test: builds · Root workspace aggregates compatibility test
- anthropic-java → BuildSrc: uses · Workspace uses shared build conventions
- Core library → Clients: exposes · Public blocking and async client APIs
- Core library → Services: implements · Service layer defines API families and orchestration
- Core library → HTTP stack: depends on · Service layer uses transport abstractions
- Core library → Auth: depends on · Client requests use credential resolution
- Core library → Config: depends on · Profile and file config feed credential lookup
- Core library → Models: serializes · Services encode/decode typed DTOs and errors
- Core library → Helpers: uses · Higher-level SDK conveniences for streaming and tools
- OkHttp client → Core library: adapts · Concrete OkHttp wiring targets core transport APIs
- Bedrock adapter → Core library: adapts · Provider backend plugs into shared core services
- Vertex adapter → Core library: adapts · Provider backend plugs into shared core services
- Foundry adapter → Core library: adapts · Provider backend plugs into shared core services
- AWS support → Bedrock adapter: supports · AWS auth utilities are reused by Bedrock
- MCP module → Helpers: extends · MCP resource/tool helpers complement core tooling
- Examples → Core library: demonstrates · Sample app exercises the core SDK surfaces
- Examples → OkHttp client: uses · Examples show the default concrete client
- Examples → Bedrock adapter: uses · Examples cover Bedrock connectivity
- Examples → Vertex adapter: uses · Examples cover Vertex connectivity
- Examples → Foundry adapter: uses · Examples cover Foundry connectivity
- ProGuard test → Core library: verifies · Shrinking compatibility is checked against the core SDK