CLI, SDK e librerieSDK client

SDK Java

Installa e configura l'SDK Java di Anthropic con pattern builder e supporto asincrono

L'SDK Java di Anthropic fornisce un accesso pratico alla REST API di Anthropic da applicazioni scritte in Java. Utilizza il pattern builder per creare le richieste e supporta operazioni sia sincrone che asincrone.

Per la documentazione delle funzionalità API con esempi di codice, consulta il riferimento API. Questa pagina tratta le funzionalità e la configurazione dell'SDK specifiche per Java.

Installazione

Requisiti

Questa libreria richiede Java 8 o versioni successive.

L'SDK supporta Java 8 e versioni successive. Gli esempi di codice in questa documentazione sono scritti come file sorgente compatti JDK 25, utilizzando un punto di ingresso void main() semplice e IO.println() per l'output. Le chiamate API stesse sono identiche su ogni JDK supportato; per compilare un esempio su una versione precedente, sostituisci IO.println(...) con System.out.println(...) e inserisci il corpo all'interno di public static void main(String[] args) dentro una classe.

Avvio rapido

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 le proprietà di sistema `anthropic.apiKey`, `anthropic.authToken` e `anthropic.baseUrl`
// Oppure configura usando le variabili d'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_4_8)
  .build();

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

Configurazione del client

Configurazione della chiave API

Configura il client utilizzando le proprietà di sistema o le variabili d'ambiente:

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

// Configura usando le proprietà di sistema `anthropic.apiKey`, `anthropic.authToken` e `anthropic.baseUrl`
// Oppure configura usando le variabili d'ambiente `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` e `ANTHROPIC_BASE_URL`
AnthropicClient client = AnthropicOkHttpClient.fromEnv();

Oppure configura manualmente:

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

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

Oppure usa una combinazione di entrambi gli approcci:

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

AnthropicClient client = AnthropicOkHttpClient.builder()
  // Configura usando proprietà di sistema o variabili d'ambiente
  .fromEnv()
  .apiKey("my-anthropic-api-key")
  .build();

Per le opzioni di autenticazione, inclusa la Workload Identity Federation, consulta Autenticazione.

Opzioni di configurazione

Setter	Proprietà di sistema	Variabile d'ambiente	Obbligatorio	Valore predefinito
`apiKey`	`anthropic.apiKey`	`ANTHROPIC_API_KEY`	false	-
`authToken`	`anthropic.authToken`	`ANTHROPIC_AUTH_TOKEN`	false	-
`baseUrl`	`anthropic.baseUrl`	`ANTHROPIC_BASE_URL`	true

Le proprietà di sistema hanno la precedenza sulle variabili d'ambiente.

Non creare più di un client nella stessa applicazione. Ogni client ha un pool di connessioni e pool di thread, che sono più efficienti se condivisi tra le richieste.

Modifica della configurazione

Per utilizzare temporaneamente una configurazione del client modificata riutilizzando gli stessi pool di connessioni e thread, chiama withOptions() su qualsiasi client o servizio:

import com.anthropic.client.AnthropicClient;

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

Il metodo withOptions() non influisce sul client o servizio originale.

Utilizzo asincrono

Il client predefinito è sincrono. Per passare all'esecuzione asincrona, chiama il metodo 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);

Oppure crea un client asincrono fin dall'inizio:

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

Il client asincrono supporta le stesse opzioni di quello sincrono, tranne che la maggior parte dei metodi restituisce CompletableFuture.

Streaming

L'SDK definisce metodi che restituiscono stream di "chunk" di risposta, dove ogni chunk può essere elaborato individualmente non appena arriva invece di attendere la risposta completa.

Streaming sincrono

Questi metodi di streaming restituiscono StreamResponse per i client sincroni:

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 asincrono

Per i client asincroni, il metodo restituisce AsyncStreamResponse:

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

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

// Se devi gestire errori o il completamento dello 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!");
        }
    }
});

// Oppure usa i future
client.async().messages().createStreaming(params)
    .subscribe(chunk -> {
        IO.println(chunk);
    })
    .onCompleteFuture()
    .whenComplete((unused, error) -> {
        if (error != null) {
            IO.println("Something went wrong!");
            throw new RuntimeException(error);
        } else {
            IO.println("No more chunks!");
        }
    });

Lo streaming asincrono utilizza un Executor dedicato con pool di thread in cache per ogni client per eseguire lo streaming senza bloccare il thread corrente. Per utilizzare un Executor diverso:

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

Oppure configura il client globalmente utilizzando il metodo streamHandlerExecutor:

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

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

Streaming con accumulatore di messaggi

Un MessageAccumulator può registrare lo stream di eventi nella risposta mentre vengono elaborati e accumulare un oggetto Message simile a quello che sarebbe stato restituito dall'API non in streaming.

Per una risposta sincrona, aggiungi una chiamata Stream.peek() alla pipeline dello stream per accumulare ogni 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();

Per una risposta asincrona, aggiungi il MessageAccumulator alla chiamata 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();

È disponibile anche un BetaMessageAccumulator per l'accumulo di un oggetto BetaMessage. Viene utilizzato nello stesso modo del MessageAccumulator.

Output strutturati

Per la documentazione completa sugli output strutturati, inclusi esempi Java, consulta Output strutturati.

Uso degli strumenti

L'uso degli strumenti con Claude ti consente di integrare strumenti e funzioni esterni direttamente nelle risposte del modello di IA. Invece di produrre testo semplice, il modello può generare istruzioni (con parametri) per chiamare uno strumento o una funzione quando appropriato. Definisci schemi JSON per gli strumenti e il modello utilizza gli schemi per determinare quando e come utilizzare questi strumenti.

La funzionalità di uso degli strumenti supporta una modalità "strict" che garantisce che l'output JSON del modello di IA sia conforme allo schema JSON fornito nei parametri di input.

L'SDK può derivare automaticamente uno strumento e i suoi parametri dalla struttura di una classe Java arbitraria: il nome della classe (convertito in snake case) fornisce il nome dello strumento e i campi della classe definiscono i parametri dello strumento.

Dichiara le tue classi di strumenti come classi di primo livello o classi annidate static. Questo requisito deriva dalla libreria Jackson Databind (com.fasterxml.jackson.databind), che l'SDK utilizza per deserializzare gli input degli strumenti nelle istanze delle tue classi e non può istanziare classi interne non statiche.

Definizione di strumenti con annotazioni

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

Chiamata degli strumenti

Quando le tue classi di strumenti sono definite, aggiungile ai parametri del messaggio utilizzando MessageCreateParams.Builder.addTool(Class<T>) e poi chiamale se richiesto nella risposta del modello di IA. BetaToolUseBlock.input(Class<T>) può essere utilizzato per analizzare i parametri di uno strumento in formato JSON in un'istanza della tua classe che definisce lo strumento.

Dopo aver chiamato lo strumento, usa BetaToolResultBlockParam.Builder.contentAsJson(Object) per passare il risultato dello strumento al modello di 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_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
              // Aggiungi un messaggio che indica che è stato richiesto l'uso dello strumento.
              .addAssistantMessageOfBetaContentBlockParams(
                      List.of(BetaContentBlockParam.ofToolUse(BetaToolUseBlockParam.builder()
                              .name(toolUseBlock.name())
                              .id(toolUseBlock.id())
                              .input(toolUseBlock._input())
                              .build())))
              // Aggiungi un messaggio con il risultato dell'uso dello strumento richiesto.
              .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");
}

Conversione del nome dello strumento

I nomi degli strumenti sono derivati dai nomi delle classi di strumenti in camel case (ad esempio, GetWeather) e convertiti in snake case (ad esempio, get_weather). I confini delle parole iniziano dove il carattere corrente non è il primo carattere, è maiuscolo e il carattere precedente è minuscolo oppure il carattere successivo è minuscolo. Ad esempio, MyJSONParser diventa my_json_parser e ParseJSON diventa parse_json. Questa conversione può essere sovrascritta utilizzando l'annotazione @JsonTypeName.

Validazione locale dello schema JSON dello strumento

Puoi eseguire una validazione locale per verificare che lo schema JSON derivato dalla tua classe di strumento rispetti le restrizioni di Anthropic. La validazione locale è abilitata per impostazione predefinita, ma può essere disabilitata:

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

Annotazione delle classi di strumenti

Puoi utilizzare le annotazioni per aggiungere ulteriori informazioni sugli strumenti agli schemi JSON:

@JsonClassDescription - Aggiungi una descrizione a una classe di strumento che dettaglia quando e come utilizzare quello strumento.
@JsonTypeName - Imposta il nome dello strumento su qualcosa di diverso dal nome semplice della classe convertito in snake case.
@JsonPropertyDescription - Aggiungi una descrizione dettagliata a un parametro dello strumento.
@JsonIgnore - Escludi un campo public o un metodo getter dallo schema JSON generato per i parametri di uno strumento.
@JsonProperty - Includi un campo non public o un metodo getter nello schema JSON generato per i parametri di uno strumento.

Batch di messaggi

L'SDK fornisce supporto per l'elaborazione batch nel namespace client.messages().batches(). Consulta Paginazione per sapere come elencare e paginare i batch.

Caricamento di file

L'SDK definisce metodi che accettano file tramite la classe 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);

Oppure da un 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);

Oppure da byte in memoria:

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

Risposte binarie

L'SDK definisce metodi che restituiscono risposte binarie per le risposte API che non vengono necessariamente analizzate come JSON:

import com.anthropic.core.http.HttpResponse;

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

Per salvare il contenuto della risposta in un file:

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

Oppure trasferisci il contenuto della risposta a qualsiasi 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);
}

Gestione degli errori

L'SDK lancia tipi di eccezioni unchecked personalizzate:

AnthropicServiceException - Classe base per gli errori HTTP.
AnthropicIoException - Errori di rete I/O.
AnthropicRetryableException - Errore generico che indica un fallimento che potrebbe essere ritentato.
AnthropicInvalidDataException - Impossibilità di interpretare dati analizzati con successo (ad esempio, quando si accede a una proprietà che dovrebbe essere obbligatoria, ma l'API l'ha inaspettatamente omessa).
AnthropicException - Classe base per tutte le eccezioni.

Mappatura dei codici di stato

Stato	Eccezione
400	`BadRequestException`
401	`UnauthorizedException`
403	`PermissionDeniedException`
404	`NotFoundException`
422	`UnprocessableEntityException`
429	`RateLimitException`
5xx	`InternalServerException`
altri	`UnexpectedStatusCodeException`

SseException viene lanciata per gli errori riscontrati durante lo streaming SSE dopo una risposta HTTP iniziale riuscita.

import com.anthropic.errors.*;

try {
    Message message = client.messages().create(params);
} catch (RateLimitException e) {
    IO.println("Rate limited, retry after: " + e.headers());
} catch (UnauthorizedException e) {
    IO.println("Invalid API key");
} catch (AnthropicServiceException e) {
    IO.println("API error: " + e.statusCode());
} catch (AnthropicIoException e) {
    IO.println("Network error: " + e.getMessage());
}

ID delle richieste

Quando utilizzi le risposte raw, puoi accedere all'header di risposta request-id utilizzando il metodo 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();

Questo può essere utilizzato per registrare rapidamente le richieste fallite e segnalarle ad Anthropic. Per ulteriori informazioni sul debug delle richieste, consulta ID richiesta.

Tentativi

L'SDK riprova automaticamente 2 volte per impostazione predefinita, con un breve backoff esponenziale tra le richieste.

Vengono ritentati solo i seguenti tipi di errore:

Errori di connessione (ad esempio, a causa di un problema di connettività di rete)
408 Request Timeout
409 Conflict
429 Rate Limit
5xx Internal

L'API può anche istruire esplicitamente l'SDK a ritentare o non ritentare una richiesta.

Per impostare un numero personalizzato di tentativi, configura il client utilizzando il metodo maxRetries:

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

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

Timeout

Le richieste vanno in timeout dopo 10 minuti per impostazione predefinita.

Tuttavia, per i metodi che accettano maxTokens, se specifichi un valore maxTokens elevato e stai utilizzando lo streaming, il timeout predefinito verrà calcolato dinamicamente utilizzando questa formula:

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

Questo risulta in un timeout fino a 60 minuti, scalato in base al parametro maxTokens, a meno che non venga sovrascritto.

Per le richieste non in streaming, il timeout dinamico scala da un minimo di 30 secondi fino a un massimo di 10 minuti in base a maxTokens.

Per impostare un timeout personalizzato per richiesta:

import com.anthropic.models.messages.Message;

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

Oppure configura il valore predefinito per tutte le chiamate di metodo a livello di client:

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

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

Richieste lunghe

Considera l'utilizzo dello streaming per richieste di lunga durata.

Evita di impostare un valore maxTokens elevato senza utilizzare lo streaming. Alcune reti potrebbero interrompere le connessioni inattive dopo un certo periodo di tempo, il che può causare il fallimento della richiesta o il timeout senza ricevere una risposta da Anthropic. L'SDK esegue periodicamente un ping all'API per mantenere attiva la connessione e ridurre l'impatto di queste reti.

L'SDK lancia un errore se si prevede che una richiesta non in streaming richieda più di 10 minuti. L'utilizzo di un metodo di streaming o la sovrascrittura del timeout a livello di client o di richiesta disabilita l'errore.

Paginazione

L'SDK fornisce modi pratici per accedere ai risultati paginati una pagina alla volta o elemento per elemento su tutte le pagine.

Paginazione automatica

Per iterare su tutti i risultati di tutte le pagine, usa il metodo autoPager(), che recupera automaticamente più pagine secondo necessità.

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

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

// Elabora come Iterable
for (MessageBatch batch : page.autoPager()) {
    IO.println(batch);
}

// Elabora come Stream
page.autoPager()
    .stream()
    .limit(50)
    .forEach(batch -> IO.println(batch));

Quando si utilizza il client asincrono, il metodo restituisce un 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 devi gestire errori o il completamento dello 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!");
        }
    }
}));

// Oppure usa i future
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!");
        }
    }));

Paginazione manuale

Per accedere agli elementi di una singola pagina e richiedere manualmente la pagina successiva:

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 di tipi

Immutabilità e builder

Ogni classe nell'SDK ha un builder associato per costruirla. Ogni classe è immutabile una volta costruita. Se la classe ha un builder associato, allora ha un metodo toBuilder(), che può essere utilizzato per riconvertirla in un builder per creare una copia modificata.

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

// Crea una copia modificata usando toBuilder()
MessageCreateParams modified = params.toBuilder().maxTokens(2048L).build();

Poiché ogni classe è immutabile, la modifica del builder non influirà mai sulle istanze di classe già costruite.

Richieste e risposte

Per inviare una richiesta all'API di Claude, costruisci un'istanza di una classe Params e passala al metodo client corrispondente. Quando la risposta viene ricevuta, viene deserializzata in un'istanza di una classe Java.

Ad esempio, client.messages().create(...) dovrebbe essere chiamato con un'istanza di MessageCreateParams e restituirà un'istanza di Message.

Parametri non documentati

Per impostare parametri non documentati, chiama i metodi putAdditionalHeader, putAdditionalQueryParam o putAdditionalBodyProperty su qualsiasi 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();

Questi possono essere accessibili sull'oggetto costruito in seguito utilizzando i metodi _additionalHeaders(), _additionalQueryParams() e _additionalBodyProperties().

I valori passati a questi metodi sovrascrivono i valori passati ai metodi precedenti. Per motivi di sicurezza, assicurati che questi metodi vengano utilizzati solo con dati di input attendibili.

Per impostare parametri non documentati su header, parametri di query o classi body annidati:

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

Queste proprietà possono essere accessibili sull'oggetto annidato costruito in seguito utilizzando il metodo _additionalProperties().

Per impostare un parametro o una proprietà documentata su un valore non documentato o non ancora supportato, passa un oggetto JsonValue al suo 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_4_8)
  .build();

Creazione di JsonValue

Il modo più semplice per creare un JsonValue è utilizzare il suo metodo from(...):

import com.anthropic.core.JsonValue;

// Crea valori JSON primitivi
JsonValue nullValue = JsonValue.from(null);

JsonValue booleanValue = JsonValue.from(true);

JsonValue numberValue = JsonValue.from(42);

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

// Crea un valore array JSON equivalente a `["Hello", "World"]`
JsonValue arrayValue = JsonValue.from(List.of("Hello", "World"));

// Crea un valore oggetto JSON equivalente a `{ "a": 1, "b": 2 }`
JsonValue objectValue = JsonValue.from(Map.of("a", 1, "b", 2));

// Crea un JSON annidato 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)));

Omissione forzata di parametri obbligatori

Normalmente il metodo build di una classe Builder lancerà IllegalStateException se un parametro o una proprietà obbligatoria non è impostata. Per omettere forzatamente un parametro o una proprietà obbligatoria, passa 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();

Proprietà della risposta

Per accedere alle proprietà di risposta non documentate, chiama il metodo _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!";
    }

    // Altri metodi includono `visitMissing`, `visitString`, `visitArray` e `visitObject`
    // L'implementazione predefinita di ogni metodo non implementato delega a `visitDefault`,
    // che per impostazione predefinita genera un'eccezione, ma può anche essere sovrascritto
});

Per accedere al valore JSON raw di una proprietà, chiama il suo metodo con prefisso _:

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

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

if (stopReason.isMissing()) {
  // La proprietà è assente dalla risposta JSON
} else if (stopReason.isNull()) {
  // La proprietà è stata impostata su null letterale
} else {
  // Verifica se il valore è stato fornito come stringa
  // Altri metodi includono `asNumber()`, `asBoolean()`, ecc.
  Optional<String> jsonString = stopReason.asString();

  // Prova a deserializzare in un tipo personalizzato
  MyClass myObject = stopReason.asUnknown().orElseThrow().convert(MyClass.class);
}

Validazione della risposta

Per impostazione predefinita, l'SDK non lancia un'eccezione quando l'API restituisce una risposta che non corrisponde al tipo previsto. Lancia AnthropicInvalidDataException solo se accedi direttamente alla proprietà.

Per verificare in anticipo che la risposta sia completamente ben tipizzata, chiama validate():

import com.anthropic.models.messages.Message;

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

Oppure configura per richiesta:

import com.anthropic.models.messages.Message;

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

Oppure configura il valore predefinito per tutte le chiamate di metodo a livello di client:

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

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

Personalizzazione del client HTTP

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

Configurazione HTTPS / SSL

La maggior parte delle applicazioni non dovrebbe chiamare questi metodi e dovrebbe invece utilizzare le impostazioni predefinite di sistema. Le impostazioni predefinite includono ottimizzazioni speciali che possono andare perse se le implementazioni vengono modificate.

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

AnthropicClient client = AnthropicOkHttpClient.builder()
  .fromEnv()
  .sslSocketFactory(yourSSLSocketFactory)
  .trustManager(yourTrustManager)
  .hostnameVerifier(yourHostnameVerifier)
  .build();

Client HTTP personalizzato

L'SDK è composto da tre artefatti:

anthropic-java-core - Contiene la logica principale dell'SDK, non dipende da OkHttp. Espone AnthropicClient, AnthropicClientAsync e le loro classi di implementazione, tutte le quali possono funzionare con qualsiasi client HTTP.
anthropic-java-client-okhttp - Dipende da OkHttp. Espone AnthropicOkHttpClient e AnthropicOkHttpClientAsync.
anthropic-java - Dipende da ed espone le API sia di anthropic-java-core che di anthropic-java-client-okhttp. Non ha una propria logica.

Questa struttura consente di sostituire il client HTTP predefinito dell'SDK senza includere dipendenze non necessarie.

OkHttpClient personalizzato

Prova le opzioni di rete disponibili prima di sostituire il client predefinito.

Per utilizzare un OkHttpClient personalizzato:

Sostituisci la tua dipendenza anthropic-java con anthropic-java-core.
Copia la classe OkHttpClient di anthropic-java-client-okhttp nel tuo codice e personalizzala.
Costruisci AnthropicClientImpl o AnthropicClientAsyncImpl utilizzando il tuo client personalizzato.

Client HTTP completamente personalizzato

Per utilizzare un client HTTP completamente personalizzato:

Sostituisci la tua dipendenza anthropic-java con anthropic-java-core.
Scrivi una classe che implementa l'interfaccia HttpClient.
Costruisci AnthropicClientImpl o AnthropicClientAsyncImpl utilizzando la tua nuova classe client.

Integrazioni con piattaforme

Per guide dettagliate alla configurazione delle piattaforme con esempi di codice, consulta:

L'SDK Java supporta le seguenti piattaforme tramite dipendenze separate che forniscono implementazioni Backend specifiche per piattaforma:

Bedrock: com.anthropic:anthropic-java-bedrock: Usa BedrockMantleBackend.fromEnv() o BedrockMantleBackend.builder() per l'endpoint Bedrock con Messages API, oppure BedrockBackend.fromEnv() / BedrockBackend.builder() (percorso bedrock-runtime).
Vertex AI: com.anthropic:anthropic-java-vertex: Usa VertexBackend.fromEnv() o VertexBackend.builder().
Foundry: com.anthropic:anthropic-java-foundry: Usa FoundryBackend.fromEnv() o FoundryBackend.builder().
Claude Platform su AWS: com.anthropic:anthropic-java-aws: Usa (legge e la catena predefinita di regione/credenziali AWS) o . Disponibile in beta.

Usa BedrockMantleBackend per i nuovi progetti; BedrockBackend rimane per le applicazioni esistenti che utilizzano l'API InvokeModel di Bedrock.

Ogni implementazione Backend viene passata al client con .backend() su AnthropicOkHttpClient.builder(). Ogni backend cloud include le rispettive classi SDK della piattaforma cloud come dipendenze transitive.

Utilizzo avanzato

Accesso alla risposta raw

Per accedere agli header HTTP, ai codici di stato e al corpo della risposta raw, anteponi withRawResponse() a qualsiasi chiamata di metodo 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();

Puoi comunque deserializzare la risposta in un'istanza di una classe Java se necessario:

import com.anthropic.models.messages.Message;

Message parsedMessage = message.parse();

Logging

L'SDK utilizza l'interceptor di logging standard di OkHttp.

Abilita il logging impostando la variabile d'ambiente ANTHROPIC_LOG su info:

export ANTHROPIC_LOG=info

Oppure su debug per un logging più dettagliato:

export ANTHROPIC_LOG=debug

Funzionalità API non documentate

L'SDK è tipizzato per un utilizzo pratico dell'API documentata. Tuttavia, supporta anche l'utilizzo di parti dell'API non documentate o non ancora supportate.

Parametri di richiesta non documentati

Per impostare parametri di richiesta non documentati, usa i metodi putAdditionalHeader, putAdditionalQueryParam o putAdditionalBodyProperty come descritto in Parametri non documentati.

Proprietà di risposta non documentate

Per accedere alle proprietà di risposta non documentate, usa il metodo _additionalProperties() come descritto in Proprietà della risposta.

Valori enum nuovi o non rilasciati

Le classi simili a enum nell'SDK, come Model e AnthropicBeta, non sono tipi enum Java chiusi. Ognuna fornisce un metodo factory of(String) che accetta qualsiasi stringa, quindi puoi utilizzare valori che non sono ancora stati aggiunti all'SDK, come un modello o un header beta rilasciato dopo la tua versione dell'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");

I metodi builder che accettano questi tipi spesso forniscono anche un overload String che chiama of(...) per te:

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

Preferisci le costanti ben tipizzate (ad esempio, Model.CLAUDE_OPUS_4_7) così ottieni il completamento automatico e gli avvisi di deprecazione. Gli overload String e of(...) servono principalmente per impostare il campo su un valore non documentato o non ancora supportato in attesa di una release dell'SDK che lo includa.

Funzionalità beta

Le funzionalità beta sono disponibili prima del rilascio generale per ottenere feedback anticipato e testare nuove funzionalità. Puoi verificare la disponibilità di tutte le capacità e gli strumenti di Claude nella panoramica di build with Claude.

Puoi accedere alla maggior parte delle funzionalità API beta tramite il metodo beta() sul client. Per abilitare una particolare funzionalità beta, aggiungi l'header beta appropriato con .addBeta() quando costruisci i parametri del messaggio.

Ad esempio, per utilizzare la 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());
}

Domande frequenti

Versionamento semantico

Questo pacchetto segue generalmente le convenzioni SemVer, anche se alcune modifiche non retrocompatibili possono essere rilasciate come versioni minori:

Modifiche agli interni della libreria che sono tecnicamente pubblici ma non destinati o documentati per uso esterno.
Modifiche che non si prevede abbiano un impatto sulla stragrande maggioranza degli utenti nella pratica.

Risorse aggiuntive

Was this page helpful?

CLI, SDK e librerieSDK client

SDK Java

Installa e configura l'SDK Java di Anthropic con pattern builder e supporto asincrono

Per la documentazione delle funzionalità API con esempi di codice, consulta il riferimento API. Questa pagina tratta le funzionalità e la configurazione dell'SDK specifiche per Java.

Installazione

Requisiti

Questa libreria richiede Java 8 o versioni successive.

Avvio rapido

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 le proprietà di sistema `anthropic.apiKey`, `anthropic.authToken` e `anthropic.baseUrl`
// Oppure configura usando le variabili d'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_4_8)
  .build();

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

Configurazione del client

Configurazione della chiave API

Configura il client utilizzando le proprietà di sistema o le variabili d'ambiente:

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

// Configura usando le proprietà di sistema `anthropic.apiKey`, `anthropic.authToken` e `anthropic.baseUrl`
// Oppure configura usando le variabili d'ambiente `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` e `ANTHROPIC_BASE_URL`
AnthropicClient client = AnthropicOkHttpClient.fromEnv();

Oppure configura manualmente:

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

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

Oppure usa una combinazione di entrambi gli approcci:

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

AnthropicClient client = AnthropicOkHttpClient.builder()
  // Configura usando proprietà di sistema o variabili d'ambiente
  .fromEnv()
  .apiKey("my-anthropic-api-key")
  .build();

Per le opzioni di autenticazione, inclusa la Workload Identity Federation, consulta Autenticazione.

Opzioni di configurazione

Setter	Proprietà di sistema	Variabile d'ambiente	Obbligatorio	Valore predefinito
`apiKey`	`anthropic.apiKey`	`ANTHROPIC_API_KEY`	false	-
`authToken`	`anthropic.authToken`	`ANTHROPIC_AUTH_TOKEN`	false	-
`baseUrl`	`anthropic.baseUrl`	`ANTHROPIC_BASE_URL`	true

Le proprietà di sistema hanno la precedenza sulle variabili d'ambiente.

Non creare più di un client nella stessa applicazione. Ogni client ha un pool di connessioni e pool di thread, che sono più efficienti se condivisi tra le richieste.

Modifica della configurazione

Per utilizzare temporaneamente una configurazione del client modificata riutilizzando gli stessi pool di connessioni e thread, chiama withOptions() su qualsiasi client o servizio:

import com.anthropic.client.AnthropicClient;

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

Il metodo withOptions() non influisce sul client o servizio originale.

Utilizzo asincrono

Il client predefinito è sincrono. Per passare all'esecuzione asincrona, chiama il metodo 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);

Oppure crea un client asincrono fin dall'inizio:

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

Il client asincrono supporta le stesse opzioni di quello sincrono, tranne che la maggior parte dei metodi restituisce CompletableFuture.

Streaming

L'SDK definisce metodi che restituiscono stream di "chunk" di risposta, dove ogni chunk può essere elaborato individualmente non appena arriva invece di attendere la risposta completa.

Streaming sincrono

Questi metodi di streaming restituiscono StreamResponse per i client sincroni:

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 asincrono

Per i client asincroni, il metodo restituisce AsyncStreamResponse:

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

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

// Se devi gestire errori o il completamento dello 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!");
        }
    }
});

// Oppure usa i future
client.async().messages().createStreaming(params)
    .subscribe(chunk -> {
        IO.println(chunk);
    })
    .onCompleteFuture()
    .whenComplete((unused, error) -> {
        if (error != null) {
            IO.println("Something went wrong!");
            throw new RuntimeException(error);
        } else {
            IO.println("No more chunks!");
        }
    });

Lo streaming asincrono utilizza un Executor dedicato con pool di thread in cache per ogni client per eseguire lo streaming senza bloccare il thread corrente. Per utilizzare un Executor diverso:

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

Oppure configura il client globalmente utilizzando il metodo streamHandlerExecutor:

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

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

Streaming con accumulatore di messaggi

Per una risposta sincrona, aggiungi una chiamata Stream.peek() alla pipeline dello stream per accumulare ogni 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();

Per una risposta asincrona, aggiungi il MessageAccumulator alla chiamata 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();

È disponibile anche un BetaMessageAccumulator per l'accumulo di un oggetto BetaMessage. Viene utilizzato nello stesso modo del MessageAccumulator.

Output strutturati

Per la documentazione completa sugli output strutturati, inclusi esempi Java, consulta Output strutturati.

Uso degli strumenti

La funzionalità di uso degli strumenti supporta una modalità "strict" che garantisce che l'output JSON del modello di IA sia conforme allo schema JSON fornito nei parametri di input.

Definizione di strumenti con annotazioni

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

Chiamata degli strumenti

Dopo aver chiamato lo strumento, usa BetaToolResultBlockParam.Builder.contentAsJson(Object) per passare il risultato dello strumento al modello di 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_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
              // Aggiungi un messaggio che indica che è stato richiesto l'uso dello strumento.
              .addAssistantMessageOfBetaContentBlockParams(
                      List.of(BetaContentBlockParam.ofToolUse(BetaToolUseBlockParam.builder()
                              .name(toolUseBlock.name())
                              .id(toolUseBlock.id())
                              .input(toolUseBlock._input())
                              .build())))
              // Aggiungi un messaggio con il risultato dell'uso dello strumento richiesto.
              .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");
}

Conversione del nome dello strumento

Validazione locale dello schema JSON dello strumento

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

Annotazione delle classi di strumenti

Puoi utilizzare le annotazioni per aggiungere ulteriori informazioni sugli strumenti agli schemi JSON:

@JsonClassDescription - Aggiungi una descrizione a una classe di strumento che dettaglia quando e come utilizzare quello strumento.
@JsonTypeName - Imposta il nome dello strumento su qualcosa di diverso dal nome semplice della classe convertito in snake case.
@JsonPropertyDescription - Aggiungi una descrizione dettagliata a un parametro dello strumento.
@JsonIgnore - Escludi un campo public o un metodo getter dallo schema JSON generato per i parametri di uno strumento.
@JsonProperty - Includi un campo non public o un metodo getter nello schema JSON generato per i parametri di uno strumento.

Batch di messaggi

L'SDK fornisce supporto per l'elaborazione batch nel namespace client.messages().batches(). Consulta Paginazione per sapere come elencare e paginare i batch.

Caricamento di file

L'SDK definisce metodi che accettano file tramite la classe 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);

Oppure da un 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);

Oppure da byte in memoria:

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

Risposte binarie

L'SDK definisce metodi che restituiscono risposte binarie per le risposte API che non vengono necessariamente analizzate come JSON:

import com.anthropic.core.http.HttpResponse;

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

Per salvare il contenuto della risposta in un file:

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

Oppure trasferisci il contenuto della risposta a qualsiasi 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);
}

Gestione degli errori

L'SDK lancia tipi di eccezioni unchecked personalizzate:

AnthropicServiceException - Classe base per gli errori HTTP.
AnthropicIoException - Errori di rete I/O.
AnthropicRetryableException - Errore generico che indica un fallimento che potrebbe essere ritentato.
AnthropicInvalidDataException - Impossibilità di interpretare dati analizzati con successo (ad esempio, quando si accede a una proprietà che dovrebbe essere obbligatoria, ma l'API l'ha inaspettatamente omessa).
AnthropicException - Classe base per tutte le eccezioni.

Mappatura dei codici di stato

Stato	Eccezione
400	`BadRequestException`
401	`UnauthorizedException`
403	`PermissionDeniedException`
404	`NotFoundException`
422	`UnprocessableEntityException`
429	`RateLimitException`
5xx	`InternalServerException`
altri	`UnexpectedStatusCodeException`

SseException viene lanciata per gli errori riscontrati durante lo streaming SSE dopo una risposta HTTP iniziale riuscita.

import com.anthropic.errors.*;

try {
    Message message = client.messages().create(params);
} catch (RateLimitException e) {
    IO.println("Rate limited, retry after: " + e.headers());
} catch (UnauthorizedException e) {
    IO.println("Invalid API key");
} catch (AnthropicServiceException e) {
    IO.println("API error: " + e.statusCode());
} catch (AnthropicIoException e) {
    IO.println("Network error: " + e.getMessage());
}

ID delle richieste

Quando utilizzi le risposte raw, puoi accedere all'header di risposta request-id utilizzando il metodo 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();

Questo può essere utilizzato per registrare rapidamente le richieste fallite e segnalarle ad Anthropic. Per ulteriori informazioni sul debug delle richieste, consulta ID richiesta.

Tentativi

L'SDK riprova automaticamente 2 volte per impostazione predefinita, con un breve backoff esponenziale tra le richieste.

Vengono ritentati solo i seguenti tipi di errore:

Errori di connessione (ad esempio, a causa di un problema di connettività di rete)
408 Request Timeout
409 Conflict
429 Rate Limit
5xx Internal

L'API può anche istruire esplicitamente l'SDK a ritentare o non ritentare una richiesta.

Per impostare un numero personalizzato di tentativi, configura il client utilizzando il metodo maxRetries:

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

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

Timeout

Le richieste vanno in timeout dopo 10 minuti per impostazione predefinita.

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

Questo risulta in un timeout fino a 60 minuti, scalato in base al parametro maxTokens, a meno che non venga sovrascritto.

Per le richieste non in streaming, il timeout dinamico scala da un minimo di 30 secondi fino a un massimo di 10 minuti in base a maxTokens.

Per impostare un timeout personalizzato per richiesta:

import com.anthropic.models.messages.Message;

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

Oppure configura il valore predefinito per tutte le chiamate di metodo a livello di client:

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

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

Richieste lunghe

Considera l'utilizzo dello streaming per richieste di lunga durata.

Paginazione

L'SDK fornisce modi pratici per accedere ai risultati paginati una pagina alla volta o elemento per elemento su tutte le pagine.

Paginazione automatica

Per iterare su tutti i risultati di tutte le pagine, usa il metodo autoPager(), che recupera automaticamente più pagine secondo necessità.

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

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

// Elabora come Iterable
for (MessageBatch batch : page.autoPager()) {
    IO.println(batch);
}

// Elabora come Stream
page.autoPager()
    .stream()
    .limit(50)
    .forEach(batch -> IO.println(batch));

Quando si utilizza il client asincrono, il metodo restituisce un 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 devi gestire errori o il completamento dello 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!");
        }
    }
}));

// Oppure usa i future
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!");
        }
    }));

Paginazione manuale

Per accedere agli elementi di una singola pagina e richiedere manualmente la pagina successiva:

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 di tipi

Immutabilità e builder

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

// Crea una copia modificata usando toBuilder()
MessageCreateParams modified = params.toBuilder().maxTokens(2048L).build();

Poiché ogni classe è immutabile, la modifica del builder non influirà mai sulle istanze di classe già costruite.

Richieste e risposte

Ad esempio, client.messages().create(...) dovrebbe essere chiamato con un'istanza di MessageCreateParams e restituirà un'istanza di Message.

Parametri non documentati

Per impostare parametri non documentati, chiama i metodi putAdditionalHeader, putAdditionalQueryParam o putAdditionalBodyProperty su qualsiasi 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();

Questi possono essere accessibili sull'oggetto costruito in seguito utilizzando i metodi _additionalHeaders(), _additionalQueryParams() e _additionalBodyProperties().

I valori passati a questi metodi sovrascrivono i valori passati ai metodi precedenti. Per motivi di sicurezza, assicurati che questi metodi vengano utilizzati solo con dati di input attendibili.

Per impostare parametri non documentati su header, parametri di query o classi body annidati:

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

Queste proprietà possono essere accessibili sull'oggetto annidato costruito in seguito utilizzando il metodo _additionalProperties().

Per impostare un parametro o una proprietà documentata su un valore non documentato o non ancora supportato, passa un oggetto JsonValue al suo 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_4_8)
  .build();

Creazione di JsonValue

Il modo più semplice per creare un JsonValue è utilizzare il suo metodo from(...):

import com.anthropic.core.JsonValue;

// Crea valori JSON primitivi
JsonValue nullValue = JsonValue.from(null);

JsonValue booleanValue = JsonValue.from(true);

JsonValue numberValue = JsonValue.from(42);

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

// Crea un valore array JSON equivalente a `["Hello", "World"]`
JsonValue arrayValue = JsonValue.from(List.of("Hello", "World"));

// Crea un valore oggetto JSON equivalente a `{ "a": 1, "b": 2 }`
JsonValue objectValue = JsonValue.from(Map.of("a", 1, "b", 2));

// Crea un JSON annidato 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)));

Omissione forzata di parametri obbligatori

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

Proprietà della risposta

Per accedere alle proprietà di risposta non documentate, chiama il metodo _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!";
    }

    // Altri metodi includono `visitMissing`, `visitString`, `visitArray` e `visitObject`
    // L'implementazione predefinita di ogni metodo non implementato delega a `visitDefault`,
    // che per impostazione predefinita genera un'eccezione, ma può anche essere sovrascritto
});

Per accedere al valore JSON raw di una proprietà, chiama il suo metodo con prefisso _:

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

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

if (stopReason.isMissing()) {
  // La proprietà è assente dalla risposta JSON
} else if (stopReason.isNull()) {
  // La proprietà è stata impostata su null letterale
} else {
  // Verifica se il valore è stato fornito come stringa
  // Altri metodi includono `asNumber()`, `asBoolean()`, ecc.
  Optional<String> jsonString = stopReason.asString();

  // Prova a deserializzare in un tipo personalizzato
  MyClass myObject = stopReason.asUnknown().orElseThrow().convert(MyClass.class);
}

Validazione della risposta

Per verificare in anticipo che la risposta sia completamente ben tipizzata, chiama validate():

import com.anthropic.models.messages.Message;

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

Oppure configura per richiesta:

import com.anthropic.models.messages.Message;

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

Oppure configura il valore predefinito per tutte le chiamate di metodo a livello di client:

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

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

Personalizzazione del client HTTP

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

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

Client HTTP personalizzato

L'SDK è composto da tre artefatti:

anthropic-java-core - Contiene la logica principale dell'SDK, non dipende da OkHttp. Espone AnthropicClient, AnthropicClientAsync e le loro classi di implementazione, tutte le quali possono funzionare con qualsiasi client HTTP.
anthropic-java-client-okhttp - Dipende da OkHttp. Espone AnthropicOkHttpClient e AnthropicOkHttpClientAsync.
anthropic-java - Dipende da ed espone le API sia di anthropic-java-core che di anthropic-java-client-okhttp. Non ha una propria logica.

Questa struttura consente di sostituire il client HTTP predefinito dell'SDK senza includere dipendenze non necessarie.

OkHttpClient personalizzato

Prova le opzioni di rete disponibili prima di sostituire il client predefinito.

Per utilizzare un OkHttpClient personalizzato:

Sostituisci la tua dipendenza anthropic-java con anthropic-java-core.
Copia la classe OkHttpClient di anthropic-java-client-okhttp nel tuo codice e personalizzala.
Costruisci AnthropicClientImpl o AnthropicClientAsyncImpl utilizzando il tuo client personalizzato.

Client HTTP completamente personalizzato

Per utilizzare un client HTTP completamente personalizzato:

Sostituisci la tua dipendenza anthropic-java con anthropic-java-core.
Scrivi una classe che implementa l'interfaccia HttpClient.
Costruisci AnthropicClientImpl o AnthropicClientAsyncImpl utilizzando la tua nuova classe client.

Integrazioni con piattaforme

Per guide dettagliate alla configurazione delle piattaforme con esempi di codice, consulta:

L'SDK Java supporta le seguenti piattaforme tramite dipendenze separate che forniscono implementazioni Backend specifiche per piattaforma:

Bedrock: com.anthropic:anthropic-java-bedrock: Usa BedrockMantleBackend.fromEnv() o BedrockMantleBackend.builder() per l'endpoint Bedrock con Messages API, oppure BedrockBackend.fromEnv() / BedrockBackend.builder() (percorso bedrock-runtime).
Vertex AI: com.anthropic:anthropic-java-vertex: Usa VertexBackend.fromEnv() o VertexBackend.builder().
Foundry: com.anthropic:anthropic-java-foundry: Usa FoundryBackend.fromEnv() o FoundryBackend.builder().
Claude Platform su AWS: com.anthropic:anthropic-java-aws: Usa (legge e la catena predefinita di regione/credenziali AWS) o . Disponibile in beta.

Usa BedrockMantleBackend per i nuovi progetti; BedrockBackend rimane per le applicazioni esistenti che utilizzano l'API InvokeModel di Bedrock.

Utilizzo avanzato

Accesso alla risposta raw

Per accedere agli header HTTP, ai codici di stato e al corpo della risposta raw, anteponi withRawResponse() a qualsiasi chiamata di metodo 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();

Puoi comunque deserializzare la risposta in un'istanza di una classe Java se necessario:

import com.anthropic.models.messages.Message;

Message parsedMessage = message.parse();

Logging

L'SDK utilizza l'interceptor di logging standard di OkHttp.

Abilita il logging impostando la variabile d'ambiente ANTHROPIC_LOG su info:

export ANTHROPIC_LOG=info

Oppure su debug per un logging più dettagliato:

export ANTHROPIC_LOG=debug

Funzionalità API non documentate

L'SDK è tipizzato per un utilizzo pratico dell'API documentata. Tuttavia, supporta anche l'utilizzo di parti dell'API non documentate o non ancora supportate.

Parametri di richiesta non documentati

Per impostare parametri di richiesta non documentati, usa i metodi putAdditionalHeader, putAdditionalQueryParam o putAdditionalBodyProperty come descritto in Parametri non documentati.

Proprietà di risposta non documentate

Per accedere alle proprietà di risposta non documentate, usa il metodo _additionalProperties() come descritto in Proprietà della risposta.

Valori enum nuovi o non rilasciati

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

I metodi builder che accettano questi tipi spesso forniscono anche un overload String che chiama of(...) per te:

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

Funzionalità beta

Ad esempio, per utilizzare la 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());
}

Domande frequenti

Versionamento semantico

Questo pacchetto segue generalmente le convenzioni SemVer, anche se alcune modifiche non retrocompatibili possono essere rilasciate come versioni minori:

Modifiche agli interni della libreria che sono tecnicamente pubblici ma non destinati o documentati per uso esterno.
Modifiche che non si prevede abbiano un impatto sulla stragrande maggioranza degli utenti nella pratica.

Risorse aggiuntive

Was this page helpful?

Installazione

Requisiti

Avvio rapido

Configurazione del client

Configurazione della chiave API

Opzioni di configurazione

Modifica della configurazione

Utilizzo asincrono

Streaming

Streaming sincrono

Streaming asincrono

Streaming con accumulatore di messaggi

Output strutturati

Uso degli strumenti

Definizione di strumenti con annotazioni

Chiamata degli strumenti

Conversione del nome dello strumento

Validazione locale dello schema JSON dello strumento

Annotazione delle classi di strumenti

Batch di messaggi

Caricamento di file

Risposte binarie

Gestione degli errori

Mappatura dei codici di stato

ID delle richieste

Tentativi

Timeout

Richieste lunghe

Paginazione

Paginazione automatica

Paginazione manuale

Sistema di tipi

Immutabilità e builder

Richieste e risposte

Parametri non documentati

Creazione di JsonValue

Omissione forzata di parametri obbligatori

Proprietà della risposta

Validazione della risposta

Personalizzazione del client HTTP

Configurazione del proxy

Configurazione HTTPS / SSL

Client HTTP personalizzato

OkHttpClient personalizzato

Client HTTP completamente personalizzato

Integrazioni con piattaforme

Utilizzo avanzato

Accesso alla risposta raw

Logging

Compatibilità con Jackson

Configurazione ProGuard/R8

Funzionalità API non documentate

Parametri di richiesta non documentati

Proprietà di risposta non documentate

Valori enum nuovi o non rilasciati

Funzionalità beta

Domande frequenti

Perché l'SDK non utilizza classi enum semplici?

Perché i campi sono rappresentati utilizzando JsonField<T> invece di semplicemente T?

Perché l'SDK non utilizza data class?

Perché l'SDK non utilizza eccezioni checked?

Versionamento semantico

Risorse aggiuntive

Installazione

Requisiti

Avvio rapido

Configurazione del client

Configurazione della chiave API

Opzioni di configurazione

Modifica della configurazione

Utilizzo asincrono

Streaming

Streaming sincrono

Streaming asincrono

Streaming con accumulatore di messaggi

Output strutturati

Uso degli strumenti

Definizione di strumenti con annotazioni

Chiamata degli strumenti

Conversione del nome dello strumento