Java SDK

安裝並設定 Anthropic Java SDK，支援建構器模式與非同步操作

Anthropic Java SDK 讓以 Java 撰寫的應用程式能夠便利地存取 Claude API。它使用「builder pattern」（建構器模式）來建立請求，並同時支援同步與非同步操作。

安裝

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

<dependency>
    <groupId>com.anthropic</groupId>
    <artifactId>anthropic-java</artifactId>
    <version>3.3.0</version>
</dependency>

需求

此函式庫需要 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 的逐請求設定選項。

設定選項

Setter	系統屬性	環境變數	必要	預設值
`apiKey`	`anthropic.apiKey`	`ANTHROPIC_API_KEY`	false	-
`authToken`	`anthropic.authToken`	`ANTHROPIC_AUTH_TOKEN`	false	-
`baseUrl`	`anthropic.baseUrl`	`ANTHROPIC_BASE_URL`	true	`"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。

串流

「Streaming」（串流）：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 可以在處理回應中的事件串流時加以記錄，並累積出一個 Message 物件，類似於非串流 API 會回傳的內容。

對於同步回應，請在串流管線中加入 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();

另外也提供 BetaMessageAccumulator，用於累積 BetaMessage 物件。其使用方式與 MessageAccumulator 相同。

結構化輸出

如需包含 Java 範例的完整「structured outputs」（結構化輸出）文件，請參閱結構化輸出。

工具使用

Claude 的工具使用（tool use）讓您能將外部工具和函式直接整合到 AI 模型的回應中。模型可以在適當時機輸出呼叫工具或函式的指令（含參數），而不只是產生純文字。您為工具定義 JSON schema，模型則使用這些 schema 來判斷何時以及如何使用這些工具。

工具使用功能支援「strict」（嚴格）模式，可保證 AI 模型的 JSON 輸出符合您在輸入參數中提供的 JSON schema。

SDK 可以從任意 Java 類別的結構自動推導出工具及其參數：類別名稱（轉換為 snake case）提供工具名稱，而類別的欄位則定義工具的參數。

使用註解定義工具

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");
}

工具名稱轉換

工具名稱由 camel case 的工具類別名稱（例如 GetWeather）推導而來，並轉換為 snake case（例如 get_weather）。當目前字元不是第一個字元、為大寫，且前一個字元為小寫或下一個字元為小寫時，即為單字邊界的開始。例如，MyJSONParser 會變成 my_json_parser，而 ParseJSON 會變成 parse_json。此轉換可以使用 @JsonTypeName 註解覆寫。

本機工具 JSON schema 驗證

您可以執行本機驗證，檢查從工具類別推導出的 JSON schema 是否符合 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 schema 中加入更多關於工具的資訊：

@JsonClassDescription - 為工具類別加入描述，詳細說明何時以及如何使用該工具。
@JsonTypeName - 將工具名稱設定為類別簡單名稱轉換為 snake case 以外的名稱。
@JsonPropertyDescription - 為工具參數加入詳細描述。
@JsonIgnore - 將 public 欄位或 getter 方法從工具參數所產生的 JSON schema 中排除。
@JsonProperty - 將非 public 欄位或 getter 方法納入工具參數所產生的 JSON schema 中。

訊息批次

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);

二進位回應

對於不一定會解析為 JSON 的 API 回應，SDK 定義了回傳二進位回應的方法：

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 - 所有例外的基底類別。

狀態碼對應

狀態	例外
400	`BadRequestException`
401	`UnauthorizedException`
403	`PermissionDeniedException`
404	`NotFoundException`
422	`UnprocessableEntityException`
429	`RateLimitException`
5xx	`InternalServerException`
其他	`UnexpectedStatusCodeException`

在初始 HTTP 回應成功後，若 SSE 串流期間發生錯誤，會拋出 SseException。

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

除非被覆寫，否則這會產生最長 60 分鐘的逾時，並依 maxTokens 參數調整。

對於非串流請求，動態逾時會根據 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 會定期 ping API 以保持連線，並降低這些網路的影響。

如果預期非串流請求會超過 10 分鐘，SDK 會拋出錯誤。使用串流方法或在用戶端或請求層級覆寫逾時即可停用此錯誤。

分頁

SDK 提供便利的方式來存取分頁結果，可以一次一頁，或跨所有頁面逐項存取。

自動分頁

若要迭代所有頁面的所有結果，請使用 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 物件傳遞給其 setter：

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 用戶端自訂

Proxy 設定

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 由三個構件組成：

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：

將您的 anthropic-java 相依套件替換為 anthropic-java-core。
將 anthropic-java-client-okhttp 的 OkHttpClient 類別複製到您的程式碼中並加以自訂。
使用您自訂的用戶端建構 AnthropicClientImpl 或 AnthropicClientAsyncImpl。

完全自訂的 HTTP 用戶端

若要使用完全自訂的 HTTP 用戶端：

將您的 anthropic-java 相依套件替換為 anthropic-java-core。
撰寫一個實作 HttpClient 介面的類別。
使用您的新用戶端類別建構 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()；或使用 BedrockBackend.fromEnv() / BedrockBackend.builder()（bedrock-runtime 路徑）。
Claude Platform on AWS： com.anthropic:anthropic-java-aws：使用 AwsBackend.fromEnv()（讀取 ANTHROPIC_AWS_WORKSPACE_ID 以及 AWS 預設區域/憑證鏈）或 AwsBackend.builder()。以 beta 形式提供。
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)。此後端目前為 beta 版。請使用 GoogleCloudBackend.builder() 或 GoogleCloudBackend.fromEnv() 建立它。fromEnv() 會讀取 ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID、ANTHROPIC_GOOGLE_CLOUD_PROJECT 以及 Google Application Default Credentials。請參閱專案、位置與工作區解析。

平台構件是基礎 com.anthropic:anthropic-java 相依套件（提供 AnthropicOkHttpClient）的附加元件，因此請兩者都安裝。每個 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 tracer provider 時，SDK 會為其傳送的每個請求發出一個 span。若要將這些 span 傳送至您的可觀測性平台，請參閱搭配 Claude SDK 設定 OpenTelemetry。

未記載的 API 功能

SDK 針對已記載的 API 提供型別，以便於使用。不過，它也支援使用 API 中未記載或尚未支援的部分。

未記載的請求參數

若要設定未記載的請求參數，請依照未記載的參數中的說明，使用 putAdditionalHeader、putAdditionalQueryParam 或 putAdditionalBodyProperty 方法。

未記載的回應屬性

若要存取未記載的回應屬性，請依照回應屬性中的說明，使用 _additionalProperties() 方法。

新的或未發布的列舉值

SDK 中類似列舉的類別（例如 Model 和 AnthropicBeta）並非封閉的 Java enum 型別。每個類別都提供一個接受任意字串的 of(String) 工廠方法，因此您可以使用尚未加入 SDK 的值，例如在您的 SDK 版本之後才發布的模型或 beta 標頭：

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");

接受這些型別的建構器方法通常也會提供一個 String 多載，替您呼叫 of(...)：

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 版本發布期間，將欄位設定為未記載或尚未支援的值。

Beta 功能

Beta 功能會在正式發布前提供，以取得早期回饋並測試新功能。您可以在功能概覽中查看 Claude 所有功能和工具的可用性。

您可以透過用戶端上的 beta() 方法存取大多數 beta API 功能。若要啟用特定的 beta 功能，請在建構訊息參數時使用 .addBeta() 加入適當的 beta 標頭。

例如，若要啟用上下文編輯：

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 標頭中傳送一個 API 版本，且每個新的 API 版本都會伴隨一個新的主要版本。第一個傳送 2026-10-21 的主要版本是 3.0.0；請參閱遷移至 API 版本 2026-10-21。

此套件大致遵循 SemVer 慣例，但某些不向後相容的變更可能會以次要版本發布：

對函式庫內部的變更，這些內部在技術上是公開的，但並非設計或記載供外部使用。
預期在實務上不會影響絕大多數使用者的變更。

安裝

需求

快速入門

用戶端設定

API 金鑰設定

設定選項

修改設定

非同步用法

串流

同步串流

非同步串流

使用訊息累加器進行串流

結構化輸出

工具使用

使用註解定義工具

呼叫工具

工具名稱轉換

本機工具 JSON schema 驗證

為工具類別加上註解

訊息批次

檔案上傳

二進位回應

錯誤處理

狀態碼對應

請求 ID

重試

逾時

長時間請求

分頁

自動分頁

手動分頁

型別系統

不可變性與建構器

請求與回應

未記載的參數

建立 JsonValue

強制省略必要參數

回應屬性

回應驗證

HTTP 用戶端自訂

Proxy 設定

HTTPS / SSL 設定

自訂 HTTP 用戶端

自訂 OkHttpClient

完全自訂的 HTTP 用戶端

平台整合

進階用法

原始回應存取

記錄

Jackson 相容性

ProGuard/R8 設定

OpenTelemetry 追蹤

未記載的 API 功能

未記載的請求參數

未記載的回應屬性

新的或未發布的列舉值

Beta 功能

常見問題

為什麼 SDK 不使用一般的 enum 類別？

為什麼欄位使用 JsonField<T> 表示，而不是單純的 T？

為什麼 SDK 不使用 data class？

為什麼 SDK 不使用受檢例外？

語意化版本

其他資源

安裝

需求