跳到主要内容

Anthropic

Maven依存関係​

<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-anthropic</artifactId>
<version>1.23.0</version>
</dependency>

AnthropicChatModel​

AnthropicChatModel model = AnthropicChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.modelName(CLAUDE_3_5_SONNET_20240620)
.build();
String answer = model.chat("Say 'Hello World'");
System.out.println(answer);

AnthropicChatModel のカスタマイズ​

AnthropicChatModel model = AnthropicChatModel.builder()
.httpClientBuilder(...)
.baseUrl(...)
.apiKey(...)
.version(...)
.beta(...)
.modelName(...)
.temperature(...)
.topP(...)
.topK(...)
.maxTokens(...)
.stopSequences(...)
.toolSpecifications(...)
.toolChoice(...)
.toolChoiceName(...)
.disableParallelToolUse(...)
.serverTools(...)
.returnServerToolResults(...)
.toolMetadataKeysToSend(...)
.cacheSystemMessages(...)
.cacheTools(...)
.cacheAutomatically(...)
.cacheTtl(...)
.returnCacheDiagnostics(...)
.thinkingType(...)
.thinkingBudgetTokens(...)
.thinkingDisplay(...)
.returnThinking(...)
.sendThinking(...)
.midConversationSystemMessages(...)
.timeout(...)
.maxRetries(...)
.logRequests(...)
.logResponses(...)
.listeners(...)
// You can also specify default chat request parameters using ChatRequestParameters or AnthropicChatRequestParameters
.defaultRequestParameters(...)
.userId(...)
.customParameters(...)
.build();

上記の一部パラメータの説明は こちら。

リクエスト単位のパラメータ​

上記に示した Anthropic 固有のオプション(cacheSystemMessages、cacheTools、cacheAutomatically、cacheTtl、returnCacheDiagnostics、thinkingType、thinkingBudgetTokens、sendThinking、returnThinking、midConversationSystemMessages、toolChoiceName、disableParallelToolUse、および userId)と、previousMessageId(リクエスト専用、Cache Diagnostics を参照)は、 AnthropicChatRequestParameters 経由でリクエスト単位にも設定でき、モデルビルダー上の値を上書きします。 これにより、共有の単一モデルインスタンスで呼び出しごとにこれらのオプションを変えられます——例えば、 長時間のエージェントループではプロンプトキャッシュを有効にし、安価なワンショット補完ではスキップし、 2 つ目のモデルを構築せずに済みます:

AnthropicChatModel model = AnthropicChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.modelName(CLAUDE_3_5_SONNET_20240620)
.build();

AnthropicChatRequestParameters parameters = AnthropicChatRequestParameters.builder()
.cacheSystemMessages(true)
.cacheTools(true)
.build();

ChatRequest chatRequest = ChatRequest.builder()
.messages(systemMessage, userMessage)
.parameters(parameters)
.build();

ChatResponse chatResponse = model.chat(chatRequest);

リクエストに設定されていないパラメータは、モデルビルダー上の値にフォールバックします。

AnthropicStreamingChatModel​

AnthropicStreamingChatModel model = AnthropicStreamingChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.modelName(CLAUDE_3_5_SONNET_20240620)
.build();

model.chat("Say 'Hello World'", new StreamingChatResponseHandler() {

@Override
public void onPartialResponse(String partialResponse) {
// this method is called when a new partial response is available. It can consist of one or more tokens.
}

@Override
public void onCompleteResponse(ChatResponse completeResponse) {
// this method is called when the model has completed responding
}

@Override
public void onError(Throwable error) {
// this method is called when an error occurs
}
});

AnthropicStreamingChatModel のカスタマイズ​

AnthropicChatModel と同一です。上記を参照してください。

Batch API​

Message Batches API は多数のチャットリクエストを 標準のトークン単価の 50% で非同期処理します。AnthropicBatchChatModel はコアの BatchChatModel インターフェース(submit、retrieve、cancel、list)を実装します。各リクエストは AnthropicChatModel 呼び出しと同じパラメータで送信します。

AnthropicBatchChatModel model = AnthropicBatchChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.modelName("claude-sonnet-4-5")
.maxTokens(1024)
.build();

// Submit a batch of requests
BatchResponse<ChatResponse> submitted = model.submit(new BatchRequest<>(List.of(
ChatRequest.builder().messages(UserMessage.from("What is the capital of France?")).build(),
ChatRequest.builder().messages(UserMessage.from("What is the capital of Germany?")).build())));

String batchId = submitted.batchId();

// Poll until the batch reaches a terminal state (typically well under an hour)
BatchResponse<ChatResponse> batch = model.retrieve(batchId);
while (!batch.state().isTerminal()) {
TimeUnit.SECONDS.sleep(30); // throws InterruptedException
batch = model.retrieve(batchId);
}

// Read the per-request results, in submission order
for (BatchItemResult<ChatResponse> result : batch.results()) {
if (result.isSuccess()) {
System.out.println(result.response().aiMessage().text());
} else {
System.out.println("Failed: " + result.error().message());
}
}

model.list(...) で最近のバッチをページングし、model.cancel(batchId) で処理中のバッチをキャンセルできます。 キャンセルしたバッチも Anthropic 側では ended 状態で終わり、BatchState.CANCELLED として報告されます。 キャンセルが効く前に完了したリクエストの結果が含まれる場合があります。

thinking やプロンプトキャッシュなどの Anthropic 固有オプションは defaultRequestParameters(...) で設定し、 AnthropicChatModel と全く同様で、リクエスト単位で上書きできます:

AnthropicBatchChatModel model = AnthropicBatchChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.modelName("claude-sonnet-4-5")
.maxTokens(4096)
.defaultRequestParameters(AnthropicChatRequestParameters.builder()
.thinkingType("enabled")
.thinkingBudgetTokens(2000)
.cacheSystemMessages(true)
.cacheTtl("1h") // batches can take longer than the default 5-minute cache TTL
.build())
.returnThinking(true) // store the returned thinking in AiMessage.thinking()
.build();

ツール(Tools)​

Anthropic はストリーミング/非ストリーミングの両方で ツール をサポートします。

Anthropic のツールに関するドキュメントは こちら。

ツール選択(Tool Choice)​

Anthropic の ツール選択 機能は、ストリーミングと非ストリーミングの両方のやり取りで利用できます:

  • toolChoice(ToolChoice.REQUIRED) は、テキストで回答する代わりに、利用可能なツールのいずれかを呼び出すようモデルに強制します。
  • toolChoiceName("get_weather") は、特定の 1 つのツールを呼び出すようモデルに強制します。単独で使用できます。 また toolChoice(ToolChoice) も設定されている場合は、名前で指定されたツールが優先されます。

並列ツール使用​

デフォルトでは Anthropic Claude はユーザーのクエリに答えるために複数のツールを使うことがありますが、 並列ツールの使用は disableParallelToolUse(true) を設定することで無効にできます。

サーバーツール(Server Tools)​

Anthropic の サーバーツール は serverTools パラメータでサポートされます。以下は ウェブ検索ツール の使用例です:

AnthropicServerTool webSearchTool = AnthropicServerTool.builder()
.type("web_search_20250305")
.name("web_search")
.addAttribute("max_uses", 5)
.addAttribute("allowed_domains", List.of("accuweather.com"))
.build();

ChatModel model = AnthropicChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.modelName("claude-sonnet-4-5")
.serverTools(webSearchTool)
.logRequests(true)
.logResponses(true)
.build();

String answer = model.chat("What is the weather in Munich?");

serverTools で指定したツールは、Anthropic API へのすべてのリクエストに含まれます。

サーバーツール結果の取得​

サーバーツールの生の結果(ウェブ検索結果、コード実行出力、 生成ファイルの fileIds など)にアクセスするには、returnServerToolResults(true) を有効にします。 結果は AiMessage.attributes() の "server_tool_results" キー配下に入ります:

ChatModel model = AnthropicChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.modelName("claude-sonnet-4-5")
.serverTools(webSearchTool)
.returnServerToolResults(true)
.build();

ChatResponse response = model.chat("What is the weather in Munich?");
AiMessage aiMessage = response.aiMessage();

List<AnthropicServerToolResult> results = aiMessage.attribute("server_tool_results", List.class);
for (AnthropicServerToolResult result : results) {
System.out.println("Type: " + result.type());
System.out.println("Tool Use ID: " + result.toolUseId());
System.out.println("Content: " + result.content());
}

ChatMemory に大きなデータが保存されるのを避けるため、デフォルトでは無効です。

Skills​

Anthropic の Agent Skills は、コード実行コンテナ内で事前構築スキルを実行し、ダウンロード可能な実ドキュメント(.xlsx、.pptx、.docx、.pdf)を Claude に生成させます。 型付きの skills パラメータで有効化します:

AnthropicChatModel model = AnthropicChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.modelName("claude-opus-4-8")
.maxTokens(4096)
.beta("code-execution-2025-08-25,skills-2025-10-02,files-api-2025-04-14")
.skills(AnthropicSkill.XLSX, AnthropicSkill.PPTX)
.returnServerToolResults(true)
.build();

ChatResponse response = model.chat("Create an Excel spreadsheet with the numbers 1 to 5 in column A");

skills を有効にすると自動的に:

  • リクエストに container.skills ブロックを追加し、
  • 必要な code_execution サーバーツールを追加します(既に serverTools(...) で設定済みでない場合)。

必要な beta 機能は、上記のように自分で beta(...) によりオプトインする必要があります。これらは beta ヘッダーで、値は時間とともに変わるため自動注入されません——現行セットは Agent Skills ドキュメント を確認してください。

returnServerToolResults(true) と組み合わせると、生成されたファイル id が AiMessage.attributes() の "server_tool_results" キー(上記のサーバーツール結果の取得を参照)に出力できます。ファイルは Anthropic の Files API を通じて 24 時間ダウンロードできます。

Skills は Claude Sonnet 4 / 4.5、Opus 4 以降でサポートされます。リクエストあたり最大 8 スキルまで有効化できます。 同じ skills(...) パラメータは AnthropicStreamingChatModel でも利用できます。

ツール検索ツール(Tool Search Tool)​

Anthropic の ツール検索ツール は serverTools、ツールの metadata、および toolMetadataKeysToSend パラメータでサポートされます。

高レベル AI Service と @Tool API を使う例:

AnthropicServerTool toolSearchTool = AnthropicServerTool.builder()
.type("tool_search_tool_regex_20251119")
.name("tool_search_tool_regex")
.build();

class Tools {

@Tool(metadata = "{\"defer_loading\": true}")
String getWeather(String location) {
return "sunny";
}

@Tool
String getTime(String location) {
return "12:34:56";
}
}

ChatModel chatModel = AnthropicChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.modelName(CLAUDE_SONNET_4_5_20250929)
.beta("advanced-tool-use-2025-11-20")
.serverTools(toolSearchTool)
.toolMetadataKeysToSend("defer_loading") // need to specify it explicitly
.logRequests(true)
.logResponses(true)
.build();

interface Assistant {

@SystemMessage("Use tool search if needed")
String chat(String userMessage);
}

Assistant assistant = AiServices.builder(Assistant.class)
.chatModel(chatModel)
.tools(new Tools())
.build();

assistant.chat("What is the weather in Munich?");

低レベル ChatModel と ToolSpecification API を使う例:

AnthropicServerTool toolSearchTool = AnthropicServerTool.builder()
.type("tool_search_tool_regex_20251119")
.name("tool_search_tool_regex")
.build();

Map<String, Object> toolMetadata = Map.of("defer_loading", true);

ToolSpecification weatherTool = ToolSpecification.builder()
.name("get_weather")
.parameters(JsonObjectSchema.builder()
.addStringProperty("location")
.required("location")
.build())
.metadata(toolMetadata)
.build();

ToolSpecification timeTool = ToolSpecification.builder()
.name("get_time")
.parameters(JsonObjectSchema.builder()
.addStringProperty("location")
.required("location")
.build())
.build();

ChatModel model = AnthropicChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.modelName(CLAUDE_SONNET_4_5_20250929)
.beta("advanced-tool-use-2025-11-20")
.serverTools(toolSearchTool)
.toolMetadataKeysToSend(toolMetadata.keySet()) // need to specify it explicitly
.logRequests(true)
.logResponses(true)
.build();

ChatRequest chatRequest = ChatRequest.builder()
.messages(UserMessage.from("What is the weather in Munich? Use tool search if needed."))
.toolSpecifications(weatherTool, timeTool)
.build();

ChatResponse chatResponse = model.chat(chatRequest);

プログラマティック・ツール呼び出し(Programmatic Tool Calling)​

Anthropic の プログラマティック・ツール呼び出し は serverTools、ツールの metadata、および toolMetadataKeysToSend パラメータでサポートされます。

高レベル AI Service と @Tool API を使う例:

AnthropicServerTool codeExecutionTool = AnthropicServerTool.builder()
.type("code_execution_20250825")
.name("code_execution")
.build();

class Tools {

static final String TOOL_METADATA = "{\"allowed_callers\": [\"code_execution_20250825\"]}";
static final String TOOL_DESCRIPTION = """
Returns daily minimum and maximum temperatures recorded
for a specified city for a specified number of previous days.
Response format: [{"min":0.0,"max":10.0},{"min":0.0,"max":20.0},{"min":0.0,"max":30.0}]
""";

record TemperatureRange(double min, double max) {}

@Tool(value = TOOL_DESCRIPTION, metadata = TOOL_METADATA)
List<TemperatureRange> getDailyTemperatures(String city, int days) {
if ("Munich".equals(city) && days == 5) {
return List.of(
new TemperatureRange(0.0, 1.0),
new TemperatureRange(0.0, 2.0),
new TemperatureRange(0.0, 3.0),
new TemperatureRange(0.0, 4.0),
new TemperatureRange(0.0, 5.0)
);
}

throw new IllegalArgumentException("Unknown city: " + city + " or days: " + days);
}

@Tool(value = "Calculates the average of the specified list of numbers", metadata = TOOL_METADATA)
Double average(List<Double> numbers) {
return numbers.stream()
.mapToDouble(Double::doubleValue)
.average()
.orElseThrow();
}
}

ChatModel chatModel = AnthropicChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.modelName(CLAUDE_SONNET_4_5_20250929)
.beta("advanced-tool-use-2025-11-20")
.serverTools(codeExecutionTool)
.toolMetadataKeysToSend("allowed_callers") // need to specify it explicitly
.logRequests(true)
.logResponses(true)
.build();

interface Assistant {

String chat(String userMessage);
}

Assistant assistant = AiServices.builder(Assistant.class)
.chatModel(chatModel)
.tools(new Tools())
.build();

assistant.chat("What was the average max temperature in Munich in the last 5 days?");

ツール検索ツール セクションで、低レベルの ToolSpecification API でツールの metadata を指定する例を確認できます。

ツール使用例(Tool Use Examples)​

Anthropic の ツール使用例 はツールの metadata と toolMetadataKeysToSend パラメータでサポートされます。

高レベル AI Service と @Tool API を使う例:

enum Unit {
CELSIUS, FAHRENHEIT
}

class Tools {

// NOTE: if javac "-parameters" option is not enabled, you need to change "location" to "arg0"
// and "unit" to "arg1" inside the TOOL_METADATA to make it work.
public static final String TOOL_METADATA = """
{
"input_examples": [
{
"location": "San Francisco, CA",
"unit": "FAHRENHEIT"
},
{
"location": "Tokyo, Japan",
"unit": "CELSIUS"
},
{
"location": "New York, NY"
}
]
}
""";

@Tool(metadata = TOOL_METADATA)
String getWeather(String location, @P(description = "temperature unit", required = false) Unit unit) {
return "sunny";
}
}

ChatModel chatModel = AnthropicChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.modelName(CLAUDE_SONNET_4_5_20250929)
.beta("advanced-tool-use-2025-11-20")
.toolMetadataKeysToSend("input_examples") // need to specify it explicitly
.logRequests(true)
.logResponses(true)
.build();

interface Assistant {

String chat(String userMessage);
}

Assistant assistant = AiServices.builder(Assistant.class)
.chatModel(chatModel)
.tools(new Tools())
.build();

assistant.chat("What is the weather in Munich in Fahrenheit?");

ツール検索ツール セクションで、低レベルの ToolSpecification API でツールの metadata を指定する例を確認できます。

キャッシュ(Caching)​

Anthropic は、プロンプトの先頭部分(ツール、システムメッセージ、それ以前のメッセージ)をキャッシュできます。これにより、同じ内容で始まる次のリクエストは、再処理せずにキャッシュから読み取ります。キャッシュからの読み取りは同じトークンを再処理するよりはるかに安価で高速ですが、キャッシュへの書き込みは通常の入力トークンより少しコストがかかります。そのため、同じプロンプトのプレフィックスを複数回送信する場合にキャッシュは効果的で、マルチターンの会話、ツールを呼び出す AI Services、エージェントがこれに該当します。

キャッシュはデフォルトで無効です。以下に説明するオプションで、プロンプトの部位ごとに有効にします。Anthropic は、ツール → システムメッセージ → メッセージ の順でキャッシュされた内容を完全一致で照合するため、リクエスト間で変化するもの(たとえば、システムメッセージ内の現在時刻や、異なるツールの集合)があると、それ以降のすべてのキャッシュヒットが妨げられます。モデル固有の最小値(512〜4,096 トークンの間)より短いプロンプトはキャッシュされません。

どのオプションを使うべきか:

  • システムメッセージとツールがリクエスト間で変わらない場合は、必ず cacheSystemMessages と cacheTools を有効にします(下記を参照)。チャットメモリなしの独立した呼び出しを含め、あらゆる使い方で効果があります。
  • 会話履歴が保持され、リクエストごとに増えていく場合(たとえば AI Service やエージェントがループ内でツールを呼び出す場合)は、さらに cacheAutomatically を有効にします(自動キャッシュを参照)。会話の先頭がリクエストごとに変わる場合(たとえばチャットメモリが毎ターン古いメッセージを削除する場合(満杯の MessageWindowChatMemory や TokenWindowChatMemory)や、チャットメモリなしの独立した呼び出し)は有効にしないでください。節約できる以上にコストがかかります。

Anthropic は 1 リクエストあたり最大 4 つのキャッシュブレークポイントを許可します。cacheSystemMessages、cacheTools、cacheAutomatically がそれぞれ 1 つを使用し、cache_control 属性でマークされた各メッセージも 1 つずつ使用します。これを超えるブレークポイントを持つリクエストは Anthropic に拒否されます。

キャッシュされたコンテンツは、キャッシュ TTL の間 Anthropic に保存され、他の組織とは共有されません。詳細はプロンプトキャッシュのドキュメントを参照してください。

AnthropicChatModel と AnthropicStreamingChatModel はレスポンスで AnthropicTokenUsage を返し、 cacheCreationInputTokens(キャッシュに書き込まれたトークン)と cacheReadInputTokens(キャッシュから読み取られたトークン)を含みます。

キャッシュの詳細はこちらを参照してください。

システムメッセージとツールのキャッシュ​

cacheSystemMessages は最後のシステムメッセージに cache_control を付与し、cacheTools は最後のツールに付与します。 ツールはシステムメッセージより前に来るため、システムメッセージのブレークポイントは両方をキャッシュします。 ツールのブレークポイントは、リクエスト間でシステムメッセージが変わっても、ツールをキャッシュされたままに保ちます。

これらのブレークポイントはすべてのリクエストで同じ位置にあるため、システムメッセージとツールが変わらない限り、チャットメモリなしの独立した呼び出しでも効果があります:

ChatModel model = AnthropicChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.modelName("claude-opus-5-5")
.cacheSystemMessages(true)
.cacheTools(true)
.build();

自動キャッシュ(Automatic Caching)​

cacheAutomatically を有効にすると、Anthropic は各リクエストの最後のブロックにキャッシュブレークポイントを置き、会話が進むにつれてそれを前方に移動させるため、各リクエストはそれ以前に送信されたすべての内容をキャッシュから読み取ります。キャッシュ対象のメッセージを手動でマークする必要がないため、メッセージが LangChain4j によって作成される AI Services やエージェントでも機能します。

これが効果を発揮するのは、各リクエストが直前のリクエストで送信されたすべての内容で始まる場合のみです(どのオプションを使うべきかを参照)。そうでない場合、各リクエストはプロンプト全体に対してキャッシュ書き込み料金を支払うだけで何も読み戻されず、キャッシュしないよりもコストがかかります。使用する際は、会話の先頭が変わってもシステムメッセージとツールをキャッシュされたままにするため、cacheSystemMessages と cacheTools も有効にしてください。

次の例では、1 回の assistant.chat(...) 呼び出し内のツール呼び出しごとに会話が増えていくため、同じツールループの後続のリクエストは、それ以前の内容をキャッシュから読み取ります:

ChatModel model = AnthropicChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.modelName("claude-opus-5-5")
.cacheSystemMessages(true)
.cacheTools(true)
.cacheAutomatically(true)
.build();

Assistant assistant = AiServices.builder(Assistant.class)
.chatModel(model)
.tools(new MyTools())
.build();

自動キャッシュは、リクエストのトップレベルの cache_control フィールドとして送信されます。このフィールドをサポートしない Anthropic 互換のゲートウェイやプロキシは、リクエストを拒否するか、フィールドを無視する場合があります。その場合は、代わりにシステムメッセージ、ツール、個々のメッセージをキャッシュしてください。

個別メッセージのキャッシュ​

UserMessage、AiMessage、ToolExecutionResultMessage はそれぞれ、 cache_control 属性を ephemeral に設定することでキャッシュ対象にできます。キャッシュ制御マーカーは自動的に メッセージの最後のコンテンツブロックに適用されます(ToolExecutionResultMessage の場合は tool_result ブロック 自体)。

UserMessage は可変の attributes マップを公開します:

UserMessage userMessage = UserMessage.from("Hello cached world");
userMessage.attributes().put("cache_control", "ephemeral");

AiMessage と ToolExecutionResultMessage は不変の attributes マップを持つため、 toBuilder() 経由で設定します。エージェントのツール実行ループのように、ターンごとに増えていく会話をキャッシュするには、メッセージをマークする必要がない自動キャッシュのほうが簡単です。個々のメッセージのマークは、キャッシュブレークポイントの位置を制御する必要がある場合に便利です。

AiMessage aiMessage = someAiMessage.toBuilder()
.attributes(Map.of("cache_control", "ephemeral"))
.build();

ToolExecutionResultMessage toolExecutionResultMessage = someToolExecutionResultMessage.toBuilder()
.attributes(Map.of("cache_control", "ephemeral"))
.build();

キャッシュ TTL(Cache TTL)​

キャッシュされたコンテンツはデフォルトで 5 分間保持され、キャッシュヒットのたびにこの時間がリフレッシュされます。 同じプロンプトプレフィックスを共有するリクエストの間隔が通常 5 分を超える場合(たとえば、ユーザーが 20 分後に返信する場合や、バッチ処理)、キャッシュを代わりに 1 時間保持できます:

ChatModel model = AnthropicChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.modelName("claude-opus-5-5")
.cacheAutomatically(true)
.cacheTtl("1h") // "5m" by default
.build();

両方の値は、定数 AnthropicChatRequestParameters.CACHE_TTL_5M と AnthropicChatRequestParameters.CACHE_TTL_1H としても利用できます。

TTL は、システムメッセージ、ツール、自動的にキャッシュされるメッセージ、cache_control 属性でマークされたメッセージなど、キャッシュされるすべてのコンテンツに適用されます。これらのうち少なくとも 1 つがキャッシュされていない限り、効果はありません。 1 時間キャッシュへの書き込みは基本入力トークン価格の 2 倍かかります(5 分キャッシュは 1.25 倍)。そのため、キャッシュされたコンテンツが 1 時間以内に少なくとも数回読み取られる場合にのみ効果があります。

キャッシュ診断​

Anthropic の(beta)キャッシュ診断 機能は、プロンプトキャッシュがヒットしなかった理由(モデル、システムプロンプト、ツール、メッセージ履歴の変更)を報告し、 単に cacheReadInputTokens がゼロになったことだけを示すのではありません。

cache-diagnosis-2026-04-07 beta ヘッダーが必要で、returnCacheDiagnostics で有効化します。会話の最初のターンでは previousMessageId に null を渡してオプトインし、以降の各ターンでは前のレスポンスの id を渡します:

AnthropicChatModel model = AnthropicChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.beta("cache-diagnosis-2026-04-07")
.returnCacheDiagnostics(true)
.build();

ChatResponse response1 = model.chat(ChatRequest.builder()
.messages(UserMessage.from("Summarize section 1."))
.build());
String previousMessageId = ((AnthropicChatResponseMetadata) response1.metadata()).id();

ChatResponse response2 = model.chat(ChatRequest.builder()
.messages(UserMessage.from("Summarize section 1."), UserMessage.from("Now summarize section 2."))
.parameters(AnthropicChatRequestParameters.builder()
// returnCacheDiagnostics is already enabled on the model above, so on subsequent turns
// you only need to supply the previousMessageId (it changes every turn).
.previousMessageId(previousMessageId)
.build())
.build());

AnthropicCacheDiagnostics diagnostics = ((AnthropicChatResponseMetadata) response2.metadata()).cacheDiagnostics();
if (diagnostics != null && diagnostics.cacheMissReasonType() != null) {
// e.g. "model_changed", "system_changed", "tools_changed", "messages_changed",
// "previous_message_not_found" or "unavailable"
System.out.println(diagnostics.cacheMissReasonType());
}

診断を要求していない、または不一致が見つからない場合、cacheDiagnostics() は null です。

Thinking​

AnthropicChatModel と AnthropicStreamingChatModel はどちらも 拡張 thinking と 適応的 thinking をサポートします。

次のパラメータで制御します:

  • thinkingType と thinkingBudgetTokens:thinking を有効化。 詳細は こちら。
  • thinkingDisplay:API が thinking シグネチャと並べて読み取り可能な thinking テキストを返すかどうかを制御します。有効な値は "summarized"(thinking ブロックに推論の読み取り可能な要約が含まれる)と "omitted"(thinking ブロックの thinking テキストは空で、暗号化されたシグネチャのみが返される)です。未設定の場合、API はモデルに応じたデフォルトを選びます。最近の Claude モデルのデフォルトは "omitted"、古いモデルは "summarized" です。Anthropic のドキュメントを参照してください。thinking テキスト自体が必要な場合(たとえばエンドユーザーに表示する場合)は、常に "summarized" に設定してください。どちらの場合も、モデルの思考方法と課金は同じで、変わるのは thinking テキストの可視性のみです。
  • returnThinking:利用可能な場合に AiMessage.thinking() 内で thinking を返すか、 AnthropicStreamingChatModel 使用時に StreamingChatResponseHandler.onPartialThinking() と TokenStream.onPartialThinking() のコールバックを呼び出すかも制御します。デフォルトでは無効です。有効にすると、thinking シグネチャも保存され AiMessage.attributes() 内に返されます。API が thinking テキストを返さない場合、AiMessage.thinking() は空のままである点に注意してください。上記の thinkingDisplay を参照してください。
  • sendThinking:後続リクエストで AiMessage に保存された thinking とシグネチャを LLM に送るかを制御。 デフォルト有効。

effort パラメータを設定するには、モデル構築時に customParameters を設定します:

ChatModel model = AnthropicChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.modelName("claude-sonnet-5")
.customParameters(Map.of("output_config", Map.of("effort", "max")))
...
.build();

thinking の設定例:

ChatModel model = AnthropicChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.modelName("claude-sonnet-4-5-20250929")
.thinkingType("enabled")
.thinkingBudgetTokens(1024)
.maxTokens(1024 + 100)
.returnThinking(true)
.sendThinking(true)
.build();

最近の Claude モデルは、thinkingDisplay で要求しない限り thinking テキストを返さないため、 未設定の場合 AiMessage.thinking() は空になります:

ChatModel model = AnthropicChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.modelName("claude-sonnet-5")
.thinkingType("adaptive")
.thinkingDisplay("summarized")
.maxTokens(16000)
.returnThinking(true)
.sendThinking(true)
.build();

会話途中のシステムメッセージ(Mid-Conversation System Messages)​

デフォルトでは、メッセージリスト内の位置に関係なく、すべての SystemMessage がトップレベル system プロンプトに折りたたまれます。 これは Anthropic の従来どおりの動作で、変更ありません。

Claude Opus 4.8 は追加で 会話途中のシステムメッセージ をサポートしています。会話の開始後に現れる SystemMessage を、messages 配列内の system エントリとしてインラインで送信でき、会話のその時点以降に有効になります(たとえば、セッションの途中でアシスタントの指示を変更する場合)。 midConversationSystemMessages(true) で有効化します:

AnthropicChatModel model = AnthropicChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.modelName("claude-opus-4-8")
.midConversationSystemMessages(true)
.build();

ChatResponse response = model.chat(ChatRequest.builder()
.messages(
SystemMessage.from("You are a helpful assistant."), // leading -> top-level "system" prompt
UserMessage.from("Hello"),
AiMessage.from("Hi! How can I help?"),
SystemMessage.from("From now on, answer only in French."), // mid-conversation -> inline
UserMessage.from("What is the capital of Spain?"))
.build());

有効時、先頭の SystemMessage(最初のユーザー/アシスタントメッセージより前のもの)は引き続きトップレベル system プロンプトを埋めます。会話開始後に現れたものだけがインライン送信されます。これは単なる慣習ではなく——Anthropic の要件です: system メッセージは messages 配列の先頭エントリにはできず、 ベースのシステムプロンプトは安定してキャッシュ可能なプレフィックスに置くべきだからです。オプション無効(デフォルト)時は 動作は変わらず、すべての SystemMessage がトップレベル system プロンプトに入ります。

リクエスト単位で AnthropicChatRequestParameters 経由でも設定できます(リクエスト単位のパラメータを参照)。

备注

Anthropic は会話途中のシステムメッセージの配置を制約します:必ず user ターンの直後(ツール結果を含む user ターンも含む)に置き、assistant ターンの前か配列末尾でなければならず、 tool_use ブロックとその tool_result の間に挟んではいけません。連続する system メッセージも不可です。 注意:オプション無効時、langchain4j は複数の SystemMessage をトップレベル system フィールドにマージします。有効にすると、隣接する 2 つの会話途中の SystemMessage が連続したインライン system エントリとして送られ拒否されます。langchain4j はインラインメッセージを並べ替えたりマージしたりせず—— 指定した位置のまま送ります——サポート外モデルや無効な配置は Anthropic API から 400 になります。

PDF サポート​

Anthropic Claude は PDF ドキュメントの処理をサポートします。URL または base64 エンコードデータで PDF を送れます。

URL 経由で PDF を送る​

UserMessage message = UserMessage.from(
PdfFileContent.from(URI.create("https://example.com/document.pdf")),
TextContent.from("What are the key findings in this document?")
);

ChatResponse response = model.chat(message);

Base64 経由で PDF を送る​

String base64Data = Base64.getEncoder().encodeToString(Files.readAllBytes(Path.of("document.pdf")));

UserMessage message = UserMessage.from(
PdfFileContent.from(base64Data, "application/pdf"),
TextContent.from("Summarize this document.")
);

ChatResponse response = model.chat(message);

PDF サポートの詳細は こちら。

カスタムチャットリクエストパラメータの設定​

AnthropicChatModel と AnthropicStreamingChatModel を構築するとき、 HTTP リクエストの JSON ボディ内のチャットリクエストにカスタムパラメータを設定できます。 コンテキスト編集 を有効にする例:

record Edit(String type) {}
record ContextManagement(List<Edit> edits) { }
Map<String, Object> customParameters = Map.of("context_management", new ContextManagement(List.of(new Edit("clear_tool_uses_20250919"))));

ChatModel model = AnthropicChatModel.builder()
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.modelName(CLAUDE_SONNET_4_5_20250929)
.beta("context-management-2025-06-27")
.customParameters(customParameters)
.logRequests(true)
.logResponses(true)
.build();

String answer = model.chat("Hi");

次のボディを持つ HTTP リクエストが生成されます:

{
"model" : "claude-sonnet-4-5-20250929",
"messages" : [ {
"role" : "user",
"content" : [ {
"type" : "text",
"text" : "Hi"
} ]
} ],
"context_management" : {
"edits" : [ {
"type" : "clear_tool_uses_20250919"
} ]
}
}

あるいは、カスタムパラメータをネストした map 構造としても指定できます:

Map<String, Object> customParameters = Map.of(
"context_management",
Map.of("edits", List.of(Map.of("type", "clear_tool_uses_20250919")))
);

生の HTTP レスポンスと Server-Sent Events(SSE)へのアクセス​

AnthropicChatModel 使用時、生の HTTP レスポンスにアクセスできます:

SuccessfulHttpResponse rawHttpResponse = ((AnthropicChatResponseMetadata) chatResponse.metadata()).rawHttpResponse();
System.out.println(rawHttpResponse.body());
System.out.println(rawHttpResponse.headers());
System.out.println(rawHttpResponse.statusCode());

AnthropicStreamingChatModel 使用時は、生の HTTP レスポンス(上記)と生の Server-Sent Events にアクセスできます:

List<ServerSentEvent> rawServerSentEvents = ((AnthropicChatResponseMetadata) chatResponse.metadata()).rawServerSentEvents();
System.out.println(rawServerSentEvents.get(0).data());
System.out.println(rawServerSentEvents.get(0).event());

AnthropicTokenCountEstimator​

TokenCountEstimator tokenCountEstimator = AnthropicTokenCountEstimator.builder()
.modelName(CLAUDE_3_OPUS_20240229)
.apiKey(System.getenv("ANTHROPIC_API_KEY"))
.logRequests(true)
.logResponses(true)
.build();

List<ChatMessage> messages = List.of(...);

int tokenCount = tokenCountEstimator.estimateTokenCountInMessages(messages);

Quarkus​

詳細は こちら。

Spring Boot​

Anthropic 用 Spring Boot starter をインポート:

<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-anthropic-spring-boot4-starter</artifactId>
<version>1.23.0-beta33</version>
</dependency>
备注

この starter には Spring Boot 4 が必要です。Spring Boot 3 では、代わりに langchain4j-anthropic-spring-boot-starter を使用してください。 詳細は Spring Boot 統合を参照してください。

AnthropicChatModel bean を設定:

langchain4j.anthropic.chat-model.api-key = ${ANTHROPIC_API_KEY}

AnthropicStreamingChatModel bean を設定:

langchain4j.anthropic.streaming-chat-model.api-key = ${ANTHROPIC_API_KEY}

例​