0
# @langchain/openai
1

2
The @langchain/openai package provides comprehensive LangChain integrations for OpenAI's APIs, including chat models, language models, embeddings, and specialized tools. It supports both OpenAI and Azure OpenAI services with advanced features like structured output, tool calling, streaming, and multimodal interactions.
3

4
## Package Information
5

6
- **Package Name**: @langchain/openai
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @langchain/openai`
10

11
## Core Imports
12

13
```typescript
14
import { ChatOpenAI, OpenAI, OpenAIEmbeddings, DallEAPIWrapper } from "@langchain/openai";
15
import { AzureChatOpenAI, AzureOpenAI, AzureOpenAIEmbeddings } from "@langchain/openai";
16
import { customTool, convertPromptToOpenAI } from "@langchain/openai";
17
import { OpenAIClient, type ClientOptions, toFile } from "@langchain/openai";
18
```
19

20
For CommonJS:
21

22
```javascript
23
const { ChatOpenAI, OpenAI, OpenAIEmbeddings, DallEAPIWrapper } = require("@langchain/openai");
24
const { AzureChatOpenAI, AzureOpenAI, AzureOpenAIEmbeddings } = require("@langchain/openai");
25
const { customTool, convertPromptToOpenAI } = require("@langchain/openai");
26
const { OpenAIClient, ClientOptions, toFile } = require("@langchain/openai");
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { ChatOpenAI } from "@langchain/openai";
33
import { z } from "zod";
34

35
// Basic chat model
36
const chatModel = new ChatOpenAI({
37
  model: "gpt-4o-mini",
38
  temperature: 0,
39
  apiKey: process.env.OPENAI_API_KEY
40
});
41

42
const response = await chatModel.invoke("What is the capital of France?");
43
console.log(response.content);
44

45
// With tool binding
46
const tools = [
47
  {
48
    name: "get_weather",
49
    description: "Get current weather for a location",
50
    schema: z.object({
51
      location: z.string().describe("City name")
52
    })
53
  }
54
];
55

56
const modelWithTools = chatModel.bindTools(tools);
57
const result = await modelWithTools.invoke("What's the weather in Paris?");
58

59
// Structured output
60
const structuredModel = chatModel.withStructuredOutput(
61
  z.object({
62
    answer: z.string(),
63
    confidence: z.number().min(0).max(1)
64
  }),
65
  { name: "Response" }
66
);
67

68
const structured = await structuredModel.invoke("Explain quantum computing briefly");
69
```
70

71
## Architecture
72

73
The @langchain/openai package is built around several key components:
74

75
- **Chat Models**: Modern conversational AI with OpenAI's chat completion models
76
- **Language Models**: Traditional text completion models for legacy use cases
77
- **Embeddings**: Vector representations for semantic similarity and retrieval
78
- **Azure Integration**: Full support for Azure OpenAI services with custom endpoints
79
- **Tools System**: Function calling, built-in tools, and custom tool creation
80
- **Streaming**: Real-time token streaming with usage metadata
81
- **Multimodal**: Support for text, images, and audio in conversations
82

83
## Capabilities
84

85
### Chat Models
86

87
Modern conversational AI models supporting streaming, tools, structured output, and multimodal interactions. Built on OpenAI's Chat Completions API.
88

89
```typescript { .api }
90
class ChatOpenAI<CallOptions extends ChatOpenAICallOptions = ChatOpenAICallOptions> {
91
  constructor(fields?: ChatOpenAIFields & Partial<ChatOpenAIFields>);
92
  
93
  /** Generate a single response */
94
  invoke(input: BaseLanguageModelInput, options?: CallOptions): Promise<BaseMessage>;
95
  
96
  /** Stream response tokens */
97
  stream(input: BaseLanguageModelInput, options?: CallOptions): AsyncIterable<BaseMessageChunk>;
98
  
99
  /** Bind tools to the model */
100
  bindTools(tools: ChatOpenAIToolType[], kwargs?: Partial<CallOptions>): Runnable;
101
  
102
  /** Enable structured output with schema validation */
103
  withStructuredOutput<T>(
104
    outputSchema: z.ZodType<T> | Record<string, any>,
105
    config?: { name?: string; description?: string; method?: "functionCalling" | "jsonMode" }
106
  ): Runnable<BaseLanguageModelInput, T>;
107
}
108
```
109

110
[Chat Models](./chat-models.md)
111

112
### Language Models
113

114
Traditional text completion models for legacy workflows and specific use cases requiring the completions API.
115

116
```typescript { .api }
117
class OpenAI<CallOptions extends OpenAICallOptions = OpenAICallOptions> {
118
  constructor(fields?: OpenAIInput & Partial<OpenAIInput>);
119
  
120
  /** Generate text completions */
121
  _generate(prompts: string[], options: CallOptions): Promise<LLMResult>;
122
  
123
  /** Stream response chunks */
124
  _streamResponseChunks(input: string, options: CallOptions): AsyncIterable<GenerationChunk>;
125
}
126
```
127

128
[Language Models](./language-models.md)
129

130
### Embeddings
131

132
Vector embeddings for semantic similarity, search, and retrieval-augmented generation (RAG) applications.
133

134
```typescript { .api }
135
class OpenAIEmbeddings {
136
  constructor(fields?: Partial<OpenAIEmbeddingsParams>);
137
  
138
  /** Embed multiple documents */
139
  embedDocuments(texts: string[]): Promise<number[][]>;
140
  
141
  /** Embed a single query */
142
  embedQuery(text: string): Promise<number[]>;
143
}
144
```
145

146
[Embeddings](./embeddings.md)
147

148
### Azure Integration
149

150
Complete Azure OpenAI service support with custom endpoints, API versions, and authentication methods including Azure AD.
151

152
```typescript { .api }
153
class AzureChatOpenAI<CallOptions extends ChatOpenAICallOptions = ChatOpenAICallOptions> 
154
  extends ChatOpenAI<CallOptions> {
155
  constructor(fields?: AzureOpenAIInput & ChatOpenAIFields);
156
}
157
```
158

159
[Azure Integration](./azure-integration.md)
160

161
### Tools
162

163
Image generation with DALL-E and custom tool creation for the OpenAI Responses API.
164

165
```typescript { .api }
166
class DallEAPIWrapper {
167
  constructor(fields?: Partial<DallEAPIWrapperParams>);
168
  
169
  /** Generate images from text descriptions */
170
  _call(input: string): Promise<string>;
171
}
172

173
/** Create custom tools for Responses API */
174
function customTool<T extends Record<string, any>>(
175
  func: RunnableFunc<string, string, ToolRunnableConfig>,
176
  fields: CustomToolFields<T>
177
): CustomTool<T>;
178
```
179

180
[Tools](./tools.md)
181

182
### Types and Configuration
183

184
Comprehensive type system covering all configuration options, call parameters, and response formats.
185

186
```typescript { .api }
187
interface ChatOpenAICallOptions extends BaseChatOpenAICallOptions {
188
  tools?: ChatOpenAIToolType[];
189
  tool_choice?: OpenAIToolChoice | ResponsesToolChoice;
190
  response_format?: ChatOpenAIResponseFormat;
191
  seed?: number;
192
  stream_options?: OpenAIClient.Chat.ChatCompletionStreamOptions;
193
  parallel_tool_calls?: boolean;
194
  strict?: boolean;
195
  modalities?: Array<OpenAIClient.Chat.ChatCompletionModality>;
196
  audio?: OpenAIClient.Chat.ChatCompletionAudioParam;
197
}
198
```
199

200
[Types and Configuration](./types-and-configuration.md)
201

202
### Utilities
203

204
Utility functions for interoperability and advanced use cases.
205

206
```typescript { .api }
207
/**
208
 * Convert LangChain prompt to OpenAI format
209
 * Useful for direct OpenAI SDK interoperability
210
 */
211
function convertPromptToOpenAI(formattedPrompt: BasePromptValue): {
212
  messages: OpenAI.Chat.ChatCompletionMessageParam[];
213
};
214
```
215

216
#### Usage Example
217

218
```typescript
219
import { convertPromptToOpenAI } from "@langchain/openai";
220
import { pull } from "langchain/hub";
221
import OpenAI from 'openai';
222

223
// Pull a prompt from LangChain Hub
224
const prompt = await pull("jacob/joke-generator");
225
const formattedPrompt = await prompt.invoke({
226
  topic: "cats",
227
});
228

229
// Convert to OpenAI format
230
const { messages } = convertPromptToOpenAI(formattedPrompt);
231

232
// Use directly with OpenAI SDK
233
const openAIClient = new OpenAI();
234
const openaiResponse = await openAIClient.chat.completions.create({
235
  model: "gpt-4o-mini",
236
  messages,
237
});
238
```