java changedcli-sdks-libraries/sdks/java
Nearest release: v2.1.312, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+30added
Lines−30removed
From line
99
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits30to this page, all time
The whole hunk
from line 99, old and new numbered
/
from line 99
9999 .build();
100100```
101101
102For authentication options including Workload Identity Federation, see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication). If your API key is a [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) that isn't scoped to a workspace, set the workspace ID in the `anthropic-workspace-id` request header; [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) shows the per-request option for this SDK.
102For authentication options including Workload Identity Federation, see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication). If your API key is a [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) that isn’t scoped to a workspace, set the workspace ID in the `anthropic-workspace-id` request header; [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) shows the per-request option for this SDK.
103103
104104### Configuration options
105105
from line 112
112112System properties take precedence over environment variables.
113113
114114<Tip>
115 Don't create more than one client in the same application. Each client has a connection pool and thread pools, which are more efficient to share between requests.
115 Don’t create more than one client in the same application. Each client has a connection pool and thread pools, which are more efficient to share between requests.
116116</Tip>
117117
118118### Modifying configuration
from line 176
176176
177177## Streaming
178178
179The SDK defines methods that return response "chunk" streams, where each chunk can be individually processed as soon as it arrives instead of waiting on the full response.
179The SDK defines methods that return response “chunk” streams, where each chunk can be individually processed as soon as it arrives instead of waiting on the full response.
180180
181181### Synchronous streaming
182182
from line 314
314314
315315## Tool use
316316
317[Tool use with Claude](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) lets you integrate external tools and functions directly into the AI model's responses. Instead of producing plain text, the model can output instructions (with parameters) for calling a tool or function when appropriate. You define JSON schemas for tools, and the model uses the schemas to determine when and how to use these tools.
317[Tool use with Claude](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) lets you integrate external tools and functions directly into the AI model’s responses. Instead of producing plain text, the model can output instructions (with parameters) for calling a tool or function when appropriate. You define JSON schemas for tools, and the model uses the schemas to determine when and how to use these tools.
318318
319The tool use feature supports a "strict" mode that guarantees that the JSON output from the AI model conforms to the JSON schema you provide in the input parameters.
319The tool use feature supports a “strict” mode that guarantees that the JSON output from the AI model conforms to the JSON schema you provide in the input parameters.
320320
321The SDK can derive a tool and its parameters automatically from the structure of an arbitrary Java class: the class's name (converted to snake case) provides the tool name, and the class's fields define the tool's parameters.
321The SDK can derive a tool and its parameters automatically from the structure of an arbitrary Java class: the class’s name (converted to snake case) provides the tool name, and the class’s fields define the tool’s parameters.
322322
323323<Note>
324324 Declare your tool classes as top-level classes or `static` nested classes. This requirement comes from the Jackson Databind library (`com.fasterxml.jackson.databind`), which the SDK uses to deserialize tool inputs into your class instances and cannot instantiate non-static inner classes.
from line 381
381381
382382### Calling tools
383383
384After you define your tool classes, add them to the message parameters using `MessageCreateParams.Builder.addTool(Class<T>)` and then call them if requested to do so in the AI model's response. `BetaToolUseBlock.input(Class<T>)` can be used to parse a tool's parameters in JSON form to an instance of your tool-defining class.
384After you define your tool classes, add them to the message parameters using `MessageCreateParams.Builder.addTool(Class<T>)` and then call them if requested to do so in the AI model’s response. `BetaToolUseBlock.input(Class<T>)` can be used to parse a tool’s parameters in JSON form to an instance of your tool-defining class.
385385
386After calling the tool, use `BetaToolResultBlockParam.Builder.contentAsJson(Object)` to pass the tool's result back to the AI model:
386After calling the tool, use `BetaToolResultBlockParam.Builder.contentAsJson(Object)` to pass the tool’s result back to the AI model:
387387
388388```java
389389import com.anthropic.client.AnthropicClient;
from line 436
436436
437437### Local tool JSON schema validation
438438
439You can perform local validation to check that the JSON schema derived from your tool class respects Anthropic's restrictions. Local validation is enabled by default, but it can be disabled:
439You can perform local validation to check that the JSON schema derived from your tool class respects Anthropic’s restrictions. Local validation is enabled by default, but it can be disabled:
440440
441441```java
442442MessageCreateParams.Builder createParamsBuilder = MessageCreateParams.builder()
from line 453
453453* `@JsonClassDescription` - Add a description to a tool class detailing when and how to use that tool.
454454* `@JsonTypeName` - Set the tool name to something other than the simple name of the class converted to snake case.
455455* `@JsonPropertyDescription` - Add a detailed description to a tool parameter.
456* `@JsonIgnore` - Exclude a `public` field or getter method from the generated JSON schema for a tool's parameters.
457* `@JsonProperty` - Include a non-`public` field or getter method in the generated JSON schema for a tool's parameters.
456* `@JsonIgnore` - Exclude a `public` field or getter method from the generated JSON schema for a tool’s parameters.
457* `@JsonProperty` - Include a non-`public` field or getter method in the generated JSON schema for a tool’s parameters.
458458
459459## Message batches
460460
from line 523
523523
524524### Binary responses
525525
526The SDK defines methods that return binary responses for API responses that aren't necessarily parsed as JSON:
526The SDK defines methods that return binary responses for API responses that aren’t necessarily parsed as JSON:
527527
528528```java
529529import com.anthropic.core.http.HttpResponse;
from line 568
568568* `AnthropicServiceException` - Base class for HTTP errors
569569* `AnthropicIoException` - I/O networking errors
570570* `AnthropicRetryableException` - Generic error indicating a failure that could be retried
571* `AnthropicInvalidDataException` - Failure to interpret successfully parsed data (for example, when accessing a property that's supposed to be required, but the API unexpectedly omitted it)
571* `AnthropicInvalidDataException` - Failure to interpret successfully parsed data (for example, when accessing a property that’s supposed to be required, but the API unexpectedly omitted it)
572572* `AnthropicException` - Base class for all exceptions
573573
574574### Status code mapping
from line 903
903903
904904### Forcibly omitting required parameters
905905
906Normally a `Builder` class's `build` method will throw `IllegalStateException` if any required parameter or property is unset. To forcibly omit a required parameter or property, pass `JsonMissing`:
906Normally a `Builder` class’s `build` method will throw `IllegalStateException` if any required parameter or property is unset. To forcibly omit a required parameter or property, pass `JsonMissing`:
907907
908908```java
909909import com.anthropic.core.JsonMissing;
from line 953
953953});
954954```
955955
956To access a property's raw JSON value, call its `_` prefixed method:
956To access a property’s raw JSON value, call its `_` prefixed method:
957957
958958```java
959959import com.anthropic.core.JsonField;
from line 977
977977
978978### Response validation
979979
980By default, the SDK does not throw an exception when the API returns a response that doesn't match the expected type. It throws `AnthropicInvalidDataException` only if you directly access the property.
980By default, the SDK does not throw an exception when the API returns a response that doesn’t match the expected type. It throws `AnthropicInvalidDataException` only if you directly access the property.
981981
982982To check that the response is completely well-typed upfront, call `validate()`:
983983
from line 1052
10521052* `anthropic-java-client-okhttp` - Depends on OkHttp. Exposes `AnthropicOkHttpClient` and `AnthropicOkHttpClientAsync`.
10531053* `anthropic-java` - Depends on and exposes the APIs of both `anthropic-java-core` and `anthropic-java-client-okhttp`. Does not have its own logic.
10541054
1055This structure allows replacing the SDK's default HTTP client without pulling in unnecessary dependencies.
1055This structure allows replacing the SDK’s default HTTP client without pulling in unnecessary dependencies.
10561056
10571057#### Customized OkHttpClient
10581058
from line 1063
10631063To use a customized `OkHttpClient`:
10641064
106510651. Replace your `anthropic-java` dependency with `anthropic-java-core`.
10662. Copy `anthropic-java-client-okhttp`'s `OkHttpClient` class into your code and customize it.
10662. Copy `anthropic-java-client-okhttp`’s `OkHttpClient` class into your code and customize it.
106710673. Construct `AnthropicClientImpl` or `AnthropicClientAsyncImpl` using your customized client.
10681068
10691069#### Completely custom HTTP client
from line 1156
11561156
11571157 The SDK throws an exception if it detects an incompatible Jackson version at runtime (for example, if the default version was overridden in your Maven or Gradle config).
11581158
1159 If the SDK threw an exception, but you're certain the version is compatible, then disable the version check using `checkJacksonVersionCompatibility` on `AnthropicOkHttpClient` or `AnthropicOkHttpClientAsync`.
1159 If the SDK threw an exception, but you’re certain the version is compatible, then disable the version check using `checkJacksonVersionCompatibility` on `AnthropicOkHttpClient` or `AnthropicOkHttpClientAsync`.
11601160
11611161 <Warning>
11621162 There is no guarantee that the SDK works correctly when the Jackson version check is disabled.
11631163 </Warning>
11641164
1165 There are also bugs in older Jackson versions that can affect the SDK. The SDK doesn't work around all Jackson bugs and expects users to upgrade Jackson for those instead.
1165 There are also bugs in older Jackson versions that can affect the SDK. The SDK doesn’t work around all Jackson bugs and expects users to upgrade Jackson for those instead.
11661166</Accordion>
11671167
11681168<Accordion title="ProGuard/R8 configuration">
from line 1215
12151215
12161216## Beta features
12171217
1218Beta features are available before general release to get early feedback and test new functionality. You can check the availability of all of Claude's capabilities and tools in the [Features overview](https://platform.claude.com/docs/en/build-with-claude/overview).
1218Beta features are available before general release to get early feedback and test new functionality. You can check the availability of all of Claude’s capabilities and tools in the [Features overview](https://platform.claude.com/docs/en/build-with-claude/overview).
12191219
12201220You can access most beta API features through the `beta()` method on the client. To enable a particular beta feature, add the appropriate [beta header](https://platform.claude.com/docs/en/api/beta-headers) with `.addBeta()` when building the message parameters.
12211221
from line 1242
12421242## Frequently asked questions
12431243
12441244<AccordionGroup>
1245 <Accordion title="Why doesn't the SDK use plain enum classes?">
1245 <Accordion title="Why doesn’t the SDK use plain enum classes?">
12461246 Java `enum` classes are not trivially forward compatible. Using them in the SDK could cause runtime exceptions if the API is updated to respond with a new enum value.
12471247
1248 Because these classes are open, you can also construct them with any string value through their `of(String)` factory method. See [New or unreleased enum values](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/java#new-or-unreleased-enum-values) if you need to use a value that isn't in your SDK version yet.
1248 Because these classes are open, you can also construct them with any string value through their `of(String)` factory method. See [New or unreleased enum values](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/java#new-or-unreleased-enum-values) if you need to use a value that isn’t in your SDK version yet.
12491249 </Accordion>
12501250
12511251 <Accordion title="Why are fields represented using JsonField<T> instead of just plain T?">
from line 1256
12561256 * Representing absent versus explicitly null values
12571257 </Accordion>
12581258
1259 <Accordion title="Why doesn't the SDK use data classes?">
1259 <Accordion title="Why doesn’t the SDK use data classes?">
12601260 It is not backwards compatible to add new fields to a data class, and the SDK avoids introducing a breaking change every time a field is added to a class.
12611261 </Accordion>
12621262
1263 <Accordion title="Why doesn't the SDK use checked exceptions?">
1263 <Accordion title="Why doesn’t the SDK use checked exceptions?">
12641264 Checked exceptions are widely considered a mistake in the Java programming language. In fact, they were omitted from Kotlin for this reason.
12651265
12661266 Checked exceptions:
from line 1268
12681268 * Are verbose to handle
12691269 * Encourage error handling at the wrong level of abstraction, where nothing can be done about the error
12701270 * Are tedious to propagate because of the function coloring problem
1271 * Don't work well with lambdas (also because of the function coloring problem)
1271 * Don’t work well with lambdas (also because of the function coloring problem)
12721272 </Accordion>
12731273</AccordionGroup>
12741274
from line 1279
12791279This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backward-incompatible changes may be released as minor versions:
12801280
128112811. Changes to library internals that are technically public but not intended or documented for external use.
12822. Changes that aren't expected to impact the vast majority of users in practice.
12822. Changes that aren’t expected to impact the vast majority of users in practice.
12831283
12841284## Additional resources
12851285
No line in this hunk matches that.