# anthropics/anthropic-sdk-java architecture

> Architecture diagram of the GitHub repository anthropics/anthropic-sdk-java, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anthropics/anthropic-sdk-java
- Repository: https://github.com/anthropics/anthropic-sdk-java

## Overview

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 `HttpRequest`s, 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`](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-core) (Core library), [`anthropic-java`](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java) (anthropic-java), [`anthropic-java-example`](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-example) (Examples), [`anthropic-java-bedrock`](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-bedrock) (Bedrock adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Workspace"]
  node_repo["anthropic-java<br/>aggregator"]
  node_buildsrc["BuildSrc<br/>build-conventions"]
end

subgraph group_core["Core SDK"]
  node_corelib["Core library<br/>sdk-core"]
  node_client["Clients<br/>public-api"]
  node_services["Services"]
  node_http["HTTP stack<br/>transport"]
  node_auth["Auth<br/>credentials"]
  node_config["Config"]
  node_models["Models<br/>dto-schemas"]
  node_helpers["Helpers"]
end

subgraph group_adapters["Adapters"]
  node_okhttpmod["OkHttp client<br/>runtime-adapter"]
  node_bedrockmod["Bedrock adapter<br/>provider-adapter"]
  node_vertexmod["Vertex adapter<br/>provider-adapter"]
  node_foundrymod["Foundry adapter<br/>provider-adapter"]
  node_awssupp["AWS support<br/>aws-auth"]
end

subgraph group_aux["Auxiliary"]
  node_mcplib["MCP module<br/>integration"]
  node_example["Examples<br/>sample-app"]
  node_proguard["ProGuard test<br/>compatibility"]
end

node_repo -->|"builds"| node_corelib
node_repo -->|"builds"| node_okhttpmod
node_repo -->|"builds"| node_bedrockmod
node_repo -->|"builds"| node_vertexmod
node_repo -->|"builds"| node_foundrymod
node_repo -->|"builds"| node_awssupp
node_repo -->|"builds"| node_mcplib
node_repo -->|"builds"| node_example
node_repo -->|"builds"| node_proguard
node_repo -->|"uses"| node_buildsrc
node_corelib -->|"exposes"| node_client
node_corelib -->|"implements"| node_services
node_corelib -->|"depends on"| node_http
node_corelib -->|"depends on"| node_auth
node_corelib -->|"depends on"| node_config
node_corelib -->|"serializes"| node_models
node_corelib -->|"uses"| node_helpers
node_okhttpmod -->|"adapts"| node_corelib
node_bedrockmod -->|"adapts"| node_corelib
node_vertexmod -->|"adapts"| node_corelib
node_foundrymod -->|"adapts"| node_corelib
node_awssupp -->|"supports"| node_bedrockmod
node_mcplib -->|"extends"| node_helpers
node_example -->|"demonstrates"| node_corelib
node_example -->|"uses"| node_okhttpmod
node_example -->|"uses"| node_bedrockmod
node_example -->|"uses"| node_vertexmod
node_example -->|"uses"| node_foundrymod
node_proguard -->|"verifies"| node_corelib

click node_repo "https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java"
click node_corelib "https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-core"
click node_client "https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-core/src/main/kotlin/com/anthropic/client"
click node_services "https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-core/src/main/kotlin/com/anthropic/services"
click node_http "https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-core/src/main/kotlin/com/anthropic/core/http"
click node_auth "https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-core/src/main/kotlin/com/anthropic/core/auth"
click node_config "https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-core/src/main/kotlin/com/anthropic/config"
click node_models "https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-core/src/main/kotlin/com/anthropic/models"
click node_helpers "https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-core/src/main/kotlin/com/anthropic/helpers"
click node_okhttpmod "https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-client-okhttp"
click node_bedrockmod "https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-bedrock"
click node_vertexmod "https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-vertex"
click node_foundrymod "https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-foundry"
click node_awssupp "https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-aws"
click node_mcplib "https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-mcp"
click node_example "https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-example"
click node_proguard "https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-proguard-test"
click node_buildsrc "https://github.com/anthropics/anthropic-sdk-java/tree/main/buildSrc"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_repo,node_buildsrc toneBlue
class node_corelib,node_client,node_services,node_http,node_auth,node_config,node_models,node_helpers toneAmber
class node_okhttpmod,node_bedrockmod,node_vertexmod,node_foundrymod,node_awssupp toneMint
class node_mcplib,node_example,node_proguard toneRose
```

## Components

### Workspace

Aggregator and build boundary

- [anthropic-java](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java): aggregator · Multi-module JVM SDK workspace · `anthropic-java`
- [BuildSrc](https://github.com/anthropics/anthropic-sdk-java/tree/main/buildSrc): build-conventions · Shared Gradle/Kotlin convention plugins · `buildSrc`

### Core SDK

Transport-agnostic client, services, HTTP, auth, and models

- [Core library](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-core): sdk-core · Main client, service, transport, auth, and model layer · `anthropic-java-core`
- [Clients](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-core/src/main/kotlin/com/anthropic/client): public-api · Blocking and async entry points for consumers · `anthropic-java-core/src/main/kotlin/com/anthropic/client`
- [Services](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-core/src/main/kotlin/com/anthropic/services): api-services · Completions, messages, models, and beta service implementations · `anthropic-java-core/src/main/kotlin/com/anthropic/services`
- [HTTP stack](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-core/src/main/kotlin/com/anthropic/core/http): transport · Request/response abstractions, retry, logging, streams, SSE, and wrappers · `anthropic-java-core/src/main/kotlin/com/anthropic/core/http`
- [Auth](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-core/src/main/kotlin/com/anthropic/core/auth): credentials · Access tokens, identity providers, credential caching, and resolution · `anthropic-java-core/src/main/kotlin/com/anthropic/core/auth`
- [Config](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-core/src/main/kotlin/com/anthropic/config): profile-config · Profile and file-based configuration resolution · `anthropic-java-core/src/main/kotlin/com/anthropic/config`
- [Models](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-core/src/main/kotlin/com/anthropic/models): dto-schemas · Strongly typed request/response objects and error shapes · `anthropic-java-core/src/main/kotlin/com/anthropic/models`
- [Helpers](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-core/src/main/kotlin/com/anthropic/helpers): sdk-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](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-client-okhttp): runtime-adapter · Default concrete HTTP client for JVM usage · `anthropic-java-client-okhttp`
- [Bedrock adapter](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-bedrock): provider-adapter · AWS Bedrock backend integration · `anthropic-java-bedrock`
- [Vertex adapter](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-vertex): provider-adapter · Google Vertex backend integration · `anthropic-java-vertex`
- [Foundry adapter](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-foundry): provider-adapter · Microsoft Foundry backend integration · `anthropic-java-foundry`
- [AWS support](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-aws): aws-auth · AWS-specific auth and backend utilities shared by Bedrock · `anthropic-java-aws`

### Auxiliary

Examples, MCP integration, and compatibility checks

- [MCP module](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-mcp): integration · MCP resource and tool helpers outside the main client flow · `anthropic-java-mcp`
- [Examples](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-example): sample-app · Consumer-facing sample app covering major SDK flows · `anthropic-java-example`
- [ProGuard test](https://github.com/anthropics/anthropic-sdk-java/tree/main/anthropic-java-proguard-test): compatibility · Compatibility check for shrinking/obfuscation · `anthropic-java-proguard-test`

## Connections

- 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
