---
name: langchain4j-openai-sdk
description: "Use when selecting/configuring LangChain4j OpenAI integrations (custom REST, official openai-java SDK, Azure OpenAI/Foundry) including model/reasoning/Responses API setup. Do not invoke for broader agent-system design (use langchain4j-agent-design), general LangChain4j code review (use langchain4j-review), or Anthropic Claude integrations (use langchain4j-anthropic-sdk)."
allowed-tools: Read, Grep, Glob, Write, Edit, Bash(find * -name "*.java" -o -name "*.kt" -o -name "*.yml" -o -name "*.properties")
---

# LangChain4j OpenAI SDK — Scaffold, Review & Configuration

> **Version baseline**: LangChain4j stable `1.18.1`; beta-tier modules including `langchain4j-open-ai-official` use `1.18.1-beta28`; the wrapper bundles `openai-java` `4.41.0`; direct OpenAI SDK baseline is `openai-java` `4.44.0`; Spring Boot 3.5+ / Spring Boot 4.0.5+; August 2026

Use this skill only for LangChain4j-mediated OpenAI integrations. Direct official SDK clients, Spring Boot starter usage, or raw Responses/Realtime/Images 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 "*openai*" -o -path "*model*" -o -path "*ai*" 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

> **Deprecation notice**: `langchain4j-github-models` is deprecated since 1.10.0.
> For GitHub Models, use `langchain4j-open-ai-official` with `baseUrl("https://models.inference.ai.azure.com")`.

| Scenario | Module to use | Artifact |
|----------|--------------|----------|
| **OpenAI.com + Spring Boot (stable)** | Custom REST | `langchain4j-open-ai` + `langchain4j-open-ai-spring-boot-starter` |
| **Latest models (gpt-5.1, o-series)** | Custom REST or official | `langchain4j-open-ai` (has `reasoning-effort`) |
| **Azure v1 API (`/openai/v1/`)** | Official SDK | `langchain4j-open-ai-official` |
| **GitHub Models** | Official SDK | `langchain4j-open-ai-official` with `.isGitHubModels(true)` (deprecated: `langchain4j-github-models`) |
| **Microsoft Foundry** | Official SDK | `langchain4j-open-ai-official` with `.isMicrosoftFoundry(true)` + `.microsoftFoundryDeploymentName(name)` |
| **Classic Azure (deployment-path + api-version)** | Azure SDK | `langchain4j-azure-open-ai` |
| **Strict tools / strict JSON schema** | Either | Both support `strictTools(true)` |
| **Responses API (sync, cancellation, reasoning summaries, encrypted reasoning)** | Custom REST or official | `OpenAiResponsesStreamingChatModel` / `OpenAiOfficialResponsesChatModel` / `OpenAiOfficialResponsesStreamingChatModel` |
| **Spring Boot 3.x** | Any | `*-spring-boot-starter` suffix |
| **Spring Boot 4.x (4.0.5+)** | Any | `*-spring-boot4-starter` suffix |

## Step 3 — Generation rules by component

### OpenAI chat model (langchain4j-open-ai — custom REST)

- `OpenAiChatModel.builder().apiKey(...).modelName(...)` — standard non-streaming
- Use `defaultRequestParameters(OpenAiChatRequestParameters.builder()...)` for temperature, maxOutputTokens, reasoningEffort
- Add `.supportedCapabilities(Set.of(RESPONSE_FORMAT_JSON_SCHEMA))` when structured outputs are needed
- `OpenAiStreamingChatModel` for streaming; `OpenAiResponsesStreamingChatModel` for Responses API
- Spring Boot: `langchain4j.open-ai.chat-model.*` properties; auto-creates `ChatModel` bean
- **Never set `reasoningEffort` on gpt-4o or standard models — the API will error**
- **Never set `reasoningEffort = "none"` on o1/o3/o4-mini — API rejects it**
- `reasoningEffort` is null by default and `@JsonInclude(NON_EMPTY)` — safe to omit

### OpenAI chat model (langchain4j-open-ai-official — official SDK wrapper)

- `OpenAiOfficialChatModel.builder().apiKey(...).modelName(...)` for standard OpenAI
- `.baseUrl("https://name.openai.azure.com/openai/v1").apiKey(...)` for Azure v1 API (no `microsoftFoundryDeploymentName`)
- `.isGitHubModels(true)` to auto-read `GITHUB_TOKEN` and configure GitHub Models endpoint
  - **`langchain4j-github-models` is deprecated since 1.10.0** — use `isGitHubModels(true)` instead
- `.isMicrosoftFoundry(true)` — required for Entra ID auth when URL has `/openai/v1` suffix (not auto-detected)
- **Microsoft Foundry** (since 1.11.0): Use `isMicrosoftFoundry(true)` + `microsoftFoundryDeploymentName(name)` for Foundry deployments. Do not use `isAzure(true)` for Foundry deployments.
- `.strictTools(true)` and `.strictJsonSchema(true)` for strict structured output enforcement
- `OpenAiOfficialResponsesChatModel` for blocking Responses API calls; `OpenAiOfficialResponsesStreamingChatModel` for streaming/cancellation
- Prefer official Responses models when reasoning summaries, encrypted reasoning, PDF input, or Responses server tools are required
- Do not override the wrapper's managed `openai-java` 4.41.0 with the direct-SDK 4.44.0 baseline unless compatibility tests prove the combined dependency graph.
- No Spring Boot 3 starter — declare as `@Bean` and use `@AiService(wiringMode = EXPLICIT, chatModel = "beanName")`
- **Deprecated:** `isAzure(true)` → `isMicrosoftFoundry(true)`; `azureDeploymentName(...)` → `microsoftFoundryDeploymentName(...)`

### Azure OpenAI (langchain4j-azure-open-ai — classic API)

- `AzureOpenAiChatModel.builder().endpoint(...).apiKey(...).deploymentName(...)`
- Managed Identity: `.tokenCredential(new DefaultAzureCredentialBuilder().build())`
- Spring Boot: `langchain4j.azure-open-ai.chat-model.*`
- **Not compatible with v1 API** — always sends `?api-version=...` and deployment-path URL
- Use this only for existing workloads on the classic Azure OpenAI deployment-path API

### Streaming agent

- `OpenAiStreamingChatModel` → use with `@AiService` returning `TokenStream`
- Controller: return `Flux<ServerSentEvent<String>>` for SSE, consume `TokenStream` in service
- `OpenAiOfficialResponsesStreamingChatModel` → supports `PartialResponseContext.streamingHandle().cancel()`
- `OpenAiOfficialResponsesChatModel` → blocking official Responses API model added in 1.14.0

### Reasoning model integration

- Prefer **Responses API** for reasoning: `OpenAiResponsesStreamingChatModel` or `OpenAiOfficialResponsesStreamingChatModel`
- Use `OpenAiOfficialResponsesChatModel` when synchronous Responses calls need reasoning summaries or encrypted reasoning
- Set `reasoningEffort("low"|"medium"|"high")` via `OpenAiChatRequestParameters`
- Budget `maxOutputTokens` to include reasoning tokens (e.g. 16,000 for complex tasks)

### Structured outputs (AI Service return type)

- Return a POJO, enum, `List<T>`, or primitive from an `@AiService` method — LangChain4j auto-infers JSON schema
- Enable JSON Schema mode: `supportedCapabilities(Set.of(RESPONSE_FORMAT_JSON_SCHEMA))` (custom REST) or `strictJsonSchema(true)` (official SDK)
- For complex schemas, define explicit `ResponseFormat` with `JsonObjectSchema.builder()`

### Embeddings

- `OpenAiEmbeddingModel` / `OpenAiOfficialEmbeddingModel` — same pattern
- Specify `dimensions` to reduce vector size with text-embedding-3-* models (e.g. `768` instead of `1536`)
- For Azure v1: `OpenAiOfficialEmbeddingModel.builder().baseUrl("https://name.openai.azure.com/openai/v1").apiKey(...)`

### Vision / multimodal

- `UserMessage.from(TextContent.from("describe"), ImageContent.from(url))` — URL or base64+MIME
- Supported models: gpt-4o, gpt-4o-mini

## 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
6. Maven dependency block for the chosen integration module

After generating, list:
- Required environment variables
- Azure setup steps (if applicable)
- Any limitations of the chosen integration (e.g., no Spring Boot starter for `langchain4j-open-ai-official`)

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