Java SDK

Anthropic Java SDK предоставляет удобный доступ к Anthropic REST API из приложений, написанных на Java. Он использует паттерн «builder» (строитель) для создания запросов и поддерживает как синхронные, так и асинхронные операции.

Документацию по функциям API с примерами кода см. в справочнике API. На этой странице рассматриваются специфичные для Java функции SDK и его настройка.

Установка

Требования

Эта библиотека требует Java 8 или более поздней версии.

SDK поддерживает Java 8 и более поздние версии. Примеры кода в этой документации написаны как компактные исходные файлы JDK 25 с использованием простой точки входа void main() и IO.println() для вывода. Сами вызовы API идентичны на любой поддерживаемой версии JDK; чтобы скомпилировать пример на более ранней версии, замените IO.println(...) на System.out.println(...) и поместите тело внутрь public static void main(String[] args) в классе.

Быстрый старт

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_4_8)
  .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, см. в разделе Аутентификация.

Параметры конфигурации

Сеттер	Системное свойство	Переменная окружения	Обязательно	Значение по умолчанию
`apiKey`	`anthropic.apiKey`	`ANTHROPIC_API_KEY`	false	-
`authToken`	`anthropic.authToken`	`ANTHROPIC_AUTH_TOKEN`	false	-
`baseUrl`	`anthropic.baseUrl`	`ANTHROPIC_BASE_URL`	true

Системные свойства имеют приоритет над переменными окружения.

Не создавайте более одного клиента в одном приложении. Каждый клиент имеет пул соединений и пулы потоков, которые эффективнее разделять между запросами.

Изменение конфигурации

Чтобы временно использовать изменённую конфигурацию клиента, повторно используя те же пулы соединений и потоков, вызовите 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_4_8)
  .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_4_8)
  .build();

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

Асинхронный клиент поддерживает те же параметры, что и синхронный, за исключением того, что большинство методов возвращают CompletableFuture.

Потоковая передача

SDK определяет методы, которые возвращают потоки «фрагментов» (chunks) ответа, где каждый фрагмент может быть обработан индивидуально сразу после его поступления, вместо ожидания полного ответа.

Синхронная потоковая передача

Эти методы потоковой передачи возвращают 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, см. в разделе Структурированные выходные данные.

Использование инструментов

Использование инструментов с Claude позволяет интегрировать внешние инструменты и функции непосредственно в ответы модели ИИ. Вместо создания обычного текста модель может выводить инструкции (с параметрами) для вызова инструмента или функции, когда это уместно. Вы определяете JSON-схемы для инструментов, и модель использует эти схемы, чтобы определить, когда и как использовать эти инструменты.

Функция использования инструментов поддерживает «строгий» режим, который гарантирует, что JSON-вывод модели ИИ будет соответствовать JSON-схеме, которую вы предоставляете во входных параметрах.

SDK может автоматически выводить инструмент и его параметры из структуры произвольного Java-класса: имя класса (преобразованное в snake case) предоставляет имя инструмента, а поля класса определяют параметры инструмента.

Объявляйте ваши классы инструментов как классы верхнего уровня или вложенные классы со спецификатором static. Это требование исходит от библиотеки Jackson Databind (com.fasterxml.jackson.databind), которую SDK использует для десериализации входных данных инструментов в экземпляры ваших классов и которая не может создавать экземпляры нестатических внутренних классов.

Определение инструментов с помощью аннотаций

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

enum Unit {
  CELSIUS,
  FAHRENHEIT;

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

  public double fromKelvin(double temperatureK) {
    switch (this) {
      case CELSIUS:
        return temperatureK - 273.15;
      case FAHRENHEIT:
      default:
        return (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":
        temperatureK = 300.0;
        break;
      case "New York, NY":
        temperatureK = 310.0;
        break;
      case "Dallas, TX":
        temperatureK = 305.0;
        break;
      default:
        temperatureK = 295;
        break;
    }
    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>), а затем вызовите их, если это запрошено в ответе модели ИИ. BetaToolUseBlock.input(Class<T>) можно использовать для разбора параметров инструмента в формате JSON в экземпляр вашего класса, определяющего инструмент.

После вызова инструмента используйте BetaToolResultBlockParam.Builder.contentAsJson(Object), чтобы передать результат инструмента обратно модели ИИ:

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

Преобразование имён инструментов

Имена инструментов выводятся из имён классов инструментов в camel case (например, GetWeather) и преобразуются в snake case (например, get_weather). Границы слов начинаются там, где текущий символ не является первым символом, является символом верхнего регистра, и либо предшествующий символ является символом нижнего регистра, либо следующий символ является символом нижнего регистра. Например, MyJSONParser становится my_json_parser, а ParseJSON становится parse_json. Это преобразование можно переопределить с помощью аннотации @JsonTypeName.

Локальная валидация JSON-схемы инструмента

Вы можете выполнить локальную валидацию, чтобы проверить, что JSON-схема, выведенная из вашего класса инструмента, соответствует ограничениям Anthropic. Локальная валидация включена по умолчанию, но её можно отключить:

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

Аннотирование классов инструментов

Вы можете использовать аннотации для добавления дополнительной информации об инструментах в JSON-схемы:

@JsonClassDescription — добавить описание к классу инструмента, подробно описывающее, когда и как использовать этот инструмент.
@JsonTypeName — установить имя инструмента, отличное от простого имени класса, преобразованного в snake case.
@JsonPropertyDescription — добавить подробное описание к параметру инструмента.
@JsonIgnore — исключить public поле или метод-геттер из сгенерированной JSON-схемы для параметров инструмента.
@JsonProperty — включить не-public поле или метод-геттер в сгенерированную JSON-схему для параметров инструмента.

Пакеты сообщений

SDK предоставляет поддержку пакетной обработки в пространстве имён client.messages().batches(). См. раздел Пагинация о том, как перечислять пакеты и выполнять пагинацию по ним.

Загрузка файлов

SDK определяет методы, которые принимают файлы через класс MultipartField:

import com.anthropic.core.MultipartField;
import com.anthropic.models.beta.files.FileMetadata;
import com.anthropic.models.beta.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.beta().files().upload(params);

Или из InputStream:

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

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

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

Или из байтов в памяти:

import com.anthropic.core.MultipartField;
import com.anthropic.models.beta.files.FileMetadata;
import com.anthropic.models.beta.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.beta().files().upload(params);

Бинарные ответы

SDK определяет методы, которые возвращают бинарные ответы для ответов API, которые не обязательно разбираются как JSON:

import com.anthropic.core.http.HttpResponse;

HttpResponse response = client.beta().files().download("file_id");

Чтобы сохранить содержимое ответа в файл:

import com.anthropic.core.http.HttpResponse;

try (HttpResponse response = client.beta().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.beta().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 — сетевые ошибки ввода-вывода.
AnthropicRetryableException — общая ошибка, указывающая на сбой, который можно повторить.
AnthropicInvalidDataException — сбой при интерпретации успешно разобранных данных (например, при доступе к свойству, которое должно быть обязательным, но API неожиданно его опустил).
AnthropicException — базовый класс для всех исключений.

Соответствие кодов состояния

Статус	Исключение
400	`BadRequestException`
401	`UnauthorizedException`
403	`PermissionDeniedException`
404	`NotFoundException`
422	`UnprocessableEntityException`
429	`RateLimitException`
5xx	`InternalServerException`
другие	`UnexpectedStatusCodeException`

SseException выбрасывается для ошибок, возникших во время потоковой передачи SSE после успешного начального HTTP-ответа.

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

Идентификаторы запросов

При использовании необработанных ответов вы можете получить доступ к заголовку ответа request-id с помощью метода requestId():

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. Дополнительную информацию об отладке запросов см. в разделе Идентификатор запроса.

Повторные попытки

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, если не переопределено.

Для непотоковых запросов динамический тайм-аут масштабируется от минимума в 30 секунд до максимума в 10 минут на основе maxTokens.

Чтобы установить пользовательский тайм-аут для отдельного запроса:

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, чтобы поддерживать соединение активным и уменьшить влияние таких сетей.

SDK выбрасывает ошибку, если ожидается, что непотоковый запрос займёт более 10 минут. Использование метода потоковой передачи или переопределение тайм-аута на уровне клиента или запроса отключает эту ошибку.

Пагинация

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 имеет связанный строитель (builder) для его создания. Каждый класс является неизменяемым после создания. Если у класса есть связанный строитель, то у него есть метод toBuilder(), который можно использовать для преобразования его обратно в строитель для создания изменённой копии.

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

// Создайте изменённую копию с помощью toBuilder()
MessageCreateParams modified = params.toBuilder().maxTokens(2048L).build();

Поскольку каждый класс является неизменяемым, изменение строителя никогда не повлияет на уже созданные экземпляры класса.

Запросы и ответы

Чтобы отправить запрос к Claude API, создайте экземпляр некоторого класса Params и передайте его соответствующему методу клиента. Когда ответ получен, он десериализуется в экземпляр Java-класса.

Например, client.messages().create(...) должен вызываться с экземпляром MessageCreateParams, и он вернёт экземпляр Message.

Недокументированные параметры

Чтобы установить недокументированные параметры, вызовите методы putAdditionalHeader, putAdditionalQueryParam или putAdditionalBodyProperty на любом классе Params:

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_4_8)
  .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!");

// Создаём значение JSON-массива, эквивалентное `["Hello", "World"]`
JsonValue arrayValue = JsonValue.from(List.of("Hello", "World"));

// Создаём значение JSON-объекта, эквивалентное `{ "a": 1, "b": 2 }`
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)));

Принудительное опускание обязательных параметров

Обычно метод build класса Builder выбрасывает 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_4_8)
  .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);
}

Валидация ответа

По умолчанию SDK не выбрасывает исключение, когда API возвращает ответ, не соответствующий ожидаемому типу. Он выбрасывает 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 состоит из трёх артефактов:

anthropic-java-core — содержит основную логику SDK, не зависит от OkHttp. Предоставляет AnthropicClient, AnthropicClientAsync и их классы реализации, все из которых могут работать с любым HTTP-клиентом.
anthropic-java-client-okhttp — зависит от OkHttp. Предоставляет AnthropicOkHttpClient и AnthropicOkHttpClientAsync.
anthropic-java — зависит от API обоих артефактов anthropic-java-core и anthropic-java-client-okhttp и предоставляет их. Не имеет собственной логики.

Эта структура позволяет заменить HTTP-клиент SDK по умолчанию без подключения ненужных зависимостей.

Настроенный OkHttpClient

Попробуйте доступные сетевые параметры, прежде чем заменять клиент по умолчанию.

Чтобы использовать настроенный OkHttpClient:

Замените вашу зависимость anthropic-java на anthropic-java-core.
Скопируйте класс OkHttpClient из anthropic-java-client-okhttp в ваш код и настройте его.
Создайте AnthropicClientImpl или AnthropicClientAsyncImpl, используя ваш настроенный клиент.

Полностью пользовательский HTTP-клиент

Чтобы использовать полностью пользовательский HTTP-клиент:

Замените вашу зависимость anthropic-java на anthropic-java-core.
Напишите класс, реализующий интерфейс HttpClient.
Создайте AnthropicClientImpl или AnthropicClientAsyncImpl, используя ваш новый класс клиента.

Интеграции с платформами

Подробные руководства по настройке платформ с примерами кода см. в разделах:

Java SDK поддерживает следующие платформы через отдельные зависимости, которые предоставляют специфичные для платформы реализации Backend:

Bedrock: com.anthropic:anthropic-java-bedrock: используйте BedrockMantleBackend.fromEnv() или BedrockMantleBackend.builder() для конечной точки Bedrock с Messages API, либо BedrockBackend.fromEnv() / BedrockBackend.builder() (путь bedrock-runtime).
Vertex AI: com.anthropic:anthropic-java-vertex: используйте VertexBackend.fromEnv() или VertexBackend.builder().
Foundry: com.anthropic:anthropic-java-foundry: используйте FoundryBackend.fromEnv() или FoundryBackend.builder().
Claude Platform на AWS: com.anthropic:anthropic-java-aws: используйте (считывает и цепочку регионов/учётных данных AWS по умолчанию) или . Доступно в бета-версии.

Используйте BedrockMantleBackend для новых проектов; BedrockBackend остаётся для существующих приложений, использующих Bedrock InvokeModel API.

Каждая реализация Backend передаётся клиенту с помощью .backend() на AnthropicOkHttpClient.builder(). Каждый облачный бэкенд подключает соответствующие классы SDK облачной платформы как транзитивные зависимости.

Расширенное использование

Доступ к необработанному ответу

Чтобы получить доступ к HTTP-заголовкам, кодам состояния и необработанному телу ответа, добавьте префикс withRawResponse() к любому вызову HTTP-метода:

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_4_8)
  .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(), как описано в разделе Свойства ответа.

Новые или невыпущенные значения перечислений

Классы, подобные перечислениям, в SDK, такие как Model и AnthropicBeta, не являются закрытыми типами 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");

Методы строителя, которые принимают эти типы, часто также предоставляют перегрузку 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_4_7), чтобы получать автодополнение и предупреждения об устаревании. Перегрузки String и of(...) предназначены в первую очередь для установки поля в недокументированное или ещё не поддерживаемое значение в ожидании выпуска SDK, который его включает.

Бета-функции

Бета-функции доступны до общего выпуска для получения ранней обратной связи и тестирования новой функциональности. Вы можете проверить доступность всех возможностей и инструментов Claude в обзоре разработки с Claude.

Вы можете получить доступ к большинству бета-функций API через метод beta() на клиенте. Чтобы включить конкретную бета-функцию, добавьте соответствующий бета-заголовок с помощью .addBeta() при создании параметров сообщения.

Например, чтобы использовать Files API:

import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.beta.messages.BetaContentBlockParam;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaRequestDocumentBlock;
import com.anthropic.models.beta.messages.BetaTextBlockParam;
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_4_8)
            .maxTokens(1024L)
            .addBeta(AnthropicBeta.FILES_API_2025_04_14)
            .addUserMessageOfBetaContentBlockParams(List.of(
                BetaContentBlockParam.ofText(
                    BetaTextBlockParam.builder()
                        .text("Please summarize this document for me.")
                        .build()),
                BetaContentBlockParam.ofDocument(
                    BetaRequestDocumentBlock.builder()
                        .fileSource("file_abc123")
                        .build())))
            .build());
}

Часто задаваемые вопросы

Семантическое версионирование

Этот пакет в целом следует соглашениям SemVer, хотя некоторые обратно несовместимые изменения могут быть выпущены как минорные версии:

Изменения во внутренних компонентах библиотеки, которые технически являются публичными, но не предназначены или не документированы для внешнего использования.
Изменения, которые, как ожидается, не повлияют на подавляющее большинство пользователей на практике.

Дополнительные ресурсы

AwsBackend.fromEnv()

ANTHROPIC_AWS_WORKSPACE_ID

AwsBackend.builder()

Установка

Требования

Быстрый старт

Настройка клиента

Настройка ключа API

Параметры конфигурации

Изменение конфигурации

Асинхронное использование

Потоковая передача

Синхронная потоковая передача

Асинхронная потоковая передача

Потоковая передача с аккумулятором сообщений

Структурированные выходные данные

Использование инструментов

Определение инструментов с помощью аннотаций

Вызов инструментов

Преобразование имён инструментов

Локальная валидация JSON-схемы инструмента

Аннотирование классов инструментов

Пакеты сообщений

Загрузка файлов

Бинарные ответы

Обработка ошибок

Соответствие кодов состояния

Идентификаторы запросов

Повторные попытки

Тайм-ауты

Длительные запросы

Пагинация

Автоматическая пагинация

Ручная пагинация

Система типов

Неизменяемость и строители

Запросы и ответы

Недокументированные параметры

Создание JsonValue

Принудительное опускание обязательных параметров

Свойства ответа

Валидация ответа

Настройка HTTP-клиента

Настройка прокси

Настройка HTTPS / SSL

Пользовательский HTTP-клиент

Настроенный OkHttpClient

Полностью пользовательский HTTP-клиент

Интеграции с платформами

Расширенное использование

Доступ к необработанному ответу

Логирование

Совместимость с Jackson

Конфигурация ProGuard/R8

Недокументированная функциональность API

Недокументированные параметры запроса

Недокументированные свойства ответа

Новые или невыпущенные значения перечислений

Бета-функции

Часто задаваемые вопросы

Почему SDK не использует обычные классы enum?

Почему поля представлены с помощью JsonField<T> вместо просто T?

Почему SDK не использует data-классы?

Почему SDK не использует проверяемые исключения?

Семантическое версионирование

Дополнительные ресурсы