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

Java SDK

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

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

インストール

implementation("com.anthropic:anthropic-java:2.58.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)
  .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)
  .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)
  .build();

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

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

ストリーミング

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

同期ストリーミング

これらの「streaming」（ストリーミング）メソッドは、同期クライアントに対して 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!");
        }
    }
});

// またはfutureを使用する
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();

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

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でのツール使用（tool use）により、外部ツールや関数を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)
        .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
              // ツール使用がリクエストされたことを示すメッセージを追加します。
              .addAssistantMessageOfBetaContentBlockParams(
                      List.of(BetaContentBlockParam.ofToolUse(BetaToolUseBlockParam.builder()
                              .name(toolUseBlock.name())
                              .id(toolUseBlock.id())
                              .input(toolUseBlock._input())
                              .build())))
              // リクエストされたツール使用の結果を含むメッセージを追加します。
              .addUserMessageOfBetaContentBlockParams(
                      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)
  .maxTokens(2048)
  .addTool(GetWeather.class, JsonSchemaLocalValidation.NO)
  .addUserMessage("What's the temperature in New York?");

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

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

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

メッセージバッチ

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)
  .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)
  .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)
  .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` に委譲します。
    // `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.fromEnv() または VertexBackend.builder() を使用します。
  • Bedrock: com.anthropic:anthropic-java-bedrock：Messages-API Bedrockエンドポイントには BedrockMantleBackend.fromEnv() または BedrockMantleBackend.builder() を使用し、または BedrockBackend.fromEnv() / BedrockBackend.builder()（bedrock-runtime パス）を使用します。
  • 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を使用する既存のアプリケーション向けに残されています。

各 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)
  .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

ドキュメント化されていない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のすべての機能とツールの利用可能状況は、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)
            .maxTokens(1024L)
            .addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27)
            .addUserMessage("Hello, Claude")
            .build());
}

よくある質問

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

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

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

追加リソース

Was this page helpful?