SDK Java

Instale e configure o SDK Java da Anthropic com padrões builder e suporte assíncrono

O SDK Java da Anthropic fornece acesso conveniente à Claude API a partir de aplicações escritas em Java. Ele usa o "builder pattern" (padrão builder) para criar requisições e suporta operações síncronas e assíncronas.

Instalação

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

Requisitos

Esta biblioteca requer Java 8 ou posterior.

Início rápido

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;

// Configura usando as propriedades de sistema `anthropic.apiKey`, `anthropic.authToken` e `anthropic.baseUrl`
// Ou configura usando as variáveis de ambiente `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` e `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);

Configuração do cliente

Configuração da chave de API

Configure o cliente usando propriedades do sistema ou variáveis de ambiente:

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

// Configura usando as propriedades de sistema `anthropic.apiKey`, `anthropic.authToken` e `anthropic.baseUrl`
// Ou configura usando as variáveis de ambiente `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` e `ANTHROPIC_BASE_URL`
AnthropicClient client = AnthropicOkHttpClient.fromEnv();

Ou configure manualmente:

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

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

Ou use uma combinação de ambas as abordagens:

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

AnthropicClient client = AnthropicOkHttpClient.builder()
  // Configura usando propriedades do sistema ou variáveis de ambiente
  .fromEnv()
  .apiKey("my-anthropic-api-key")
  .build();

Para opções de autenticação, incluindo Workload Identity Federation, consulte Autenticação. Se sua chave de API for uma chave pessoal ou de conta de serviço com acesso a vários workspaces, defina o ID do workspace no cabeçalho de requisição anthropic-workspace-id; Selecionar um workspace mostra a opção por requisição para este SDK.

Opções de configuração

Setter	Propriedade do sistema	Variável de ambiente	Obrigatório	Valor padrão
`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"`

As propriedades do sistema têm precedência sobre as variáveis de ambiente.

Modificando a configuração

Para usar temporariamente uma configuração de cliente modificada, reutilizando os mesmos pools de conexões e threads, chame withOptions() em qualquer cliente ou serviço:

import com.anthropic.client.AnthropicClient;

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

O método withOptions() não afeta o cliente ou serviço original.

Uso assíncrono

O cliente padrão é síncrono. Para alternar para execução assíncrona, chame o método 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);

Ou crie um cliente assíncrono desde o início:

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

O cliente assíncrono suporta as mesmas opções que o síncrono, exceto que a maioria dos métodos retorna CompletableFutures.

Streaming

O SDK define métodos que retornam streams de "chunks" (fragmentos) de resposta, onde cada chunk pode ser processado individualmente assim que chega, em vez de aguardar a resposta completa.

Streaming síncrono

Estes métodos de streaming retornam StreamResponse para clientes síncronos:

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

Streaming assíncrono

Para clientes assíncronos, o método retorna AsyncStreamResponse:

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

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

// Se você precisar tratar erros ou a conclusão do stream
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!");
        }
    }
});

// Ou use 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!");
        }
    });

O streaming assíncrono usa um Executor dedicado de pool de threads em cache por cliente para fazer streaming sem bloquear a thread atual. Para usar um Executor diferente:

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

Ou configure o cliente globalmente usando o método streamHandlerExecutor:

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

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

Streaming com acumulador de mensagens

Um MessageAccumulator pode registrar o stream de eventos na resposta à medida que são processados e acumular um objeto Message semelhante ao que teria sido retornado pela API sem streaming.

Para uma resposta síncrona, adicione uma chamada Stream.peek() ao pipeline do stream para acumular cada evento:

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

Para uma resposta assíncrona, adicione o MessageAccumulator à chamada 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();

Um BetaMessageAccumulator também está disponível para a acumulação de um objeto BetaMessage. Ele é usado da mesma maneira que o MessageAccumulator.

Saídas estruturadas

Para a documentação completa de "structured outputs" (saídas estruturadas), incluindo exemplos em Java, consulte Saídas estruturadas.

Uso de ferramentas

O uso de ferramentas com Claude ("tool use") permite integrar ferramentas e funções externas diretamente nas respostas do modelo de IA. Em vez de produzir texto simples, o modelo pode gerar instruções (com parâmetros) para chamar uma ferramenta ou função quando apropriado. Você define esquemas JSON para as ferramentas, e o modelo usa os esquemas para determinar quando e como usar essas ferramentas.

O recurso de uso de ferramentas suporta um modo "strict" (estrito) que garante que a saída JSON do modelo de IA estará em conformidade com o esquema JSON que você fornece nos parâmetros de entrada.

O SDK pode derivar uma ferramenta e seus parâmetros automaticamente a partir da estrutura de uma classe Java arbitrária: o nome da classe (convertido para snake case) fornece o nome da ferramenta, e os campos da classe definem os parâmetros da ferramenta.

Definindo ferramentas com anotações

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

Chamando ferramentas

Quando suas classes de ferramentas estiverem definidas, adicione-as aos parâmetros da mensagem usando MessageCreateParams.Builder.addTool(Class<T>) e então chame-as se isso for solicitado na resposta do modelo de IA. BetaToolUseBlock.input(Class<T>) pode ser usado para converter os parâmetros de uma ferramenta em formato JSON para uma instância da sua classe que define a ferramenta.

Após chamar a ferramenta, use BetaToolResultBlockParam.Builder.contentAsJson(Object) para passar o resultado da ferramenta de volta ao modelo de IA:

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
              // Adiciona uma mensagem indicando que o uso de ferramentas foi solicitado.
              .addAssistantMessageOfBetaContentBlockParams(
                      List.of(BetaContentBlockParam.ofToolUse(BetaToolUseBlockParam.builder()
                              .name(toolUseBlock.name())
                              .id(toolUseBlock.id())
                              .input(toolUseBlock._input())
                              .build())))
              // Adiciona uma mensagem com o resultado do uso de ferramentas solicitado.
              .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");
}

Conversão de nomes de ferramentas

Os nomes das ferramentas são derivados dos nomes das classes de ferramentas em camel case (por exemplo, GetWeather) e convertidos para snake case (por exemplo, get_weather). Os limites de palavras começam onde o caractere atual não é o primeiro caractere, é maiúsculo e o caractere anterior é minúsculo ou o caractere seguinte é minúsculo. Por exemplo, MyJSONParser torna-se my_json_parser e ParseJSON torna-se parse_json. Esta conversão pode ser sobrescrita usando a anotação @JsonTypeName.

Validação local do esquema JSON de ferramentas

Você pode realizar validação local para verificar se o esquema JSON derivado da sua classe de ferramenta respeita as restrições da Anthropic. A validação local é habilitada por padrão, mas pode ser desabilitada:

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

Anotando classes de ferramentas

Você pode usar anotações para adicionar mais informações sobre as ferramentas aos esquemas JSON:

@JsonClassDescription - Adiciona uma descrição a uma classe de ferramenta detalhando quando e como usar essa ferramenta.
@JsonTypeName - Define o nome da ferramenta como algo diferente do nome simples da classe convertido para snake case.
@JsonPropertyDescription - Adiciona uma descrição detalhada a um parâmetro de ferramenta.
@JsonIgnore - Exclui um campo public ou método getter do esquema JSON gerado para os parâmetros de uma ferramenta.
@JsonProperty - Inclui um campo ou método getter não public no esquema JSON gerado para os parâmetros de uma ferramenta.

Lotes de mensagens

O SDK fornece suporte para processamento em lote no namespace client.messages().batches(). Consulte Paginação para saber como listar e paginar pelos lotes.

Upload de arquivos

O SDK define métodos que aceitam arquivos por meio da classe 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);

Ou a partir de um 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);

Ou a partir de bytes em memória:

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

Respostas binárias

O SDK define métodos que retornam respostas binárias para respostas da API que não são necessariamente interpretadas como JSON:

import com.anthropic.core.http.HttpResponse;

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

Para salvar o conteúdo da resposta em um arquivo:

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

Ou transferir o conteúdo da resposta para qualquer 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);
}

Tratamento de erros

O SDK lança tipos de exceção personalizados não verificados (unchecked):

AnthropicServiceException - Classe base para erros HTTP.
AnthropicIoException - Erros de rede de E/S.
AnthropicRetryableException - Erro genérico indicando uma falha que pode ser tentada novamente.
AnthropicInvalidDataException - Falha ao interpretar dados analisados com sucesso (por exemplo, ao acessar uma propriedade que deveria ser obrigatória, mas que a API omitiu inesperadamente).
AnthropicException - Classe base para todas as exceções.

Mapeamento de códigos de status

Status	Exceção
400	`BadRequestException`
401	`UnauthorizedException`
403	`PermissionDeniedException`
404	`NotFoundException`
422	`UnprocessableEntityException`
429	`RateLimitException`
5xx	`InternalServerException`
outros	`UnexpectedStatusCodeException`

SseException é lançada para erros encontrados durante o streaming SSE após uma resposta HTTP inicial bem-sucedida.

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

IDs de requisição

Ao usar respostas brutas, você pode acessar o cabeçalho de resposta request-id usando o método 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();

Isso pode ser usado para registrar rapidamente requisições com falha e reportá-las à Anthropic. Para mais informações sobre depuração de requisições, consulte ID de requisição.

Novas tentativas

O SDK tenta novamente automaticamente 2 vezes por padrão, com um curto backoff exponencial entre as requisições.

Apenas os seguintes tipos de erro são tentados novamente:

Erros de conexão (por exemplo, devido a um problema de conectividade de rede)
408 Request Timeout
409 Conflict
429 Rate Limit
5xx Internal

A API também pode instruir explicitamente o SDK a tentar ou não tentar novamente uma requisição.

Para definir um número personalizado de novas tentativas, configure o cliente usando o método maxRetries:

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

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

Timeouts

As requisições expiram após 10 minutos por padrão.

No entanto, para métodos que aceitam maxTokens, se você especificar um valor grande de maxTokens e estiver usando streaming, o timeout padrão será calculado dinamicamente usando esta fórmula:

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

Isso resulta em um timeout de até 60 minutos, escalonado pelo parâmetro maxTokens, a menos que seja sobrescrito.

Para requisições sem streaming, o timeout dinâmico escala de um mínimo de 30 segundos até um máximo de 10 minutos com base em maxTokens.

Para definir um timeout personalizado por requisição:

import com.anthropic.models.messages.Message;

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

Ou configure o padrão para todas as chamadas de método no nível do cliente:

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

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

Requisições longas

Evite definir um valor grande de maxTokens sem usar streaming. Algumas redes podem descartar conexões ociosas após um certo período de tempo, o que pode fazer com que a requisição falhe ou atinja o timeout sem receber uma resposta da Anthropic. O SDK envia pings periodicamente à API para manter a conexão ativa e reduzir o impacto dessas redes.

O SDK lança um erro se uma requisição sem streaming tiver previsão de levar mais de 10 minutos. Usar um método de streaming ou sobrescrever o timeout no nível do cliente ou da requisição desabilita o erro.

Paginação

O SDK fornece maneiras convenientes de acessar resultados paginados, seja uma página por vez ou item por item em todas as páginas.

Paginação automática

Para iterar por todos os resultados em todas as páginas, use o método autoPager(), que busca automaticamente mais páginas conforme necessário.

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

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

// Processar como um Iterable
for (MessageBatch batch : page.autoPager()) {
    IO.println(batch);
}

// Processar como um Stream
page.autoPager()
    .stream()
    .limit(50)
    .forEach(batch -> IO.println(batch));

Ao usar o cliente assíncrono, o método retorna um 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);
}));

// Se você precisar tratar erros ou a conclusão do stream
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!");
        }
    }
}));

// Ou use 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!");
        }
    }));

Paginação manual

Para acessar itens de páginas individuais e solicitar manualmente a próxima página:

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

Sistema de tipos

Imutabilidade e builders

Cada classe no SDK possui um builder associado para construí-la. Cada classe é imutável após ser construída. Se a classe possui um builder associado, então ela tem um método toBuilder(), que pode ser usado para convertê-la de volta em um builder para criar uma cópia modificada.

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

// Criar uma cópia modificada usando toBuilder()
MessageCreateParams modified = params.toBuilder().maxTokens(2048L).build();

Como cada classe é imutável, a modificação do builder nunca afeta instâncias de classe já construídas.

Requisições e respostas

Para enviar uma requisição à Claude API, construa uma instância de alguma classe Params e passe-a ao método correspondente do cliente. Quando a resposta é recebida, ela é desserializada em uma instância de uma classe Java.

Por exemplo, client.messages().create(...) deve ser chamado com uma instância de MessageCreateParams, e retorna uma instância de Message.

Parâmetros não documentados

Para definir parâmetros não documentados, chame os métodos putAdditionalHeader, putAdditionalQueryParam ou putAdditionalBodyProperty em qualquer classe 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();

Eles podem ser acessados posteriormente no objeto construído usando os métodos _additionalHeaders(), _additionalQueryParams() e _additionalBodyProperties().

Para definir parâmetros não documentados em classes aninhadas de cabeçalhos, parâmetros de consulta ou corpo:

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

Essas propriedades podem ser acessadas posteriormente no objeto aninhado construído usando o método _additionalProperties().

Para definir um parâmetro ou propriedade documentada com um valor não documentado ou ainda não suportado, passe um objeto JsonValue ao seu 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)
  .build();

Criação de JsonValue

A maneira mais direta de criar um JsonValue é usando seu método from(...):

import com.anthropic.core.JsonValue;

// Criar valores JSON primitivos
JsonValue nullValue = JsonValue.from(null);

JsonValue booleanValue = JsonValue.from(true);

JsonValue numberValue = JsonValue.from(42);

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

// Criar um valor de array JSON equivalente a `["Hello", "World"]`
JsonValue arrayValue = JsonValue.from(List.of("Hello", "World"));

// Criar um valor de objeto JSON equivalente a `{ "a": 1, "b": 2 }`
JsonValue objectValue = JsonValue.from(Map.of("a", 1, "b", 2));

// Criar um JSON aninhado arbitrariamente equivalente a:
// { "a": [1, 2], "b": [3, 4] }
JsonValue complexValue = JsonValue.from(Map.of("a", List.of(1, 2), "b", List.of(3, 4)));

Omitindo forçadamente parâmetros obrigatórios

Normalmente, o método build de uma classe Builder lançará IllegalStateException se algum parâmetro ou propriedade obrigatória não estiver definido. Para omitir forçadamente um parâmetro ou propriedade obrigatória, passe 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();

Propriedades de resposta

Para acessar propriedades de resposta não documentadas, chame o método _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!";
    }

    // Outros métodos incluem `visitMissing`, `visitString`, `visitArray` e `visitObject`
    // A implementação padrão de cada método não implementado delega para `visitDefault`,
    // que lança uma exceção por padrão, mas também pode ser sobrescrito
});

Para acessar o valor JSON bruto de uma propriedade, chame seu método com prefixo _:

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

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

if (stopReason.isMissing()) {
  // A propriedade está ausente da resposta JSON
} else if (stopReason.isNull()) {
  // A propriedade foi definida como null literal
} else {
  // Verifica se o valor foi fornecido como uma string
  // Outros métodos incluem `asNumber()`, `asBoolean()`, etc.
  Optional<String> jsonString = stopReason.asString();

  // Tenta desserializar em um tipo personalizado
  MyClass myObject = stopReason.asUnknown().orElseThrow().convert(MyClass.class);
}

Validação de resposta

Por padrão, o SDK não lança uma exceção quando a API retorna uma resposta que não corresponde ao tipo esperado. Ele lança AnthropicInvalidDataException apenas se você acessar diretamente a propriedade.

Para verificar antecipadamente se a resposta está completamente bem tipada, chame validate():

import com.anthropic.models.messages.Message;

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

Ou configure por requisição:

import com.anthropic.models.messages.Message;

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

Ou configure o padrão para todas as chamadas de método no nível do cliente:

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

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

Personalização do cliente HTTP

Configuração de 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();

Configuração de 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();

Cliente HTTP personalizado

O SDK consiste em três artefatos:

anthropic-java-core - Contém a lógica central do SDK, não depende do OkHttp. Expõe AnthropicClient, AnthropicClientAsync e suas classes de implementação, todas as quais podem funcionar com qualquer cliente HTTP.
anthropic-java-client-okhttp - Depende do OkHttp. Expõe AnthropicOkHttpClient e AnthropicOkHttpClientAsync.
anthropic-java - Depende e expõe as APIs de anthropic-java-core e anthropic-java-client-okhttp. Não possui lógica própria.

Essa estrutura permite substituir o cliente HTTP padrão do SDK sem incluir dependências desnecessárias.

OkHttpClient personalizado

Para usar um OkHttpClient personalizado:

Substitua sua dependência anthropic-java por anthropic-java-core.
Copie a classe OkHttpClient de anthropic-java-client-okhttp para o seu código e personalize-a.
Construa AnthropicClientImpl ou AnthropicClientAsyncImpl usando seu cliente personalizado.

Cliente HTTP totalmente personalizado

Para usar um cliente HTTP totalmente personalizado:

Substitua sua dependência anthropic-java por anthropic-java-core.
Escreva uma classe que implemente a interface HttpClient.
Construa AnthropicClientImpl ou AnthropicClientAsyncImpl usando sua nova classe de cliente.

Integrações com plataformas

O SDK Java suporta as seguintes plataformas por meio de dependências separadas que fornecem implementações de Backend específicas para cada plataforma:

Agent Platform: com.anthropic:anthropic-java-vertex: Use VertexBackend.fromEnv() ou VertexBackend.builder().
Bedrock: com.anthropic:anthropic-java-bedrock: Use BedrockMantleBackend.fromEnv() ou BedrockMantleBackend.builder() para o endpoint Bedrock da Messages API, ou BedrockBackend.fromEnv() / BedrockBackend.builder() (caminho bedrock-runtime).
Claude Platform on AWS: com.anthropic:anthropic-java-aws: Use AwsBackend.fromEnv() (lê ANTHROPIC_AWS_WORKSPACE_ID e a cadeia padrão de região/credenciais da AWS) ou AwsBackend.builder(). Disponível em beta.
Foundry: com.anthropic:anthropic-java-foundry: Use FoundryBackend.fromEnv() ou FoundryBackend.builder().

Use BedrockMantleBackend para novos projetos; BedrockBackend permanece para aplicações existentes que usam a API InvokeModel do Bedrock.

Cada implementação de Backend é passada ao cliente com .backend() em AnthropicOkHttpClient.builder(). Cada backend de nuvem inclui as respectivas classes do SDK da plataforma de nuvem como dependências transitivas.

Uso avançado

Acesso à resposta bruta

Para acessar cabeçalhos HTTP, códigos de status e o corpo bruto da resposta, prefixe qualquer chamada de método HTTP com withRawResponse():

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

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

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

int statusCode = message.statusCode();

Headers headers = message.headers();

Você ainda pode desserializar a resposta em uma instância de uma classe Java, se necessário:

import com.anthropic.models.messages.Message;

Message parsedMessage = message.parse();

Logging

O SDK usa o interceptor de logging padrão do OkHttp.

Habilite o logging definindo a variável de ambiente ANTHROPIC_LOG como info:

export ANTHROPIC_LOG=info

Ou como debug para um logging mais detalhado:

export ANTHROPIC_LOG=debug

Funcionalidade não documentada da API

O SDK é tipado para uso conveniente da API documentada. No entanto, ele também suporta trabalhar com partes não documentadas ou ainda não suportadas da API.

Parâmetros de requisição não documentados

Para definir parâmetros de requisição não documentados, use os métodos putAdditionalHeader, putAdditionalQueryParam ou putAdditionalBodyProperty conforme descrito em Parâmetros não documentados.

Propriedades de resposta não documentadas

Para acessar propriedades de resposta não documentadas, use o método _additionalProperties() conforme descrito em Propriedades de resposta.

Valores de enum novos ou não lançados

Classes semelhantes a enum no SDK, como Model e AnthropicBeta, não são tipos enum fechados do Java. Cada uma fornece um método de fábrica of(String) que aceita qualquer string, para que você possa usar valores que ainda não foram adicionados ao SDK, como um modelo ou cabeçalho beta lançado após a sua versão do 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");

Os métodos de builder que recebem esses tipos frequentemente também fornecem uma sobrecarga String que chama of(...) para você:

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

Prefira as constantes bem tipadas (por exemplo, Model.CLAUDE_OPUS_5) para obter autocompletar e avisos de descontinuação. As sobrecargas String e of(...) servem principalmente para definir o campo com um valor não documentado ou ainda não suportado enquanto se aguarda uma versão do SDK que o inclua.

Recursos beta

Os recursos beta estão disponíveis antes do lançamento geral para obter feedback antecipado e testar novas funcionalidades. Você pode verificar a disponibilidade de todas as capacidades e ferramentas do Claude na visão geral de construir com Claude.

Você pode acessar a maioria dos recursos beta da API por meio do método beta() no cliente. Para habilitar um recurso beta específico, adicione o cabeçalho beta apropriado com .addBeta() ao construir os parâmetros da mensagem.

Por exemplo, para habilitar a edição de contexto:

import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.MessageCreateParams;
// ...
void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

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

Perguntas frequentes

Versionamento semântico

Este pacote geralmente segue as convenções do SemVer, embora certas mudanças incompatíveis com versões anteriores possam ser lançadas como versões menores:

Mudanças em partes internas da biblioteca que são tecnicamente públicas, mas não destinadas ou documentadas para uso externo.
Mudanças que não devem impactar a grande maioria dos usuários na prática.

Instalação

Requisitos

Início rápido

Configuração do cliente

Configuração da chave de API

Opções de configuração

Modificando a configuração

Uso assíncrono

Streaming

Streaming síncrono

Streaming assíncrono

Streaming com acumulador de mensagens

Saídas estruturadas

Uso de ferramentas

Definindo ferramentas com anotações

Chamando ferramentas

Conversão de nomes de ferramentas

Validação local do esquema JSON de ferramentas

Anotando classes de ferramentas

Lotes de mensagens

Upload de arquivos

Respostas binárias

Tratamento de erros

Mapeamento de códigos de status

IDs de requisição

Novas tentativas

Timeouts

Requisições longas

Paginação

Paginação automática

Paginação manual

Sistema de tipos

Imutabilidade e builders

Requisições e respostas

Parâmetros não documentados

Criação de JsonValue

Omitindo forçadamente parâmetros obrigatórios

Propriedades de resposta

Validação de resposta

Personalização do cliente HTTP

Configuração de proxy

Configuração de HTTPS / SSL

Cliente HTTP personalizado

OkHttpClient personalizado

Cliente HTTP totalmente personalizado

Integrações com plataformas

Uso avançado

Acesso à resposta bruta

Logging

Compatibilidade com Jackson

Configuração do ProGuard/R8

Funcionalidade não documentada da API

Parâmetros de requisição não documentados

Propriedades de resposta não documentadas

Valores de enum novos ou não lançados

Recursos beta

Perguntas frequentes

Por que o SDK não usa classes enum simples?

Por que os campos são representados usando JsonField<T> em vez de simplesmente T?

Por que o SDK não usa data classes?

Por que o SDK não usa exceções verificadas (checked exceptions)?

Versionamento semântico

Recursos adicionais