> ## Documentation Index
> Fetch the complete documentation index at: https://langchain.idochub.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# ChatOpenAI
This guide provides a quick overview for getting started with OpenAI [chat models](/oss/python/langchain/models). For detailed documentation of all ChatOpenAI features and configurations head to the [API reference](https://python.langchain.com/api_reference/openai/chat_models/langchain_openai.chat_models.base.ChatOpenAI.html).
OpenAI has several chat models. You can find information about their latest models and their costs, context windows, and supported input types in the [OpenAI docs](https://platform.openai.com/docs/models).
**Azure OpenAI**
Note that certain OpenAI models can also be accessed via the [Microsoft Azure platform](https://azure.microsoft.com/en-us/products/ai-services/openai-service). To use the Azure OpenAI service use the [AzureChatOpenAI integration](/oss/python/integrations/chat/azure_chat_openai/).
## Overview
### Integration details
| Class | Package | Local | Serializable | [JS support](https://js.langchain.com/docs/integrations/chat/openai) | Downloads | Version |
| :---------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------- | :---: | :----------: | :------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------: |
| [ChatOpenAI](https://python.langchain.com/api_reference/openai/chat_models/langchain_openai.chat_models.base.ChatOpenAI.html) | [langchain-openai](https://python.langchain.com/api_reference/openai/index.html) | ❌ | beta | ✅ |  |  |
### Model features
| [Tool calling](/oss/python/langchain/tools) | [Structured output](/oss/python/langchain/structured-output) | JSON mode | Image input | Audio input | Video input | [Token-level streaming](/oss/python/langchain/streaming/) | Native async | [Token usage](/oss/python/how-to/chat_token_usage_tracking/) | [Logprobs](/oss/python/how-to/logprobs/) |
| :-----------------------------------------: | :----------------------------------------------------------: | :-------: | :---------: | :---------: | :---------: | :-------------------------------------------------------: | :----------: | :----------------------------------------------------------: | :--------------------------------------: |
| ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ |
## Setup
To access OpenAI models you'll need to create an OpenAI account, get an API key, and install the `langchain-openai` integration package.
### Credentials
Head to [platform.openai.com](https://platform.openai.com) to sign up to OpenAI and generate an API key. Once you've done this set the OPENAI\_API\_KEY environment variable:
```python theme={null}
import getpass
import os
if not os.environ.get("OPENAI_API_KEY"):
os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter your OpenAI API key: ")
```
If you want to get automated tracing of your model calls you can also set your [LangSmith](https://docs.smith.langchain.com/) API key by uncommenting below:
```python theme={null}
# os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ")
# os.environ["LANGSMITH_TRACING"] = "true"
```
### Installation
The LangChain OpenAI integration lives in the `langchain-openai` package:
```python theme={null}
%pip install -qU langchain-openai
```
## Instantiation
Now we can instantiate our model object and generate chat completions:
```python theme={null}
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="gpt-5-nano",
# stream_usage=True,
# temperature=None,
# max_tokens=None,
# timeout=None,
# reasoning_effort="low",
# max_retries=2,
# api_key="...", # if you prefer to pass api key in directly instaed of using env vars
# base_url="...",
# organization="...",
# other params...
)
```
See [API Reference](https://python.langchain.com/api_reference/openai/chat_models/langchain_openai.chat_models.base.ChatOpenAI.html)
for the full set of available parameters.
## Invocation
```python theme={null}
messages = [
(
"system",
"You are a helpful assistant that translates English to French. Translate the user sentence.",
),
("human", "I love programming."),
]
ai_msg = llm.invoke(messages)
ai_msg
```
```output theme={null}
AIMessage(content="J'adore la programmation.", additional_kwargs={'refusal': None}, response_metadata={'token_usage': {'completion_tokens': 5, 'prompt_tokens': 31, 'total_tokens': 36}, 'model_name': 'gpt-4o-2024-05-13', 'system_fingerprint': 'fp_3aa7262c27', 'finish_reason': 'stop', 'logprobs': None}, id='run-63219b22-03e3-4561-8cc4-78b7c7c3a3ca-0', usage_metadata={'input_tokens': 31, 'output_tokens': 5, 'total_tokens': 36})
```
```python theme={null}
print(ai_msg.text)
```
```output theme={null}
J'adore la programmation.
```
## Chaining
We can [chain](/oss/python/how-to/sequence/) our model with a prompt template like so:
```python theme={null}
from langchain_core.prompts import ChatPromptTemplate
prompt = ChatPromptTemplate.from_messages(
[
(
"system",
"You are a helpful assistant that translates {input_language} to {output_language}.",
),
("human", "{input}"),
]
)
chain = prompt | llm
chain.invoke(
{
"input_language": "English",
"output_language": "German",
"input": "I love programming.",
}
)
```
```output theme={null}
AIMessage(content='Ich liebe das Programmieren.', additional_kwargs={'refusal': None}, response_metadata={'token_usage': {'completion_tokens': 6, 'prompt_tokens': 26, 'total_tokens': 32}, 'model_name': 'gpt-4o-2024-05-13', 'system_fingerprint': 'fp_3aa7262c27', 'finish_reason': 'stop', 'logprobs': None}, id='run-350585e1-16ca-4dad-9460-3d9e7e49aaf1-0', usage_metadata={'input_tokens': 26, 'output_tokens': 6, 'total_tokens': 32})
```
## Streaming usage metadata
OpenAI's Chat Completions API does not stream token usage statistics by default
(see API reference
[here](https://platform.openai.com/docs/api-reference/completions/create#completions-create-stream_options)).
To recover token counts when streaming with `ChatOpenAI` or `AzureChatOpenAI`, set
`stream_usage=True` as an initialization parameter or on invocation:
```python highlight={3} theme={null}
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4.1-mini", stream_usage=True)
```
## Tool calling
OpenAI has a [tool calling](https://platform.openai.com/docs/guides/function-calling) (we use "tool calling" and "function calling" interchangeably here) API that lets you describe tools and their arguments, and have the model return a JSON object with a tool to invoke and the inputs to that tool. tool-calling is extremely useful for building tool-using chains and agents, and for getting structured outputs from models more generally.
### ChatOpenAI.bind\_tools()
With `ChatOpenAI.bind_tools`, we can easily pass in Pydantic classes, dict schemas, LangChain tools, or even functions as tools to the model. Under the hood these are converted to an OpenAI tool schemas, which looks like:
```
{
"name": "...",
"description": "...",
"parameters": {...} # JSONSchema
}
```
and passed in every model invocation.
```python theme={null}
from pydantic import BaseModel, Field
class GetWeather(BaseModel):
"""Get the current weather in a given location"""
location: str = Field(..., description="The city and state, e.g. San Francisco, CA")
llm_with_tools = llm.bind_tools([GetWeather])
```
```python theme={null}
ai_msg = llm_with_tools.invoke(
"what is the weather like in San Francisco",
)
ai_msg
```
```output theme={null}
AIMessage(content='', additional_kwargs={'refusal': None}, response_metadata={'token_usage': {'completion_tokens': 17, 'prompt_tokens': 68, 'total_tokens': 85}, 'model_name': 'gpt-4o-2024-05-13', 'system_fingerprint': 'fp_3aa7262c27', 'finish_reason': 'tool_calls', 'logprobs': None}, id='run-1617c9b2-dda5-4120-996b-0333ed5992e2-0', tool_calls=[{'name': 'GetWeather', 'args': {'location': 'San Francisco, CA'}, 'id': 'call_o9udf3EVOWiV4Iupktpbpofk', 'type': 'tool_call'}], usage_metadata={'input_tokens': 68, 'output_tokens': 17, 'total_tokens': 85})
```
### `strict=True`
**Requires `langchain-openai>=0.1.21`**
As of Aug 6, 2024, OpenAI supports a `strict` argument when calling tools that will enforce that the tool argument schema is respected by the model. See more here: [platform.openai.com/docs/guides/function-calling](https://platform.openai.com/docs/guides/function-calling)
**Note**: If `strict=True` the tool definition will also be validated, and a subset of JSON schema are accepted. Crucially, schema cannot have optional args (those with default values). Read the full docs on what types of schema are supported here: [platform.openai.com/docs/guides/structured-outputs/supported-schemas](https://platform.openai.com/docs/guides/structured-outputs/supported-schemas).
```python theme={null}
llm_with_tools = llm.bind_tools([GetWeather], strict=True)
ai_msg = llm_with_tools.invoke(
"what is the weather like in San Francisco",
)
ai_msg
```
```output theme={null}
AIMessage(content='', additional_kwargs={'tool_calls': [{'id': 'call_jUqhd8wzAIzInTJl72Rla8ht', 'function': {'arguments': '{"location":"San Francisco, CA"}', 'name': 'GetWeather'}, 'type': 'function'}], 'refusal': None}, response_metadata={'token_usage': {'completion_tokens': 17, 'prompt_tokens': 68, 'total_tokens': 85}, 'model_name': 'gpt-4o-2024-05-13', 'system_fingerprint': 'fp_3aa7262c27', 'finish_reason': 'tool_calls', 'logprobs': None}, id='run-5e3356a9-132d-4623-8e73-dd5a898cf4a6-0', tool_calls=[{'name': 'GetWeather', 'args': {'location': 'San Francisco, CA'}, 'id': 'call_jUqhd8wzAIzInTJl72Rla8ht', 'type': 'tool_call'}], usage_metadata={'input_tokens': 68, 'output_tokens': 17, 'total_tokens': 85})
```
### AIMessage.tool\_calls
Notice that the AIMessage has a `tool_calls` attribute. This contains in a standardized ToolCall format that is model-provider agnostic.
```python theme={null}
ai_msg.tool_calls
```
```output theme={null}
[{'name': 'GetWeather',
'args': {'location': 'San Francisco, CA'},
'id': 'call_jUqhd8wzAIzInTJl72Rla8ht',
'type': 'tool_call'}]
```
For more on binding tools and tool call outputs, head to the [tool calling](/oss/python/how-to/function_calling) docs.
### Structured output and tool calls
OpenAI's [structured output](https://platform.openai.com/docs/guides/structured-outputs) feature can be used simultaneously with tool-calling. The model will either generate tool calls or a response adhering to a desired schema. See example below:
```python theme={null}
from langchain_openai import ChatOpenAI
from pydantic import BaseModel
def get_weather(location: str) -> None:
"""Get weather at a location."""
return "It's sunny."
class OutputSchema(BaseModel):
"""Schema for response."""
answer: str
justification: str
llm = ChatOpenAI(model="gpt-4.1")
structured_llm = llm.bind_tools(
[get_weather],
response_format=OutputSchema,
strict=True,
)
# Response contains tool calls:
tool_call_response = structured_llm.invoke("What is the weather in SF?")
# structured_response.additional_kwargs["parsed"] contains parsed output
structured_response = structured_llm.invoke(
"What weighs more, a pound of feathers or a pound of gold?"
)
```
### Custom tools
**Requires `langchain-openai>=0.3.29`**
[Custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) support tools with arbitrary string inputs. They can be particularly useful when you expect your string arguments to be long or complex.
```python theme={null}
from langchain_openai import ChatOpenAI, custom_tool
from langchain.agents import create_agent
@custom_tool
def execute_code(code: str) -> str:
"""Execute python code."""
return "27"
llm = ChatOpenAI(model="gpt-5", use_responses_api=True)
agent = create_agent(llm, [execute_code])
input_message = {"role": "user", "content": "Use the tool to calculate 3^3."}
for step in agent.stream(
{"messages": [input_message]},
stream_mode="values",
):
step["messages"][-1].pretty_print()
```
```output theme={null}
================================ Human Message =================================
Use the tool to calculate 3^3.
================================== Ai Message ==================================
[{'id': 'rs_68b7336cb72081a080da70bf5e980e4e0d6082d28f91357a', 'summary': [], 'type': 'reasoning'}, {'call_id': 'call_qyKsJ4XlGRudbIJDrXVA2nQa', 'input': 'print(3**3)', 'name': 'execute_code', 'type': 'custom_tool_call', 'id': 'ctc_68b7336f718481a0b39584cd35fbaa5d0d6082d28f91357a', 'status': 'completed'}]
Tool Calls:
execute_code (call_qyKsJ4XlGRudbIJDrXVA2nQa)
Call ID: call_qyKsJ4XlGRudbIJDrXVA2nQa
Args:
__arg1: print(3**3)
================================= Tool Message =================================
Name: execute_code
[{'type': 'custom_tool_call_output', 'output': '27'}]
================================== Ai Message ==================================
[{'type': 'text', 'text': '27', 'annotations': [], 'id': 'msg_68b73371e9e081a0927f54f88f2cd7a20d6082d28f91357a'}]
```
OpenAI supports the specification of a [context-free grammar](https://platform.openai.com/docs/guides/function-calling#context-free-grammars) for custom tool inputs in `lark` or `regex` format. See [OpenAI docs](https://platform.openai.com/docs/guides/function-calling#context-free-grammars) for details. The `format` parameter can be passed into `@custom_tool` as shown below:
```python highlight={20} theme={null}
from langchain_openai import ChatOpenAI, custom_tool
from langchain.agents import create_agent
grammar = """
start: expr
expr: term (SP ADD SP term)* -> add
| term
term: factor (SP MUL SP factor)* -> mul
| factor
factor: INT
SP: " "
ADD: "+"
MUL: "*"
%import common.INT
"""
format_ = {"type": "grammar", "syntax": "lark", "definition": grammar}
@custom_tool(format=format_)
def do_math(input_string: str) -> str:
"""Do a mathematical operation."""
return "27"
llm = ChatOpenAI(model="gpt-5", use_responses_api=True)
agent = create_agent(llm, [do_math])
input_message = {"role": "user", "content": "Use the tool to calculate 3^3."}
for step in agent.stream(
{"messages": [input_message]},
stream_mode="values",
):
step["messages"][-1].pretty_print()
```
```output theme={null}
================================ Human Message =================================
Use the tool to calculate 3^3.
================================== Ai Message ==================================
[{'id': 'rs_68b733f066a48194a41001c0cc1081760811f11b6f4bae47', 'summary': [], 'type': 'reasoning'}, {'call_id': 'call_7hTYtlTj9NgWyw8AQGqETtV9', 'input': '3 * 3 * 3', 'name': 'do_math', 'type': 'custom_tool_call', 'id': 'ctc_68b733f3a0a08194968b8338d33ad89f0811f11b6f4bae47', 'status': 'completed'}]
Tool Calls:
do_math (call_7hTYtlTj9NgWyw8AQGqETtV9)
Call ID: call_7hTYtlTj9NgWyw8AQGqETtV9
Args:
__arg1: 3 * 3 * 3
================================= Tool Message =================================
Name: do_math
[{'type': 'custom_tool_call_output', 'output': '27'}]
================================== Ai Message ==================================
[{'type': 'text', 'text': '27', 'annotations': [], 'id': 'msg_68b733f4bb008194937130796372bd0f0811f11b6f4bae47'}]
```
## Responses API
**Requires `langchain-openai>=0.3.9`**
OpenAI supports a [Responses](https://platform.openai.com/docs/guides/responses-vs-chat-completions) API that is oriented toward building [agentic](/oss/python/langchain/agents) applications. It includes a suite of [built-in tools](https://platform.openai.com/docs/guides/tools?api-mode=responses), including web and file search. It also supports management of [conversation state](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses), allowing you to continue a conversational thread without explicitly passing in previous messages, as well as the output from [reasoning processes](https://platform.openai.com/docs/guides/reasoning?api-mode=responses).
`ChatOpenAI` will route to the Responses API if one of these features is used. You can also specify `use_responses_api=True` when instantiating `ChatOpenAI`.
### Web search
To trigger a web search, pass `{"type": "web_search_preview"}` to the model as you would another tool.
**You can also pass built-in tools as invocation params:**
```python theme={null}
llm.invoke("...", tools=[{"type": "web_search_preview"}])
```
```python theme={null}
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4.1-mini")
tool = {"type": "web_search_preview"}
llm_with_tools = llm.bind_tools([tool])
response = llm_with_tools.invoke("What was a positive news story from today?")
```
Note that the response includes structured [content blocks](/oss/python/langchain/messages/#content-1) that include both the text of the response and OpenAI [annotations](https://platform.openai.com/docs/guides/tools-web-search?api-mode=responses#output-and-citations) citing its sources. The output message will also contain information from any tool invocations:
```python theme={null}
response.content_blocks
```
```output theme={null}
[{'type': 'web_search_call',
'id': 'ws_68af6ac605848195b7ce59c3293b59100cd6678a2b812fed',
'query': 'positive news stories today',
'action': {'query': 'positive news stories today', 'type': 'search'},
'status': 'completed'},
{'type': 'web_search_result',
'id': 'ws_68af6ac605848195b7ce59c3293b59100cd6678a2b812fed'},
{'type': 'text',
'text': 'Here are some positive news stories from today...',
'annotations': [{'end_index': 587,
'start_index': 484,
'title': 'Positive News Highlights | AI, PFAS Breakthroughs & More — August 2025 — Podego',
'type': 'citation',
'url': 'https://www.podego.com/insights/august-2025-good-news-ai-pfas-stories?utm_source=openai'},
{'end_index': 3335,
'start_index': 3155,
'title': '7 stories of optimism this week (19.08.25-25.08.25) - Conservation Optimism',
'type': 'citation',
'url': 'https://conservationoptimism.org/7-stories-of-optimism-this-week-19-08-25-25-08-25/?utm_source=openai'}],
'id': 'msg_68af6ac75aa881958de4d8758b251c860cd6678a2b812fed'}]
```
**You can recover just the text content of the response as a string by using `response.text`. For example, to stream response text:**
```python theme={null}
for token in llm_with_tools.stream("..."):
print(token.text, end="|")
```
See the [streaming guide](/oss/python/langchain/streaming/) for more detail.
### Image generation
**Requires `langchain-openai>=0.3.19`**
To trigger an image generation, pass `{"type": "image_generation"}` to the model as you would another tool.
You can also pass built-in tools as invocation params:
```python theme={null}
llm.invoke("...", tools=[{"type": "image_generation"}])
```
```python theme={null}
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4.1-mini")
tool = {"type": "image_generation", "quality": "low"}
llm_with_tools = llm.bind_tools([tool])
ai_message = llm_with_tools.invoke(
"Draw a picture of a cute fuzzy cat with an umbrella"
)
```
```python theme={null}
import base64
from IPython.display import Image
image = next(
item for item in ai_message.content_blocks if item["type"] == "image"
)
Image(base64.b64decode(image["base64"]), width=200)
```
### File search
To trigger a file search, pass a [file search tool](https://platform.openai.com/docs/guides/tools-file-search) to the model as you would another tool. You will need to populate an OpenAI-managed vector store and include the vector store ID in the tool definition. See [OpenAI documentation](https://platform.openai.com/docs/guides/tools-file-search) for more detail.
```python theme={null}
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4.1-mini")
openai_vector_store_ids = [
"vs_...", # your IDs here
]
tool = {
"type": "file_search",
"vector_store_ids": openai_vector_store_ids,
}
llm_with_tools = llm.bind_tools([tool])
response = llm_with_tools.invoke("What is deep research by OpenAI?")
print(response.text)
```
```output theme={null}
Deep Research by OpenAI is...
```
As with [web search](#web-search), the response will include content blocks with citations:
```python theme={null}
for block in response.content_blocks:
if block["type"] == "non_standard":
print(block["value"].get("type"))
else:
print(block["type"])
```
```output theme={null}
file_search_call
text
```
```python theme={null}
text_block = next(block for block in response.content_blocks if block["type"] == "text")
text_block["annotations"][:2]
```
```output theme={null}
[{'type': 'citation',
'title': 'deep_research_blog.pdf',
'extras': {'file_id': 'file-3UzgX7jcC8Dt9ZAFzywg5k', 'index': 2712}},
{'type': 'citation',
'title': 'deep_research_blog.pdf',
'extras': {'file_id': 'file-3UzgX7jcC8Dt9ZAFzywg5k', 'index': 2712}}]
```
It will also include information from the built-in tool invocations:
```python theme={null}
response.content[0]
```
```output theme={null}
{'id': 'fs_685d9e7d48408191b9e34ad359069ede019138cfaaf3cea8',
'queries': ['deep research by OpenAI'],
'status': 'completed',
'type': 'file_search_call'}
```
### Computer use
`ChatOpenAI` supports the `"computer-use-preview"` model, which is a specialized model for the built-in computer use tool. To enable, pass a [computer use tool](https://platform.openai.com/docs/guides/tools-computer-use) as you would pass another tool.
Currently, tool outputs for computer use are present in the message `content` field. To reply to the computer use tool call, construct a `ToolMessage` with `{"type": "computer_call_output"}` in its `additional_kwargs`. The content of the message will be a screenshot. Below, we demonstrate a simple example.
First, load two screenshots:
```python theme={null}
import base64
def load_png_as_base64(file_path):
with open(file_path, "rb") as image_file:
encoded_string = base64.b64encode(image_file.read())
return encoded_string.decode("utf-8")
screenshot_1_base64 = load_png_as_base64(
"/path/to/screenshot_1.png"
) # perhaps a screenshot of an application
screenshot_2_base64 = load_png_as_base64(
"/path/to/screenshot_2.png"
) # perhaps a screenshot of the Desktop
```
```python theme={null}
from langchain_openai import ChatOpenAI
# Initialize model
llm = ChatOpenAI(model="computer-use-preview", truncation="auto")
# Bind computer-use tool
tool = {
"type": "computer_use_preview",
"display_width": 1024,
"display_height": 768,
"environment": "browser",
}
llm_with_tools = llm.bind_tools([tool])
# Construct input message
input_message = {
"role": "user",
"content": [
{
"type": "text",
"text": (
"Click the red X to close and reveal my Desktop. "
"Proceed, no confirmation needed."
),
},
{
"type": "input_image",
"image_url": f"data:image/png;base64,{screenshot_1_base64}",
},
],
}
# Invoke model
response = llm_with_tools.invoke(
[input_message],
reasoning={
"generate_summary": "concise",
},
)
```
The response will include a call to the computer-use tool in its `content`:
```python theme={null}
response.content
```
```output theme={null}
[{'id': 'rs_685da051742c81a1bb35ce46a9f3f53406b50b8696b0f590',
'summary': [{'text': "Clicking red 'X' to show desktop",
'type': 'summary_text'}],
'type': 'reasoning'},
{'id': 'cu_685da054302481a1b2cc43b56e0b381706b50b8696b0f590',
'action': {'button': 'left', 'type': 'click', 'x': 14, 'y': 38},
'call_id': 'call_zmQerFBh4PbBE8mQoQHkfkwy',
'pending_safety_checks': [],
'status': 'completed',
'type': 'computer_call'}]
```
We next construct a ToolMessage with these properties:
1. It has a `tool_call_id` matching the `call_id` from the computer-call.
2. It has `{"type": "computer_call_output"}` in its `additional_kwargs`.
3. Its content is either an `image_url` or an `input_image` output block (see [OpenAI docs](https://platform.openai.com/docs/guides/tools-computer-use#5-repeat) for formatting).
```python theme={null}
from langchain_core.messages import ToolMessage
tool_call_id = next(
item["call_id"] for item in response.content if item["type"] == "computer_call"
)
tool_message = ToolMessage(
content=[
{
"type": "input_image",
"image_url": f"data:image/png;base64,{screenshot_2_base64}",
}
],
# content=f"data:image/png;base64,{screenshot_2_base64}", # <-- also acceptable
tool_call_id=tool_call_id,
additional_kwargs={"type": "computer_call_output"},
)
```
We can now invoke the model again using the message history:
```python theme={null}
messages = [
input_message,
response,
tool_message,
]
response_2 = llm_with_tools.invoke(
messages,
reasoning={
"generate_summary": "concise",
},
)
```
```python theme={null}
response_2.text
```
```output theme={null}
'VS Code has been closed, and the desktop is now visible.'
```
Instead of passing back the entire sequence, we can also use the [previous\_response\_id](#passing-previous_response_id):
```python theme={null}
previous_response_id = response.response_metadata["id"]
response_2 = llm_with_tools.invoke(
[tool_message],
previous_response_id=previous_response_id,
reasoning={
"generate_summary": "concise",
},
)
```
```python theme={null}
response_2.text
```
```output theme={null}
'The VS Code window is closed, and the desktop is now visible. Let me know if you need any further assistance.'
```
### Code interpreter
OpenAI implements a [code interpreter](https://platform.openai.com/docs/guides/tools-code-interpreter) tool to support the sandboxed generation and execution of code.
Example use:
```python theme={null}
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4.1-mini")
llm_with_tools = llm.bind_tools(
[
{
"type": "code_interpreter",
# Create a new container
"container": {"type": "auto"},
}
]
)
response = llm_with_tools.invoke(
"Write and run code to answer the question: what is 3^3?"
)
```
Note that the above command created a new container. We can also specify an existing container ID:
```python highlight={5,12} theme={null}
code_interpreter_calls = [
item for item in response.content if item["type"] == "code_interpreter_call"
]
assert len(code_interpreter_calls) == 1
container_id = code_interpreter_calls[0]["extras"]["container_id"]
llm_with_tools = llm.bind_tools(
[
{
"type": "code_interpreter",
# Use an existing container
"container": container_id,
}
]
)
```
### Remote MCP
OpenAI implements a [remote MCP](https://platform.openai.com/docs/guides/tools-remote-mcp) tool that allows for model-generated calls to MCP servers.
Example use:
```python theme={null}
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4.1-mini")
llm_with_tools = llm.bind_tools(
[
{
"type": "mcp",
"server_label": "deepwiki",
"server_url": "https://mcp.deepwiki.com/mcp",
"require_approval": "never",
}
]
)
response = llm_with_tools.invoke(
"What transport protocols does the 2025-03-26 version of the MCP "
"spec (modelcontextprotocol/modelcontextprotocol) support?"
)
```
OpenAI will at times request approval before sharing data with a remote MCP server.
In the above command, we instructed the model to never require approval. We can also configure the model to always request approval, or to always request approval for specific tools:
```python theme={null}
llm_with_tools = llm.bind_tools(
[
{
"type": "mcp",
"server_label": "deepwiki",
"server_url": "https://mcp.deepwiki.com/mcp",
"require_approval": {
"always": {
"tool_names": ["read_wiki_structure"]
}
}
}
]
)
response = llm_with_tools.invoke(
"What transport protocols does the 2025-03-26 version of the MCP "
"spec (modelcontextprotocol/modelcontextprotocol) support?"
)
```
Responses may then include blocks with type `"mcp_approval_request"`.
To submit approvals for an approval request, structure it into a content block in an input message:
```python theme={null}
approval_message = {
"role": "user",
"content": [
{
"type": "mcp_approval_response",
"approve": True,
"approval_request_id": block["id"],
}
for block in response.content
if block["type"] == "mcp_approval_request"
]
}
next_response = llm_with_tools.invoke(
[approval_message],
# continue existing thread
previous_response_id=response.response_metadata["id"]
)
```
### Managing conversation state
The Responses API supports management of [conversation state](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses).
#### Manually manage state
You can manage the state manually or using [LangGraph](/oss/python/tutorials/chatbot/), as with other chat models:
```python theme={null}
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4.1-mini", use_responses_api=True)
first_query = "Hi, I'm Bob."
messages = [{"role": "user", "content": first_query}]
response = llm.invoke(messages)
print(response.text)
```
```output theme={null}
Hi Bob! Nice to meet you. How can I assist you today?
```
```python theme={null}
second_query = "What is my name?"
messages.extend(
[
response,
{"role": "user", "content": second_query},
]
)
second_response = llm.invoke(messages)
print(second_response.text)
```
```output theme={null}
You mentioned that your name is Bob. How can I assist you further, Bob?
```
**You can use [LangGraph](https://langchain-ai.github.io/langgraph/) to manage conversational threads for you in a variety of backends, including in-memory and Postgres. See [this tutorial](/oss/python/tutorials/chatbot/) to get started.**
#### Passing `previous_response_id`
When using the Responses API, LangChain messages will include an `"id"` field in its metadata. Passing this ID to subsequent invocations will continue the conversation. Note that this is [equivalent](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses#openai-apis-for-conversation-state) to manually passing in messages from a billing perspective.
```python highlight={3} theme={null}
second_response = llm.invoke(
"What is my name?",
previous_response_id=response.id,
)
print(second_response.text)
```
```output theme={null}
Your name is Bob. How can I help you today, Bob?
```
ChatOpenAI can also automatically specify `previous_response_id` using the last response in a message sequence:
```python highlight={6} theme={null}
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="gpt-4.1-mini",
use_previous_response_id=True,
)
```
If we set `use_previous_response_id=True`, input messages up to the most recent response will be dropped from request payloads, and `previous_response_id` will be set using the ID of the most recent response.
That is,
```python theme={null}
llm.invoke(
[
HumanMessage("Hello"),
AIMessage("Hi there!", id="resp_123"),
HumanMessage("How are you?"),
]
)
```
is equivalent to:
```python theme={null}
llm.invoke([HumanMessage("How are you?")], previous_response_id="resp_123")
```
### Reasoning output
Some OpenAI models will generate separate text content illustrating their reasoning process. See OpenAI's [reasoning documentation](https://platform.openai.com/docs/guides/reasoning?api-mode=responses) for details.
OpenAI can return a summary of the model's reasoning (although it doesn't expose the raw reasoning tokens). To configure `ChatOpenAI` to return this summary, specify the `reasoning` parameter. `ChatOpenAI` will automatically route to the Responses API if this parameter is set.
```python theme={null}
from langchain_openai import ChatOpenAI
reasoning = {
"effort": "medium", # 'low', 'medium', or 'high'
"summary": "auto", # 'detailed', 'auto', or None
}
llm = ChatOpenAI(model="gpt-5-nano", reasoning=reasoning)
response = llm.invoke("What is 3^3?")
# Output
response.text
```
```output theme={null}
'3³ = 3 × 3 × 3 = 27.'
```
```python theme={null}
# Reasoning
for block in response.content_blocks:
if block["type"] == "reasoning":
print(block["reasoning"])
```
```output theme={null}
**Calculating the power of three**
The user is asking about 3 raised to the power of 3. That's a pretty simple calculation! I know that 3^3 equals 27, so I can say, "3 to the power of 3 equals 27." I might also include a quick explanation that it's 3 multiplied by itself three times: 3 × 3 × 3 = 27. So, the answer is definitely 27.
```
## Fine-tuning
You can call fine-tuned OpenAI models by passing in your corresponding `modelName` parameter.
This generally takes the form of `ft:{OPENAI_MODEL_NAME}:{ORG_NAME}::{MODEL_ID}`. For example:
```python theme={null}
fine_tuned_model = ChatOpenAI(
temperature=0, model_name="ft:gpt-3.5-turbo-0613:langchain::7qTVM5AR"
)
fine_tuned_model.invoke(messages)
```
```output theme={null}
AIMessage(content="J'adore la programmation.", additional_kwargs={'refusal': None}, response_metadata={'token_usage': {'completion_tokens': 8, 'prompt_tokens': 31, 'total_tokens': 39}, 'model_name': 'ft:gpt-3.5-turbo-0613:langchain::7qTVM5AR', 'system_fingerprint': None, 'finish_reason': 'stop', 'logprobs': None}, id='run-0f39b30e-c56e-4f3b-af99-5c948c984146-0', usage_metadata={'input_tokens': 31, 'output_tokens': 8, 'total_tokens': 39})
```
## Multimodal Inputs (images, PDFs, audio)
OpenAI has models that support multimodal inputs. You can pass in images, PDFs, or audio to these models. For more information on how to do this in LangChain, head to the [multimodal inputs](/oss/python/how-to/multimodal_inputs) docs.
You can see the list of models that support different modalities in [OpenAI's documentation](https://platform.openai.com/docs/models).
For all modalities, LangChain supports both its [cross-provider standard](/oss/python/concepts/multimodality/#multimodality-in-chat-models) as well as OpenAI's native content-block format.
To pass multimodal data into `ChatOpenAI`, create a [content block](/oss/python/langchain/messages/) containing the data and incorporate it into a message, e.g., as below:
```python highlight={9} theme={null}
message = {
"role": "user",
"content": [
{
"type": "text",
# Update prompt as desired
"text": "Describe the (image / PDF / audio...)",
},
content_block,
],
}
```
See below for examples of content blocks.
Refer to examples in the how-to guide [here](/oss/how-to/multimodal_inputs/#images).
URLs:
```python theme={null}
# LangChain format
content_block = {
"type": "image",
"url": url_string,
}
# OpenAI Chat Completions format
content_block = {
"type": "image_url",
"image_url": {"url": url_string},
}
```
In-line base64 data:
```python theme={null}
# LangChain format
content_block = {
"type": "image",
"base64": base64_string,
"mime_type": "image/jpeg",
}
# OpenAI Chat Completions format
content_block = {
"type": "image_url",
"image_url": {
"url": f"data:image/jpeg;base64,{base64_string}",
},
}
```
Note: OpenAI requires file-names be specified for PDF inputs. When using LangChain's format, include the `filename` key.
Read more [here](/oss/python/how-to/multimodal_inputs/#example-openai-file-names).
Refer to examples in the how-to guide [here](/oss/python/how-to/multimodal_inputs/#documents-pdf).
In-line base64 data:
```python highlight={7} theme={null}
# LangChain format
content_block = {
"type": "file",
"base64": base64_string,
"mime_type": "application/pdf",
"filename": "my-file.pdf",
}
# OpenAI Chat Completions format
content_block = {
"type": "file",
"file": {
"filename": "my-file.pdf",
"file_data": f"data:application/pdf;base64,{base64_string}",
}
}
```
See [supported models](https://platform.openai.com/docs/models), e.g., `"gpt-4o-audio-preview"`.
Refer to examples in the how-to guide [here](/oss/python/how-to/multimodal_inputs/#audio).
In-line base64 data:
```python theme={null}
# LangChain format
content_block = {
"type": "audio",
"mime_type": "audio/wav", # or appropriate mime-type
"base64": base64_string,
}
# OpenAI Chat Completions format
content_block = {
"type": "input_audio",
"input_audio": {"data": base64_string, "format": "wav"},
}
```
## Predicted output
**Requires `langchain-openai>=0.2.6`**
Some OpenAI models (such as their `gpt-4o` and `gpt-4o-mini` series) support [Predicted Outputs](https://platform.openai.com/docs/guides/latency-optimization#use-predicted-outputs), which allow you to pass in a known portion of the LLM's expected output ahead of time to reduce latency. This is useful for cases such as editing text or code, where only a small part of the model's output will change.
Here's an example:
```python theme={null}
code = """
///
/// Represents a user with a first name, last name, and username.
///
public class User
{
///
/// Gets or sets the user's first name.
///
public string FirstName { get; set; }
///
/// Gets or sets the user's last name.
///
public string LastName { get; set; }
///
/// Gets or sets the user's username.
///
public string Username { get; set; }
}
"""
llm = ChatOpenAI(model="gpt-4o")
query = (
"Replace the Username property with an Email property. "
"Respond only with code, and with no markdown formatting."
)
response = llm.invoke(
[{"role": "user", "content": query}, {"role": "user", "content": code}],
prediction={"type": "content", "content": code},
)
print(response.content)
print(response.response_metadata)
```
```output theme={null}
///
/// Represents a user with a first name, last name, and email.
///
public class User
{
///
/// Gets or sets the user's first name.
///
public string FirstName { get; set; }
///
/// Gets or sets the user's last name.
///
public string LastName { get; set; }
///
/// Gets or sets the user's email.
///
public string Email { get; set; }
}
{'token_usage': {'completion_tokens': 226, 'prompt_tokens': 166, 'total_tokens': 392, 'completion_tokens_details': {'accepted_prediction_tokens': 49, 'audio_tokens': None, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 107}, 'prompt_tokens_details': {'audio_tokens': None, 'cached_tokens': 0}}, 'model_name': 'gpt-4o-2024-08-06', 'system_fingerprint': 'fp_45cf54deae', 'finish_reason': 'stop', 'logprobs': None}
```
Note that currently predictions are billed as additional tokens and may increase your usage and costs in exchange for this reduced latency.
## Audio Generation (Preview)
Requires `langchain-openai>=0.2.3`
OpenAI has a new [audio generation feature](https://platform.openai.com/docs/guides/audio?audio-generation-quickstart-example=audio-out) that allows you to use audio inputs and outputs with the `gpt-4o-audio-preview` model.
```python theme={null}
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="gpt-4o-audio-preview",
temperature=0,
model_kwargs={
"modalities": ["text", "audio"],
"audio": {"voice": "alloy", "format": "wav"},
},
)
output_message = llm.invoke(
[
("human", "Are you made by OpenAI? Just answer yes or no"),
]
)
```
`output_message.additional_kwargs['audio']` will contain a dictionary like
```python theme={null}
{
'data': '
