Claude Platform Docs
SDK、CLI、ライブラリクライアントSDK

Java SDK

ビルダーパターンと非同期サポートを備えたAnthropic Java SDKのインストールと設定

Anthropic Java SDKは、Javaで記述されたアプリケーションからClaude APIへの便利なアクセスを提供します。リクエストの作成にはビルダーパターンを使用し、同期操作と非同期操作の両方をサポートしています。

インストール

implementation("com.anthropic:anthropic-java:3.3.0")

要件

このライブラリにはJava 8以降が必要です。

クイックスタート

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

// `anthropic.apiKey`、`anthropic.authToken`、`anthropic.baseUrl` システムプロパティを使用して設定します
// または `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_BASE_URL` 環境変数を使用して設定します
AnthropicClient client = AnthropicOkHttpClient.fromEnv();

MessageCreateParams params = MessageCreateParams.builder()
  .maxTokens(1024L)
  .addUserMessage("Hello, Claude")
  .model(Model.CLAUDE_OPUS_5_5)
  .build();

Message message = client.messages().create(params);

クライアントの設定

APIキーの設定

システムプロパティまたは環境変数を使用してクライアントを設定します：

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

// `anthropic.apiKey`、`anthropic.authToken`、`anthropic.baseUrl` のシステムプロパティを使用して設定します
// または `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_BASE_URL` の環境変数を使用して設定します
AnthropicClient client = AnthropicOkHttpClient.fromEnv();

または手動で設定します：

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder()
  .apiKey("my-anthropic-api-key")
  .build();

または両方のアプローチを組み合わせて使用します：

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder()
  // システムプロパティまたは環境変数を使用して設定します
  .fromEnv()
  .apiKey("my-anthropic-api-key")
  .build();

Workload Identity Federationを含む認証オプションについては、認証を参照してください。APIキーがワークスペースにスコープされていない個人キーまたはサービスアカウントキーである場合は、anthropic-workspace-idリクエストヘッダーにワークスペースIDを設定してください。このSDKでのリクエストごとのオプションについては、ワークスペースを選択するで説明しています。

設定オプション

セッターシステムプロパティ環境変数必須デフォルト値
apiKeyanthropic.apiKeyANTHROPIC_API_KEYfalse-
authTokenanthropic.authTokenANTHROPIC_AUTH_TOKENfalse-
baseUrlanthropic.baseUrlANTHROPIC_BASE_URLtrue"https://api.anthropic.com"

システムプロパティは環境変数よりも優先されます。

設定の変更

同じコネクションプールとスレッドプールを再利用しながら、変更したクライアント設定を一時的に使用するには、任意のクライアントまたはサービスでwithOptions()を呼び出します：

import com.anthropic.client.AnthropicClient;

AnthropicClient clientWithOptions = client.withOptions(optionsBuilder -> {
  optionsBuilder.baseUrl("https://example.com");
  optionsBuilder.maxRetries(42);
});

withOptions()メソッドは、元のクライアントやサービスには影響しません。

非同期での使用

デフォルトのクライアントは同期型です。非同期実行に切り替えるには、async()メソッドを呼び出します：

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

AnthropicClient client = AnthropicOkHttpClient.fromEnv();

MessageCreateParams params = MessageCreateParams.builder()
  .maxTokens(1024L)
  .addUserMessage("Hello, Claude")
  .model(Model.CLAUDE_OPUS_5_5)
  .build();

CompletableFuture<Message> message = client.async().messages().create(params);

または最初から非同期クライアントを作成します：

import com.anthropic.client.AnthropicClientAsync;
import com.anthropic.client.okhttp.AnthropicOkHttpClientAsync;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

AnthropicClientAsync client = AnthropicOkHttpClientAsync.fromEnv();

MessageCreateParams params = MessageCreateParams.builder()
  .maxTokens(1024L)
  .addUserMessage("Hello, Claude")
  .model(Model.CLAUDE_OPUS_5_5)
  .build();

CompletableFuture<Message> message = client.messages().create(params);

非同期クライアントは同期クライアントと同じオプションをサポートしますが、ほとんどのメソッドはCompletableFutureを返します。

ストリーミング

SDKは、レスポンスの「チャンク」ストリームを返すメソッドを定義しています。各チャンクは、完全なレスポンスを待つことなく、到着次第個別に処理できます。

同期ストリーミング

これらのストリーミングメソッドは、同期クライアントの場合StreamResponseを返します：

import com.anthropic.core.http.StreamResponse;
import com.anthropic.models.messages.RawMessageStreamEvent;

try (StreamResponse<RawMessageStreamEvent> streamResponse = client.messages().createStreaming(params)) {
    streamResponse.stream().forEach(chunk -> {
        IO.println(chunk);
    });
    IO.println("No more chunks!");
}

非同期ストリーミング

非同期クライアントの場合、メソッドはAsyncStreamResponseを返します：

import com.anthropic.core.http.AsyncStreamResponse;
import com.anthropic.models.messages.RawMessageStreamEvent;

client.async().messages().createStreaming(params).subscribe(chunk -> {
    IO.println(chunk);
});

// ストリームのエラーや完了を処理する必要がある場合
client.async().messages().createStreaming(params).subscribe(new AsyncStreamResponse.Handler<>() {
    @Override
    public void onNext(RawMessageStreamEvent chunk) {
        IO.println(chunk);
    }

    @Override
    public void onComplete(Optional<Throwable> error) {
        if (error.isPresent()) {
            IO.println("Something went wrong!");
            throw new RuntimeException(error.get());
        } else {
            IO.println("No more chunks!");
        }
    }
});

// または futures を使用します
client.async().messages().createStreaming(params)
    .subscribe(chunk -> {
        IO.println(chunk);
    })
    .onCompleteFuture()
    .whenComplete((unused, error) -> {
        if (error != null) {
            IO.println("Something went wrong!");
            throw new RuntimeException(error);
        } else {
            IO.println("No more chunks!");
        }
    });

非同期ストリーミングは、現在のスレッドをブロックせずにストリーミングするために、クライアントごとの専用のキャッシュ型スレッドプールExecutorを使用します。別のExecutorを使用するには：

Executor executor = Executors.newFixedThreadPool(4);
client.async().messages().createStreaming(params).subscribe(
    chunk -> IO.println(chunk), executor
);

またはstreamHandlerExecutorメソッドを使用してクライアント全体で設定します：

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder()
  .fromEnv()
  .streamHandlerExecutor(Executors.newFixedThreadPool(4))
  .build();

メッセージアキュムレーターを使用したストリーミング

MessageAccumulatorは、レスポンス内のイベントストリームを処理されるたびに記録し、非ストリーミングAPIが返すものと同様のMessageオブジェクトを蓄積できます。

同期レスポンスの場合は、ストリームパイプラインにStream.peek()呼び出しを追加して各イベントを蓄積します：

import com.anthropic.core.http.StreamResponse;
import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.RawMessageStreamEvent;

MessageAccumulator messageAccumulator = MessageAccumulator.create();

try (StreamResponse<RawMessageStreamEvent> streamResponse =
         client.messages().createStreaming(createParams)) {
    streamResponse.stream()
            .peek(messageAccumulator::accumulate)
            .flatMap(event -> event.contentBlockDelta().stream())
            .flatMap(deltaEvent -> deltaEvent.delta().text().stream())
            .forEach(textDelta -> IO.print(textDelta.text()));
}

Message message = messageAccumulator.message();

非同期レスポンスの場合は、MessageAccumulatorをsubscribe()呼び出しに追加します：

import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.Message;

MessageAccumulator messageAccumulator = MessageAccumulator.create();

client.async().messages()
        .createStreaming(createParams)
        .subscribe(event -> messageAccumulator.accumulate(event).contentBlockDelta().stream()
                .flatMap(deltaEvent -> deltaEvent.delta().text().stream())
                .forEach(textDelta -> IO.print(textDelta.text())))
        .onCompleteFuture()
        .join();

Message message = messageAccumulator.message();

BetaMessageオブジェクトを蓄積するためのBetaMessageAccumulatorも利用できます。使い方はMessageAccumulatorと同じです。

構造化出力

Javaの例を含む構造化出力の完全なドキュメントについては、構造化出力を参照してください。

ツール使用

Claudeでのツール使用により、外部のツールや関数をAIモデルのレスポンスに直接統合できます。モデルはプレーンテキストを生成する代わりに、適切な場合にツールや関数を呼び出すための指示（パラメータ付き）を出力できます。ツールのJSONスキーマを定義すると、モデルはそのスキーマを使用して、これらのツールをいつどのように使用するかを判断します。

ツール使用機能は、AIモデルからのJSON出力が入力パラメータで指定したJSONスキーマに準拠することを保証する「strict」モードをサポートしています。

SDKは、任意のJavaクラスの構造からツールとそのパラメータを自動的に導出できます。クラス名（スネークケースに変換されたもの）がツール名となり、クラスのフィールドがツールのパラメータを定義します。

アノテーションによるツールの定義

import com.fasterxml.jackson.annotation.JsonClassDescription;
import com.fasterxml.jackson.annotation.JsonPropertyDescription;

enum Unit {
  CELSIUS,
  FAHRENHEIT;

  public String toString() {
    return switch (this) {
      case CELSIUS -> "C";
      case FAHRENHEIT -> "F";
    };
  }

  public double fromKelvin(double temperatureK) {
    return switch (this) {
      case CELSIUS -> temperatureK - 273.15;
      case FAHRENHEIT -> (temperatureK - 273.15) * 1.8 + 32.0;
    };
  }
}

@JsonClassDescription("Get the weather in a given location")
static class GetWeather {

  @JsonPropertyDescription("The city and state, e.g. San Francisco, CA")
  public String location;

  @JsonPropertyDescription("The unit of temperature")
  public Unit unit;

  public Weather execute() {
    double temperatureK = switch (location) {
      case "San Francisco, CA" -> 300.0;
      case "New York, NY" -> 310.0;
      case "Dallas, TX" -> 305.0;
      default -> 295;
    };
    return new Weather(String.format("%.0f%s", unit.fromKelvin(temperatureK), unit));
  }
}

static class Weather {

  public String temperature;

  public Weather(String temperature) {
    this.temperature = temperature;
  }
}

ツールの呼び出し

ツールクラスを定義したら、MessageCreateParams.Builder.addTool(Class<T>)を使用してメッセージパラメータに追加し、AIモデルのレスポンスで要求された場合にそれらを呼び出します。BetaToolUseBlock.input(Class<T>)を使用すると、JSON形式のツールのパラメータを、ツールを定義するクラスのインスタンスにパースできます。

ツールを呼び出した後、BetaToolResultBlockParam.Builder.contentAsJson(Object)を使用してツールの結果をAIモデルに返します：

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.messages.*;
import com.anthropic.models.messages.Model;

AnthropicClient client = AnthropicOkHttpClient.fromEnv();

MessageCreateParams.Builder createParamsBuilder = MessageCreateParams.builder()
        .model(Model.CLAUDE_OPUS_5_5)
        .maxTokens(2048)
        .addTool(GetWeather.class)
        .addUserMessage("What's the temperature in New York?");

client.beta().messages().create(createParamsBuilder.build()).content().stream()
        .flatMap(contentBlock -> contentBlock.toolUse().stream())
        .forEach(toolUseBlock -> createParamsBuilder
              // ツール使用がリクエストされたことを示すメッセージを追加します。
              .addAssistantMessageOfContentBlockParams(
                      List.of(BetaContentBlockParam.ofToolUse(BetaToolUseBlockParam.builder()
                              .name(toolUseBlock.name())
                              .id(toolUseBlock.id())
                              .input(toolUseBlock._input())
                              .build())))
              // リクエストされたツール使用の結果を含むメッセージを追加します。
              .addUserMessageOfContentBlockParams(
                      List.of(BetaContentBlockParam.ofToolResult(BetaToolResultBlockParam.builder()
                              .toolUseId(toolUseBlock.id())
                              .contentAsJson(callTool(toolUseBlock))
                              .build()))));

client.beta().messages().create(createParamsBuilder.build()).content().stream()
        .flatMap(contentBlock -> contentBlock.text().stream())
        .forEach(textBlock -> IO.println(textBlock.text()));

private static Object callTool(BetaToolUseBlock toolUseBlock) {
  if (!"get_weather".equals(toolUseBlock.name())) {
    throw new IllegalArgumentException("Unknown tool: " + toolUseBlock.name());
  }

  GetWeather tool = toolUseBlock.input(GetWeather.class);
  return tool != null ? tool.execute() : new Weather("unknown");
}

ツール名の変換

ツール名は、キャメルケースのツールクラス名（例：GetWeather）から導出され、スネークケース（例：get_weather）に変換されます。単語の境界は、現在の文字が最初の文字ではなく、大文字であり、かつ直前の文字が小文字であるか、直後の文字が小文字である位置から始まります。たとえば、MyJSONParserはmy_json_parserに、ParseJSONはparse_jsonになります。この変換は@JsonTypeNameアノテーションを使用して上書きできます。

ローカルでのツールJSONスキーマ検証

ツールクラスから導出されたJSONスキーマがAnthropicの制約を満たしているかを確認するために、ローカル検証を実行できます。ローカル検証はデフォルトで有効になっていますが、無効にすることもできます：

MessageCreateParams.Builder createParamsBuilder = MessageCreateParams.builder()
  .model(Model.CLAUDE_OPUS_5_5)
  .maxTokens(2048)
  .addTool(GetWeather.class, JsonSchemaLocalValidation.NO)
  .addUserMessage("What's the temperature in New York?");

ツールクラスへのアノテーション付与

アノテーションを使用して、ツールに関する追加情報をJSONスキーマに追加できます：

  • @JsonClassDescription - ツールクラスに、そのツールをいつどのように使用するかを詳述する説明を追加します。
  • @JsonTypeName - ツール名を、スネークケースに変換されたクラスの単純名以外のものに設定します。
  • @JsonPropertyDescription - ツールパラメータに詳細な説明を追加します。
  • @JsonIgnore - publicフィールドまたはゲッターメソッドを、ツールのパラメータ用に生成されるJSONスキーマから除外します。
  • @JsonProperty - 非publicのフィールドまたはゲッターメソッドを、ツールのパラメータ用に生成されるJSONスキーマに含めます。

メッセージバッチ

SDKは、client.messages().batches()名前空間でバッチ処理をサポートしています。バッチの一覧表示とページネーションの方法については、ページネーションを参照してください。

ファイルのアップロード

SDKは、MultipartFieldクラスを通じてファイルを受け付けるメソッドを定義しています：

import com.anthropic.core.MultipartField;
import com.anthropic.models.files.FileMetadata;
import com.anthropic.models.files.FileUploadParams;

FileUploadParams params = FileUploadParams.builder()
  .file(
    MultipartField.<InputStream>builder()
      .value(Files.newInputStream(Paths.get("/path/to/file.pdf")))
      .contentType("application/pdf")
      .build()
  )
  .build();

FileMetadata fileMetadata = client.files().upload(params);

またはInputStreamから：

import com.anthropic.core.MultipartField;
import com.anthropic.models.files.FileMetadata;
import com.anthropic.models.files.FileUploadParams;

FileUploadParams params = FileUploadParams.builder()
  .file(
    MultipartField.<InputStream>builder()
      .value(URI.create("https://example.com/path/to/file").toURL().openStream())
      .filename("document.pdf")
      .contentType("application/pdf")
      .build()
  )
  .build();

FileMetadata fileMetadata = client.files().upload(params);

またはメモリ上のバイト列から：

import com.anthropic.core.MultipartField;
import com.anthropic.models.files.FileMetadata;
import com.anthropic.models.files.FileUploadParams;

FileUploadParams params = FileUploadParams.builder()
  .file(
    MultipartField.<InputStream>builder()
      .value(new ByteArrayInputStream("content".getBytes()))
      .filename("document.txt")
      .contentType("text/plain")
      .build()
  )
  .build();

FileMetadata fileMetadata = client.files().upload(params);

バイナリレスポンス

SDKは、必ずしもJSONとしてパースされないAPIレスポンスに対して、バイナリレスポンスを返すメソッドを定義しています：

import com.anthropic.core.http.HttpResponse;

HttpResponse response = client.files().download("file_abc123");

レスポンスの内容をファイルに保存するには：

import com.anthropic.core.http.HttpResponse;

try (HttpResponse response = client.files().download(params)) {
    Files.copy(
        response.body(),
        Paths.get(path),
        StandardCopyOption.REPLACE_EXISTING
    );
} catch (Exception e) {
    IO.println("Something went wrong!");
    throw new RuntimeException(e);
}

またはレスポンスの内容を任意のOutputStreamに転送します：

import com.anthropic.core.http.HttpResponse;

try (HttpResponse response = client.files().download(params)) {
    response.body().transferTo(Files.newOutputStream(Paths.get(path)));
} catch (Exception e) {
    IO.println("Something went wrong!");
    throw new RuntimeException(e);
}

エラー処理

SDKは独自の非チェック例外型をスローします：

  • AnthropicServiceException - HTTPエラーの基底クラス。
  • AnthropicIoException - I/Oネットワークエラー。
  • AnthropicRetryableException - 再試行可能な失敗を示す汎用エラー。
  • AnthropicInvalidDataException - 正常にパースされたデータの解釈の失敗（たとえば、必須であるはずのプロパティにアクセスしたが、APIが予期せずそれを省略していた場合）。
  • AnthropicException - すべての例外の基底クラス。

ステータスコードのマッピング

ステータス例外
400BadRequestException
401UnauthorizedException
403PermissionDeniedException
404NotFoundException
422UnprocessableEntityException
429RateLimitException
5xxInternalServerException
その他UnexpectedStatusCodeException

SseExceptionは、最初のHTTPレスポンスが成功した後のSSEストリーミング中に発生したエラーに対してスローされます。

import com.anthropic.errors.*;

try {
    Message message = client.messages().create(params);
} catch (RateLimitException e) {
    IO.println("Rate limited, retry after: " + e.headers());
} catch (UnauthorizedException e) {
    IO.println("Invalid API key");
} catch (AnthropicServiceException e) {
    IO.println("API error: " + e.statusCode());
} catch (AnthropicIoException e) {
    IO.println("Network error: " + e.getMessage());
}

リクエストID

生のレスポンスを使用する場合、requestId()メソッドを使用してrequest-idレスポンスヘッダーにアクセスできます：

import com.anthropic.core.http.HttpResponseFor;
import com.anthropic.models.messages.Message;

HttpResponseFor<Message> message = client.messages().withRawResponse().create(params);

Optional<String> requestId = message.requestId();

これを使用して、失敗したリクエストをすばやくログに記録し、Anthropicに報告できます。リクエストのデバッグの詳細については、リクエストIDを参照してください。

再試行

SDKはデフォルトで自動的に2回再試行し、リクエスト間には短い指数バックオフが入ります。

次のエラータイプのみが再試行されます：

  • 接続エラー（たとえば、ネットワーク接続の問題によるもの）
  • 408 Request Timeout
  • 409 Conflict
  • 429 Rate Limit
  • 5xx Internal

APIは、リクエストを再試行するかどうかをSDKに明示的に指示することもあります。

再試行回数をカスタム設定するには、maxRetriesメソッドを使用してクライアントを設定します：

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder().fromEnv().maxRetries(4).build();

タイムアウト

リクエストはデフォルトで10分後にタイムアウトします。

ただし、maxTokensを受け付けるメソッドで、大きなmaxTokens値を指定してストリーミングを行っている場合、デフォルトのタイムアウトは次の式を使用して動的に計算されます：

Duration.ofSeconds(
    Math.min(
        60 * 60, // 1 hour max
        Math.max(
            10 * 60, // 10 minute minimum
            60 * 60 * maxTokens / 128_000
        )
    )
)

これにより、上書きされない限り、maxTokensパラメータに応じて最大60分のタイムアウトになります。

非ストリーミングリクエストの場合、動的タイムアウトはmaxTokensに基づいて最小30秒から最大10分までの範囲で変化します。

リクエストごとにカスタムタイムアウトを設定するには：

import com.anthropic.models.messages.Message;

Message message = client
  .messages()
  .create(params, RequestOptions.builder().timeout(Duration.ofSeconds(30)).build());

またはクライアントレベルですべてのメソッド呼び出しのデフォルトを設定します：

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder()
  .fromEnv()
  .timeout(Duration.ofSeconds(30))
  .build();

長時間のリクエスト

ストリーミングを使用せずに大きなmaxTokens値を設定することは避けてください。一部のネットワークでは、一定時間が経過するとアイドル状態の接続が切断されることがあり、その結果、Anthropicからレスポンスを受け取ることなくリクエストが失敗したりタイムアウトしたりする可能性があります。SDKは定期的にAPIにpingを送信して接続を維持し、こうしたネットワークの影響を軽減します。

非ストリーミングリクエストが10分以上かかると予想される場合、SDKはエラーをスローします。ストリーミングメソッドを使用するか、クライアントまたはリクエストレベルでタイムアウトを上書きすると、このエラーは無効になります。

ページネーション

SDKは、ページ分割された結果に、1ページずつ、またはすべてのページにわたって項目ごとにアクセスするための便利な方法を提供します。

自動ページネーション

すべてのページにわたってすべての結果を反復処理するには、必要に応じて自動的に追加のページを取得するautoPager()メソッドを使用します。

import com.anthropic.models.messages.batches.BatchListPage;
import com.anthropic.models.messages.batches.MessageBatch;

BatchListPage page = client.messages().batches().list();

// Iterable として処理します
for (MessageBatch batch : page.autoPager()) {
    IO.println(batch);
}

// Stream として処理します
page.autoPager()
    .stream()
    .limit(50)
    .forEach(batch -> IO.println(batch));

非同期クライアントを使用する場合、メソッドはAsyncStreamResponseを返します：

import com.anthropic.core.http.AsyncStreamResponse;
import com.anthropic.models.messages.batches.BatchListPageAsync;
import com.anthropic.models.messages.batches.MessageBatch;

CompletableFuture<BatchListPageAsync> pageFuture = client.async().messages().batches().list();

pageFuture.thenAccept(page -> page.autoPager().subscribe(batch -> {
    IO.println(batch);
}));

// ストリームのエラーや完了を処理する必要がある場合
pageFuture.thenAccept(page -> page.autoPager().subscribe(new AsyncStreamResponse.Handler<>() {
    @Override
    public void onNext(MessageBatch batch) {
        IO.println(batch);
    }

    @Override
    public void onComplete(Optional<Throwable> error) {
        if (error.isPresent()) {
            IO.println("Something went wrong!");
            throw new RuntimeException(error.get());
        } else {
            IO.println("No more!");
        }
    }
}));

// または futures を使用します
pageFuture.thenAccept(page -> page.autoPager()
    .subscribe(batch -> {
        IO.println(batch);
    })
    .onCompleteFuture()
    .whenComplete((unused, error) -> {
        if (error != null) {
            IO.println("Something went wrong!");
            throw new RuntimeException(error);
        } else {
            IO.println("No more!");
        }
    }));

手動ページネーション

個々のページの項目にアクセスし、次のページを手動でリクエストするには：

import com.anthropic.models.messages.batches.BatchListPage;
import com.anthropic.models.messages.batches.MessageBatch;

BatchListPage page = client.messages().batches().list();
while (true) {
    for (MessageBatch batch : page.items()) {
        IO.println(batch);
    }

    if (!page.hasNextPage()) {
        break;
    }

    page = page.nextPage();
}

型システム

イミュータビリティとビルダー

SDKの各クラスには、それを構築するための関連ビルダーがあります。各クラスは構築後はイミュータブルです。クラスに関連ビルダーがある場合、そのクラスにはtoBuilder()メソッドがあり、これを使用してビルダーに戻し、変更したコピーを作成できます。

MessageCreateParams params = MessageCreateParams.builder()
  .maxTokens(1024L)
  .addUserMessage("Hello, Claude")
  .model(Model.CLAUDE_OPUS_5_5)
  .build();

// toBuilder() を使用して変更したコピーを作成します
MessageCreateParams modified = params.toBuilder().maxTokens(2048L).build();

各クラスはイミュータブルであるため、ビルダーを変更しても、すでに構築されたクラスインスタンスに影響することはありません。

リクエストとレスポンス

Claude APIにリクエストを送信するには、何らかのParamsクラスのインスタンスを構築し、対応するクライアントメソッドに渡します。レスポンスを受信すると、それはJavaクラスのインスタンスにデシリアライズされます。

たとえば、client.messages().create(...)はMessageCreateParamsのインスタンスを指定して呼び出す必要があり、Messageのインスタンスを返します。

ドキュメント化されていないパラメータ

ドキュメント化されていないパラメータを設定するには、任意のParamsクラスでputAdditionalHeader、putAdditionalQueryParam、またはputAdditionalBodyPropertyメソッドを呼び出します：

import com.anthropic.core.JsonValue;
import com.anthropic.models.messages.MessageCreateParams;

MessageCreateParams params = MessageCreateParams.builder()
  .putAdditionalHeader("Secret-Header", "42")
  .putAdditionalQueryParam("secret_query_param", "42")
  .putAdditionalBodyProperty("secretProperty", JsonValue.from("42"))
  .build();

これらは後で、構築されたオブジェクト上で_additionalHeaders()、_additionalQueryParams()、_additionalBodyProperties()メソッドを使用してアクセスできます。

ネストされたヘッダー、クエリパラメータ、またはボディクラスにドキュメント化されていないパラメータを設定するには：

import com.anthropic.core.JsonValue;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Metadata;

MessageCreateParams params = MessageCreateParams.builder()
  .metadata(
    Metadata.builder().putAdditionalProperty("secretProperty", JsonValue.from("42")).build()
  )
  .build();

これらのプロパティは後で、ネストされた構築済みオブジェクト上で_additionalProperties()メソッドを使用してアクセスできます。

ドキュメント化されたパラメータまたはプロパティを、ドキュメント化されていない値やまだサポートされていない値に設定するには、そのセッターにJsonValueオブジェクトを渡します：

import com.anthropic.core.JsonValue;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

MessageCreateParams params = MessageCreateParams.builder()
  .maxTokens(JsonValue.from(3.14))
  .addUserMessage("Hello, Claude")
  .model(Model.CLAUDE_OPUS_5_5)
  .build();

JsonValueの作成

JsonValueを作成する最も簡単な方法は、そのfrom(...)メソッドを使用することです：

import com.anthropic.core.JsonValue;

// プリミティブな JSON 値を作成します
JsonValue nullValue = JsonValue.from(null);

JsonValue booleanValue = JsonValue.from(true);

JsonValue numberValue = JsonValue.from(42);

JsonValue stringValue = JsonValue.from("Hello World!");

// `["Hello", "World"]` と同等の JSON 配列値を作成します
JsonValue arrayValue = JsonValue.from(List.of("Hello", "World"));

// `{ "a": 1, "b": 2 }` と同等の JSON オブジェクト値を作成します
JsonValue objectValue = JsonValue.from(Map.of("a", 1, "b", 2));

// 次と同等の任意にネストされた JSON を作成します:
// { "a": [1, 2], "b": [3, 4] }
JsonValue complexValue = JsonValue.from(Map.of("a", List.of(1, 2), "b", List.of(3, 4)));

必須パラメータの強制的な省略

通常、Builderクラスのbuildメソッドは、必須のパラメータまたはプロパティが設定されていない場合にIllegalStateExceptionをスローします。必須のパラメータまたはプロパティを強制的に省略するには、JsonMissingを渡します：

import com.anthropic.core.JsonMissing;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

MessageCreateParams params = MessageCreateParams.builder()
  .addUserMessage("Hello, world")
  .model(Model.CLAUDE_OPUS_5_5)
  .maxTokens(JsonMissing.of())
  .build();

レスポンスのプロパティ

ドキュメント化されていないレスポンスのプロパティにアクセスするには、_additionalProperties()メソッドを呼び出します：

import com.anthropic.core.JsonValue;

Map<String, JsonValue> additionalProperties = client
  .messages()
  .create(params)
  ._additionalProperties();

JsonValue secretPropertyValue = additionalProperties.get("secretProperty");

String result = secretPropertyValue.accept(new JsonValue.Visitor<>() {
    @Override
    public String visitNull() {
        return "It's null!";
    }

    @Override
    public String visitBoolean(boolean value) {
        return "It's a boolean!";
    }

    @Override
    public String visitNumber(Number value) {
        return "It's a number!";
    }

    // その他のメソッドには `visitMissing`、`visitString`、`visitArray`、`visitObject` があります
    // 未実装の各メソッドのデフォルト実装は `visitDefault` に委譲します。
    // これはデフォルトでは例外をスローしますが、オーバーライドすることもできます
});

プロパティの生のJSON値にアクセスするには、_プレフィックス付きのメソッドを呼び出します：

import com.anthropic.core.JsonField;
import com.anthropic.models.messages.StopReason;

JsonField<StopReason> stopReason = client.messages().create(params)._stopReason();

if (stopReason.isMissing()) {
  // このプロパティは JSON レスポンスに存在しません
} else if (stopReason.isNull()) {
  // このプロパティはリテラルの null に設定されています
} else {
  // 値が文字列として指定されたかどうかを確認します
  // 他のメソッドには `asNumber()`、`asBoolean()` などがあります
  Optional<String> jsonString = stopReason.asString();

  // カスタム型へのデシリアライズを試みます
  MyClass myObject = stopReason.asUnknown().orElseThrow().convert(MyClass.class);
}

レスポンスの検証

デフォルトでは、APIが期待される型と一致しないレスポンスを返しても、SDKは例外をスローしません。そのプロパティに直接アクセスした場合にのみAnthropicInvalidDataExceptionをスローします。

レスポンスが完全に正しく型付けされていることを事前に確認するには、validate()を呼び出します：

import com.anthropic.models.messages.Message;

Message message = client.messages().create(params).validate();

またはリクエストごとに設定します：

import com.anthropic.models.messages.Message;

Message message = client
  .messages()
  .create(params, RequestOptions.builder().responseValidation(true).build());

またはクライアントレベルですべてのメソッド呼び出しのデフォルトを設定します：

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder()
  .fromEnv()
  .responseValidation(true)
  .build();

HTTPクライアントのカスタマイズ

プロキシの設定

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import java.net.Proxy;

AnthropicClient client = AnthropicOkHttpClient.builder()
  .fromEnv()
  .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("https://example.com", 8080)))
  .build();

HTTPS / SSLの設定

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder()
  .fromEnv()
  .sslSocketFactory(yourSSLSocketFactory)
  .trustManager(yourTrustManager)
  .hostnameVerifier(yourHostnameVerifier)
  .build();

カスタムHTTPクライアント

SDKは3つのアーティファクトで構成されています：

  • anthropic-java-core - SDKのコアロジックを含み、OkHttpには依存しません。AnthropicClient、AnthropicClientAsync、およびそれらの実装クラスを公開しており、これらはすべて任意のHTTPクライアントで動作します。
  • anthropic-java-client-okhttp - OkHttpに依存します。AnthropicOkHttpClientとAnthropicOkHttpClientAsyncを公開します。
  • anthropic-java - anthropic-java-coreとanthropic-java-client-okhttpの両方に依存し、それらのAPIを公開します。独自のロジックは持ちません。

この構造により、不要な依存関係を取り込むことなく、SDKのデフォルトのHTTPクライアントを置き換えることができます。

カスタマイズしたOkHttpClient

カスタマイズしたOkHttpClientを使用するには：

  1. anthropic-java依存関係をanthropic-java-coreに置き換えます。
  2. anthropic-java-client-okhttpのOkHttpClientクラスをコードにコピーし、カスタマイズします。
  3. カスタマイズしたクライアントを使用してAnthropicClientImplまたはAnthropicClientAsyncImplを構築します。

完全にカスタムなHTTPクライアント

完全にカスタムなHTTPクライアントを使用するには：

  1. anthropic-java依存関係をanthropic-java-coreに置き換えます。
  2. HttpClientインターフェースを実装するクラスを作成します。
  3. 新しいクライアントクラスを使用してAnthropicClientImplまたはAnthropicClientAsyncImplを構築します。

プラットフォーム統合

Java SDKは、プラットフォーム固有のBackend実装を提供する個別の依存関係を通じて、以下のプラットフォームをサポートしています：

  • Agent Platform： com.anthropic:anthropic-java-vertex：VertexBackend.builder()またはVertexBackend.fromEnv()を使用します。fromEnv()はCLOUD_ML_REGIONとANTHROPIC_VERTEX_PROJECT_IDを読み取り、Application Default Credentialsを使用します。
  • Bedrock： com.anthropic:anthropic-java-bedrock：Messages-APIのBedrockエンドポイントにはBedrockMantleBackend.fromEnv()またはBedrockMantleBackend.builder()を、bedrock-runtimeパスにはBedrockBackend.fromEnv() / BedrockBackend.builder()を使用します。
  • Claude Platform on AWS： com.anthropic:anthropic-java-aws：AwsBackend.fromEnv()（ANTHROPIC_AWS_WORKSPACE_IDとAWSのデフォルトのリージョン/認証情報チェーンを読み取ります）またはAwsBackend.builder()を使用します。ベータ版で利用可能です。
  • Foundry： com.anthropic:anthropic-java-foundry：FoundryBackend.fromEnv()またはFoundryBackend.builder()を使用します。

新しいプロジェクトにはBedrockMantleBackendを使用してください。BedrockBackendは、BedrockのInvokeModel APIを使用する既存のアプリケーション向けに引き続き提供されています。

Java SDKは、com.anthropic:anthropic-java-google-cloud依存関係のGoogleCloudBackendを通じて、Claude Models on Google Cloud (Anthropic managed)もサポートしています。このバックエンドはベータ版です。GoogleCloudBackend.builder()またはGoogleCloudBackend.fromEnv()で作成します。fromEnv()はANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID、ANTHROPIC_GOOGLE_CLOUD_PROJECT、およびGoogle Application Default Credentialsを読み取ります。プロジェクト、ロケーション、およびワークスペースの解決を参照してください。

プラットフォームアーティファクトは、AnthropicOkHttpClientを提供するベースのcom.anthropic:anthropic-java依存関係へのアドオンであるため、両方をインストールしてください。各Backend実装は、AnthropicOkHttpClient.builder()上の.backend()でクライアントに渡されます。各クラウドバックエンドは、それぞれのクラウドプラットフォームSDKのクラスを推移的依存関係として取り込みます。

高度な使用方法

生のレスポンスへのアクセス

HTTPヘッダー、ステータスコード、および生のレスポンスボディにアクセスするには、任意のHTTPメソッド呼び出しの前にwithRawResponse()を付けます：

import com.anthropic.core.http.Headers;
import com.anthropic.core.http.HttpResponseFor;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

MessageCreateParams params = MessageCreateParams.builder()
  .maxTokens(1024L)
  .addUserMessage("Hello, Claude")
  .model(Model.CLAUDE_OPUS_5_5)
  .build();

HttpResponseFor<Message> message = client.messages().withRawResponse().create(params);

int statusCode = message.statusCode();

Headers headers = message.headers();

必要に応じて、レスポンスをJavaクラスのインスタンスにデシリアライズすることもできます：

import com.anthropic.models.messages.Message;

Message parsedMessage = message.parse();

ロギング

SDKは標準のOkHttpロギングインターセプターを使用します。

ANTHROPIC_LOG環境変数をinfoに設定してロギングを有効にします：

export ANTHROPIC_LOG=info

より詳細なロギングにはdebugに設定します：

export ANTHROPIC_LOG=debug

OpenTelemetryトレーシング

アプリケーションがOpenTelemetryトレーサープロバイダーを登録すると、SDKは送信する各リクエストについてスパンを出力します。スパンをオブザーバビリティプラットフォームに送信するには、Claude SDKでOpenTelemetryを設定するを参照してください。

ドキュメント化されていないAPI機能

SDKは、ドキュメント化されたAPIを便利に使用できるように型付けされています。ただし、APIのドキュメント化されていない部分やまだサポートされていない部分を扱うこともサポートしています。

ドキュメント化されていないリクエストパラメータ

ドキュメント化されていないリクエストパラメータを設定するには、ドキュメント化されていないパラメータで説明されているように、putAdditionalHeader、putAdditionalQueryParam、またはputAdditionalBodyPropertyメソッドを使用します。

ドキュメント化されていないレスポンスのプロパティ

ドキュメント化されていないレスポンスのプロパティにアクセスするには、レスポンスのプロパティで説明されているように、_additionalProperties()メソッドを使用します。

新しい、または未リリースのenum値

ModelやAnthropicBetaなど、SDK内のenumに似たクラスは、閉じたJavaのenum型ではありません。それぞれが任意の文字列を受け付けるof(String)ファクトリメソッドを提供しているため、SDKのバージョンより後にリリースされたモデルやベータヘッダーなど、まだSDKに追加されていない値を使用できます：

import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.messages.Model;

Model model = Model.of("some-new-model");
AnthropicBeta beta = AnthropicBeta.of("some-new-beta-2026-01-01");

これらの型を受け取るビルダーメソッドは、多くの場合、of(...)を代わりに呼び出すStringオーバーロードも提供しています：

import com.anthropic.models.messages.MessageCreateParams;

MessageCreateParams params = MessageCreateParams.builder()
  .model("some-new-model") // same as .model(Model.of("some-new-model"))
  .maxTokens(1024L)
  .addUserMessage("Hello, Claude")
  .build();

オートコンプリートや非推奨の警告を得られるように、適切に型付けされた定数（たとえばModel.CLAUDE_OPUS_5）を優先して使用してください。Stringオーバーロードとof(...)は、主に、その値を含むSDKリリースを待つ間に、フィールドをドキュメント化されていない値やまだサポートされていない値に設定するためのものです。

ベータ機能

ベータ機能は、早期のフィードバックを得て新機能をテストするために、正式リリース前に利用可能になります。Claudeのすべての機能とツールの利用可能状況は、機能の概要で確認できます。

ほとんどのベータAPI機能には、クライアントのbeta()メソッドを通じてアクセスできます。特定のベータ機能を有効にするには、メッセージパラメータを構築する際に.addBeta()で適切なベータヘッダーを追加します。

たとえば、コンテキスト編集を有効にするには：

import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.MessageCreateParams;

void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    BetaMessage message = client.beta().messages().create(
        MessageCreateParams.builder()
            .model(Model.CLAUDE_OPUS_5_5)
            .maxTokens(1024L)
            .addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27)
            .addUserMessage("Hello, Claude")
            .build());
}

よくある質問

セマンティックバージョニング

このSDKの各メジャーバージョンは、デフォルトでanthropic-versionヘッダーに1つのAPIバージョンを送信し、新しいAPIバージョンごとに新しいメジャーバージョンがリリースされます。2026-10-21を送信する最初のメジャーバージョンは3.0.0です。APIバージョン2026-10-21への移行を参照してください。

このパッケージは一般的にSemVerの規約に従っていますが、特定の後方互換性のない変更がマイナーバージョンとしてリリースされる場合があります：

  1. 技術的には公開されているものの、外部での使用を意図していない、またはドキュメント化されていないライブラリ内部の変更。
  2. 実際には大多数のユーザーに影響を与えないと予想される変更。

その他のリソース

Was this page helpful?