docs: Adding in Docs for using Azure Default Credential Callable with OpenAI (#1160)

marlenezw · web-flow · commit 20b00784bb09 · 2025-10-28T15:09:16.000-04:00
diff --git a/src/oss/python/integrations/chat/azure_chat_openai.mdx b/src/oss/python/integrations/chat/azure_chat_openai.mdx
@@ -12,11 +12,15 @@ You can find information about Azure OpenAI's latest models and their costs, con
     Azure OpenAI refers to OpenAI models hosted on the [Microsoft Azure platform](https://azure.microsoft.com/en-us/products/ai-services/openai-service). OpenAI also provides its own model APIs. To access OpenAI services directly, use the [`ChatOpenAI` integration](/oss/integrations/chat/openai/).
 </Info>
 
-<Tip>
-    **API Reference**
+<Info>
+    **Azure OpenAI v1 API**
+
+    Azure OpenAI's [v1 API](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/api-version-lifecycle?tabs=python#next-generation-api-1) (Generally Available as of August 2025) allows you to use `ChatOpenAI` directly with Azure endpoints. This provides a unified interface and native support for Microsoft Entra ID authentication with automatic token refresh.
 
-    For detailed documentation of all features and configuration options, head to the @[`AzureChatOpenAI`] API reference.
-</Tip>
+    See the [ChatOpenAI Azure section](/oss/integrations/chat/openai#using-with-azure-openai) for details on using `ChatOpenAI` with Azure's v1 API.
+
+    `AzureChatOpenAI` is still currently supported for traditional Azure OpenAI API versions and scenarios requiring Azure-specific configurations, but we recommend using `ChatOpenAI` or the `AzureAIChatCompletionsModel` in [LangChain Azure AI](https://docs.langchain.com/oss/python/integrations/providers/azure_ai) going forward.
+</Info>
 
 <Note>
     @[`AzureChatOpenAI`] shares the same underlying base implementation as @[`ChatOpenAI`],
diff --git a/src/oss/python/integrations/chat/openai.mdx b/src/oss/python/integrations/chat/openai.mdx
@@ -18,12 +18,6 @@ You can find information about OpenAI's latest models, their costs, context wind
     `ChatOpenAI` is fully compatible with OpenAI's (legacy) [Chat Completions API](https://platform.openai.com/docs/guides/completions). If you are looking to connect to other model providers that support the Chat Completions API, you can do so – see [instructions](/oss/integrations/chat#chat-completions-api).
 </Note>
 
-<Info>
-    **OpenAI models hosted on Azure**
-
-    Note that certain OpenAI models can also be accessed via the [Microsoft Azure platform](https://azure.microsoft.com/en-us/products/ai-foundry/models/openai/). To use the Azure OpenAI service use the [`AzureChatOpenAI`](/oss/integrations/chat/azure_chat_openai/) integration.
-</Info>
-
 ## Overview
 
 ### Integration details
@@ -87,7 +81,7 @@ llm = ChatOpenAI(
     # timeout=None,
     # reasoning_effort="low",
     # max_retries=2,
-    # api_key="...",  # if you prefer to pass api key in directly instaed of using env vars
+    # api_key="...",  # if you prefer to pass api key in directly instead of using env vars
     # base_url="...",
     # organization="...",
     # other params...
@@ -136,6 +130,101 @@ from langchain_openai import ChatOpenAI
 llm = ChatOpenAI(model="gpt-4.1-mini", stream_usage=True)  # [!code highlight]
 ```
 
+## Using with Azure OpenAI
+
+<Info>
+    **Azure OpenAI v1 API support**
+
+    As of `langchain-openai>=1.0.1`, `ChatOpenAI` can be used directly with Azure OpenAI endpoints using the new [v1 API](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/api-version-lifecycle?tabs=python#next-generation-api-1). This provides a unified way to use OpenAI models whether hosted on OpenAI or Azure.
+
+    For the traditional Azure-specific implementation, continue to use [`AzureChatOpenAI`](/oss/integrations/chat/azure_chat_openai/).
+</Info>
+
+<Accordion title="Using Azure OpenAI v1 API with API Key">
+
+To use `ChatOpenAI` with Azure OpenAI, set the `base_url` to your Azure endpoint with `/openai/v1/` appended:
+
+```python
+from langchain_openai import ChatOpenAI
+
+llm = ChatOpenAI(
+    model="gpt-5-mini",  # Your Azure deployment name
+    base_url="https://{your-resource-name}.openai.azure.com/openai/v1/",
+    api_key="your-azure-api-key"
+)
+
+response = llm.invoke("Hello, how are you?")
+print(response.content)
+```
+</Accordion>
+
+<Accordion title="Using Azure OpenAI with Microsoft Entra ID">
+
+The v1 API adds native support for [Microsoft Entra ID](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/managed-identity) (formerly Azure AD) authentication with automatic token refresh. Pass a token provider callable to the `api_key` parameter:
+
+```python
+from azure.identity import DefaultAzureCredential, get_bearer_token_provider
+from langchain_openai import ChatOpenAI
+
+# Create a token provider that handles automatic refresh
+token_provider = get_bearer_token_provider(
+    DefaultAzureCredential(),
+    "https://cognitiveservices.azure.com/.default"
+)
+
+llm = ChatOpenAI(
+    model="gpt-5-mini",  # Your Azure deployment name
+    base_url="https://{your-resource-name}.openai.azure.com/openai/v1/",
+    api_key=token_provider  # Callable that handles token refresh
+)
+
+# Use the model as normal
+messages = [
+    ("system", "You are a helpful assistant."),
+    ("human", "Translate 'I love programming' to French.")
+]
+response = llm.invoke(messages)
+print(response.content)
+```
+
+The token provider is a callable that automatically retrieves and refreshes authentication tokens, eliminating the need to manually manage token expiration.
+
+<Tip>
+**Installation requirements**
+
+To use Microsoft Entra ID authentication, install the Azure Identity library:
+
+```bash
+pip install azure-identity
+```
+
+</Tip>
+
+You can also pass a token provider callable to the `api_key` parameter when using
+asynchronous functions. You must import DefaultAzureCredential from `azure.identity.aio`:
+
+
+```python
+from azure.identity.aio import DefaultAzureCredential
+from langchain_openai import ChatOpenAI
+
+credential = DefaultAzureCredential()
+
+llm_async = ChatOpenAI(
+    model="gpt-5-nano",
+    api_key=credential
+)
+
+# Use async methods when using async callable
+response = await llm_async.ainvoke("Hello!")
+```
+
+<Note>
+When using an async callable for the API key, you must use async methods (`ainvoke`, `astream`, etc.). Sync methods will raise an error.
+</Note>
+
+</Accordion>
+
 ## 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.
diff --git a/src/oss/python/integrations/text_embedding/openai.mdx b/src/oss/python/integrations/text_embedding/openai.mdx
@@ -57,6 +57,12 @@ embeddings = OpenAIEmbeddings(
 )
 ```
 
+<Info>
+    **Azure OpenAI v1 API support**
+
+    As of `langchain-openai>=1.0.1`, `OpenAIEmbeddings` can be used directly with Azure OpenAI endpoints using the new [v1 API](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/api-version-lifecycle?tabs=python#next-generation-api-1), including support for Microsoft Entra ID authentication. See the [Using with Azure OpenAI](#using-with-azure-openai) section below for details.
+</Info>
+
 ## Indexing and Retrieval
 
 Embedding models are often used in retrieval-augmented generation (RAG) flows, both as part of indexing data as well as later retrieving it. For more detailed instructions, please see our [RAG tutorials](/oss/langchain/rag).
@@ -125,6 +131,95 @@ for vector in two_vectors:
 [-0.010181212797760963, 0.023419594392180443, -0.04215526953339577, -0.001532090245746076, -0.023573
 ```
 
+## Using with Azure OpenAI
+
+<Info>
+    **Azure OpenAI v1 API support**
+
+    As of `langchain-openai>=1.0.1`, `OpenAIEmbeddings` can be used directly with Azure OpenAI endpoints using the new [v1 API](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/api-version-lifecycle?tabs=python#next-generation-api-1). This provides a unified way to use OpenAI embeddings whether hosted on OpenAI or Azure.
+
+    For the traditional Azure-specific implementation, continue to use [`AzureOpenAIEmbeddings`](/oss/integrations/text_embedding/azure_openai).
+</Info>
+
+### Using Azure OpenAI v1 API with API Key
+
+To use `OpenAIEmbeddings` with Azure OpenAI, set the `base_url` to your Azure endpoint with `/openai/v1/` appended:
+
+```python
+from langchain_openai import OpenAIEmbeddings
+
+embeddings = OpenAIEmbeddings(
+    model="text-embedding-3-large",  # Your Azure deployment name
+    base_url="https://{your-resource-name}.openai.azure.com/openai/v1/",
+    api_key="your-azure-api-key"
+)
+
+# Use as normal
+vector = embeddings.embed_query("Hello world")
+```
+
+### Using Azure OpenAI with Microsoft Entra ID
+
+The v1 API adds native support for [Microsoft Entra ID](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/managed-identity) authentication with automatic token refresh. Pass a token provider callable to the `api_key` parameter:
+
+```python
+from azure.identity import DefaultAzureCredential, get_bearer_token_provider
+from langchain_openai import OpenAIEmbeddings
+
+# Create a token provider that handles automatic refresh
+token_provider = get_bearer_token_provider(
+    DefaultAzureCredential(),
+    "https://cognitiveservices.azure.com/.default"
+)
+
+embeddings = OpenAIEmbeddings(
+    model="text-embedding-3-large",  # Your Azure deployment name
+    base_url="https://{your-resource-name}.openai.azure.com/openai/v1/",
+    api_key=token_provider  # Callable that handles token refresh
+)
+
+# Use as normal
+vectors = embeddings.embed_documents(["Hello", "World"])
+```
+
+<Tip>
+**Installation requirements**
+
+To use Microsoft Entra ID authentication, install the Azure Identity library:
+
+```bash
+pip install azure-identity
+```
+
+</Tip>
+
+You can also pass a token provider callable to the `api_key` parameter when using
+asynchronous functions. You must import DefaultAzureCredential from `azure.identity.aio`:
+
+:::python
+
+```python
+from azure.identity.aio import DefaultAzureCredential
+from langchain_openai import OpenAIEmbeddings
+
+credential = DefaultAzureCredential()
+
+embeddings_async = OpenAIEmbeddings(
+    model="text-embedding-3-large",
+    api_key=credential
+)
+
+# Use async methods when using async callable
+vectors = await embeddings_async.aembed_documents(["Hello", "World"])
+
+```
+
+:::
+
+<Note>
+When using an async callable for the API key, you must use async methods (`aembed_query`, `aembed_documents`). Sync methods will raise an error.
+</Note>
+
 ## API reference
 
 For detailed documentation on `OpenAIEmbeddings` features and configuration options, please refer to the [API reference](https://python.langchain.com/api_reference/openai/embeddings/langchain_openai.embeddings.base.OpenAIEmbeddings.html).
