---
name: langchain4j-anthropic-sdk
description: "Use when selecting/configuring LangChain4j Anthropic Claude integrations (direct Anthropic API, AWS Bedrock-hosted Claude) including prompt caching, tool use, extended thinking, batch API, and Agent Skills document generation. Do not invoke for broader agent-system design (use langchain4j-agent-design) or general LangChain4j code review (use langchain4j-review)."
allowed-tools: Read, Grep, Glob, Write, Edit, Bash(find * -name "*.java" -o -name "*.kt" -o -name "*.yml" -o -name "*.properties")
---

# LangChain4j Anthropic SDK — Scaffold, Review & Configuration

> **Version baseline**: LangChain4j stable `1.18.1`; `langchain4j-anthropic-spring-boot-starter` uses `1.18.1-beta28`; AWS Bedrock-hosted Claude via `langchain4j-bedrock` `1.18.1`; Spring Boot 3.5+; August 2026

Use this skill only for LangChain4j-mediated Anthropic Claude integrations. Direct `anthropic-sdk-java` clients or raw Messages API code that bypass LangChain4j are out of scope for this skill.

## Step 1 — Understand the project context

Read existing code to match conventions (language, packages, Spring Boot version, existing model provider):

```
!`find . \( -name "pom.xml" -o -name "build.gradle.kts" \) | head -3`
!`find . \( -name "*.java" -o -name "*.kt" \) -path "*anthropic*" -o -path "*claude*" -o -path "*model*" 2>/dev/null | head -15 || echo "no existing AI code"`
!`find . -name "application.yml" -o -name "application.properties" 2>/dev/null | head -3`
```

## Step 2 — Select the integration module

> **No Spring Boot 4 starter exists for Anthropic.** Only `langchain4j-anthropic-spring-boot-starter` (Boot 3.x) is published — for Spring Boot 4 apps, wire `AnthropicChatModel`/`AnthropicStreamingChatModel` as a manual `@Bean` instead.

| Scenario | Module to use | Artifact |
|----------|--------------|----------|
| **Direct Anthropic API + Spring Boot (Boot 3.x)** | Custom REST | `langchain4j-anthropic` + `langchain4j-anthropic-spring-boot-starter` |
| **Direct Anthropic API on Spring Boot 4** | Custom REST | `langchain4j-anthropic` with manual `@Bean` (no starter published) |
| **Extended thinking (Claude reasoning)** | Custom REST | `langchain4j-anthropic` with `thinkingType`/`thinkingBudgetTokens` |
| **Prompt caching (system prompts, tools, long context)** | Custom REST | `langchain4j-anthropic` with `cacheSystemMessages(true)`/`cacheTools(true)` |
| **Async/offline batch processing (cost discount)** | Custom REST | `AnthropicBatchChatModel` |
| **Server-side tools (web search, code execution)** | Custom REST | `langchain4j-anthropic` with `serverTools(...)` |
| **Native document generation (.xlsx/.pptx/.docx/.pdf)** | Custom REST | `langchain4j-anthropic` with `skills(AnthropicSkill...)` — distinct from LangChain4j's own Skills system |
| **AWS Bedrock-hosted Claude** | Bedrock SDK | `langchain4j-bedrock` with `modelId("us.anthropic.claude-...")` |
| **PDF document input (native vision)** | Custom REST | `langchain4j-anthropic` with `PdfFileContent` |

## Step 3 — Generation rules by component

### Anthropic chat model (langchain4j-anthropic)

- `AnthropicChatModel.builder().apiKey(...).modelName("claude-sonnet-4-5-...")` for standard non-streaming
- `AnthropicStreamingChatModel` for streaming; same builder surface
- Core params: `temperature`, `topP`, `topK`, `maxTokens`, `stopSequences`, `timeout`, `maxRetries`, `logRequests`/`logResponses`
- `version` / `beta` for API version headers and opt-in beta features (required for some Skills/tool betas)
- `userId` for per-end-user tracking (Anthropic abuse-monitoring metadata) — never set to a raw PII value
- `customParameters` for pass-through fields not yet modeled by the builder
- Spring Boot: `langchain4j.anthropic.chat-model.*` / `langchain4j.anthropic.streaming-chat-model.*` properties (Boot 3.x only)

### Tool use & server tools

- `toolSpecifications(...)`, `toolChoice(...)`, `toolChoiceName(...)`, `disableParallelToolUse(true)` for tool-calling control
- `serverTools(...)` to enable Anthropic-hosted server-side tools (e.g. web search, code execution) — these run on Anthropic's infrastructure, not locally
- `returnServerToolResults(true)` to surface raw server-tool results to the caller instead of only the final synthesized answer
- `toolMetadataKeysToSend(...)` to control which `@P`/tool metadata keys are forwarded in the request
- `.toolExecutionErrorHandler(...)` for graceful local tool failures — never let raw exceptions reach the model

### Prompt caching

- `cacheSystemMessages(true)` / `cacheTools(true)` — **disabled by default**, must be explicitly opted in
- `returnCacheDiagnostics(true)` to inspect cache read/write/creation token counts in the response metadata
- Cache large static system prompts, tool definitions, or repeated long-context documents — do not cache content that changes every request (cache writes cost more than a cache miss)

### Extended thinking

- `thinkingType("enabled")` + `thinkingBudgetTokens(N)` to enable Claude's extended/reasoning mode
- **`thinkingBudgetTokens` must be strictly less than `maxTokens`** — the Anthropic API rejects requests where the thinking budget meets or exceeds the total token budget; flag this during review
- `returnThinking(true)` to receive thinking blocks in the response; `sendThinking(true)` to resend prior thinking blocks on multi-turn conversations (required for some tool-use + thinking combinations)
- `thinkingDisplay(...)` controls how/whether thinking content is surfaced to the caller
- `midConversationSystemMessages(...)` — only relevant on models that support system messages injected mid-conversation, not just at turn start

### Batch API

- `AnthropicBatchChatModel` for asynchronous, high-volume, non-interactive workloads — submit a batch of requests, poll or retrieve later, cancel or list in-flight batches
- Meaningfully cheaper than synchronous calls but results are not immediate (can take hours) — never use for latency-sensitive request paths
- Use for bulk offline scoring, dataset labeling, or nightly reprocessing jobs

### AWS Bedrock (Claude via Bedrock)

- `BedrockChatModel` / `BedrockStreamingChatModel` — the **same builder class serves every Bedrock-hosted model**, including Claude; there is no Claude-specific Bedrock class
- Select Claude by `modelId(...)` alone, e.g. `modelId("us.anthropic.claude-sonnet-4-20250514-v1:0")` (use the correct region-prefixed inference-profile ID, not the bare model name, for models that require cross-region inference profiles)
- Uses the AWS default credential provider chain — prefer an IAM role in production; never hardcode static AWS keys
- Anthropic-specific builder params (`thinkingType`, `cacheSystemMessages`, `skills`, etc.) do **not** apply on the Bedrock path — Bedrock exposes a provider-agnostic parameter surface

### Structured outputs (AI Service return type)

- Return a POJO, enum, `List<T>`, or primitive from an `@AiService` method — LangChain4j infers the JSON schema and drives extraction via forced tool use under the hood
- Claude has no OpenAI-style native `response_format` JSON mode — do not look for or configure one; the tool-forced extraction path is the correct and only mechanism
- For complex/nested schemas, prefer clear field-level Javadoc or `@Description`-style hints on the POJO so the inferred schema stays unambiguous

### Vision / multimodal (images and PDFs)

- `UserMessage.from(TextContent.from("..."), ImageContent.from(url_or_base64, mimeType))` for image input
- `PdfFileContent.from(url_or_base64)` for native PDF input — Claude reads PDF pages directly (text + visual layout), no external OCR/extraction step needed
- Both URL-based and base64-encoded content are supported for images and PDFs

### Agent Skills (Anthropic-native document generation)

- `skills(AnthropicSkill.XLSX, AnthropicSkill.PPTX, ...)` enables Claude to generate real downloadable `.xlsx`/`.pptx`/`.docx`/`.pdf` files
- Requires the corresponding `beta` header opt-in on the builder — check the current beta identifier before shipping, as beta features can change header names across releases
- **Do not confuse this with LangChain4j's own Skills system** (`langchain4j-skills`, reviewed/scaffolded by `langchain4j-review`/`langchain4j-scaffold`) — that is a LangChain4j-side tool-catalog mechanism (`FileSystemSkillLoader`/`ClassPathSkillLoader` + `Skills.from(...)`); this `skills(...)` builder param is Anthropic's own server-side document-generation capability and has no relation to `SKILL.md` files

## Step 4 — Output requirements

Generate **complete, compilable files**. Each file must include:

1. Package declaration
2. All necessary imports (no wildcards)
3. Class/interface body with all methods implemented
4. Javadoc/KDoc on public API
5. An `application.yml` snippet with all required properties (Boot 3.x path) or a `@Configuration` class with explicit `@Bean`s (Boot 4 / no-starter path)
6. Maven dependency block for the chosen integration module

After generating, list:
- Required environment variables
- AWS setup steps (if using the Bedrock path — region, IAM role/policy, inference-profile ID)
- Any limitations of the chosen integration (e.g., no Spring Boot 4 starter for `langchain4j-anthropic`, no Anthropic-specific builder params on the Bedrock path)

For detailed patterns and full code examples, see [reference.md](reference.md).