CLI, SDK и библиотекиКлиентские SDK

Java SDK

Установите и настройте Anthropic Java SDK с паттернами builder и поддержкой асинхронности

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

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

Установка

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

Требования

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

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

Сеттер	Системное свойство	Переменная окружения	Обязательно	Значение по умолчанию
`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)
  .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 определяет методы, которые возвращают потоки «чанков» (chunk) ответа, где каждый чанк может быть обработан индивидуально сразу после его получения, вместо ожидания полного ответа.

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

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

Функция использования инструментов поддерживает «строгий» (strict) режим, который гарантирует, что 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() {
    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>), а затем вызовите их, если это запрошено в ответе модели ИИ. 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_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");
}

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

Имена инструментов выводятся из имён классов инструментов в 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_5)
  .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(URI.create("https://example.com/path/to/file").toURL().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_abc123");

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

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

Для непотоковых запросов динамический тайм-аут масштабируется от минимума в 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 периодически пингует 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();
}

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

Неизменяемость и builder'ы

Каждый класс в SDK имеет связанный builder для его конструирования. Каждый класс неизменяем после создания. Если у класса есть связанный builder, то у него есть метод toBuilder(), который можно использовать для преобразования его обратно в builder для создания изменённой копии.

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

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

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

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

Чтобы отправить запрос к 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_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!");

// Создание значения массива 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_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);
}

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

По умолчанию 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:

Agent Platform: com.anthropic:anthropic-java-vertex: Используйте VertexBackend.fromEnv() или VertexBackend.builder().
Bedrock: com.anthropic:anthropic-java-bedrock: Используйте BedrockMantleBackend.fromEnv() или BedrockMantleBackend.builder() для конечной точки Bedrock с Messages API, либо BedrockBackend.fromEnv() / BedrockBackend.builder() (путь bedrock-runtime).
Claude Platform на 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 остаётся для существующих приложений, использующих API Bedrock InvokeModel.

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

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

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

Методы builder'а, принимающие эти типы, часто также предоставляют перегрузку со 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, который его включает.

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

Бета-функции доступны до общего выпуска, чтобы получить ранние отзывы и протестировать новую функциональность. Вы можете проверить доступность всех возможностей и инструментов 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_5)
            .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, хотя некоторые обратно несовместимые изменения могут быть выпущены как минорные версии:

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

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

Was this page helpful?

Установка

Требования

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

Конфигурация клиента

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Тайм-ауты

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

Пагинация

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

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

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

Неизменяемость и builder'ы

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

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

Создание JsonValue

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

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

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

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

Конфигурация прокси

Конфигурация HTTPS / SSL

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

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

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

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

Продвинутое использование

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

Логирование

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Установка

Требования

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

Конфигурация клиента

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Тайм-ауты

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

Пагинация

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

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

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

Неизменяемость и builder'ы

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

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

Создание JsonValue

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

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

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

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

Конфигурация прокси

Конфигурация HTTPS / SSL

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

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

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

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

Продвинутое использование

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

Логирование

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

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

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

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

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

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

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

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