Microsoft integrations

This page covers all LangChain integrations with Microsoft Azure and other Microsoft products.

Choose a package

langchain-azure-ai and langchain-openai are complementary rather than alternatives. langchain-azure-ai depends on langchain-openai, and its chat and embeddings classes subclass ChatOpenAI and OpenAIEmbeddings, so installing the Azure package does not remove the OpenAI package from your dependency chain.

Use the following table to pick a starting point:

Moving an existing langchain-openai application to langchain-azure-ai is not a drop-in import change:

• Configuration differs. azure_endpoint, azure_deployment, api_version, and token-provider arguments become project_endpoint or endpoint, model, and credential.
• Default behavior differs. AzureAIOpenAIApiChatModel defaults to the Responses API when it resolves a project endpoint. Set use_responses_api=False to keep Chat Completions behavior.
• No completion-LLM equivalent to AzureOpenAI exists in langchain-azure-ai.
• AzureChatOpenAI carries Azure-specific response metadata and content-filter handling that the Foundry chat model does not reproduce.
• Both packages follow the official OpenAI schemas, so non-standard fields returned by compatible providers such as DeepSeek or Mistral may not be preserved.

Chat models

Microsoft offers three main options for accessing chat models through Azure:

1. Microsoft Foundry (recommended for project-centric applications): Use AzureAIOpenAIApiChatModel from langchain-azure-ai with a Foundry project endpoint and Azure credentials. This package also integrates with Foundry agents, hosting, tools, Content Safety, retrieval, and observability.
2. Azure OpenAI: Use ChatOpenAI from langchain-openai for direct v1 API calls or code that switches between OpenAI and Azure. Use AzureChatOpenAI for traditional Azure OpenAI API versions and existing applications.
3. Azure ML: Allows deployment and management of custom or fine-tuned open-source models with Azure Machine Learning.

Microsoft Foundry

Microsoft Foundry provides project-level access to models and Azure services. Use AzureAIOpenAIApiChatModel from langchain-azure-ai when your application uses a Foundry project, Azure credentials, or other Foundry capabilities.

pip install -U langchain-azure-ai

uv add langchain-azure-ai

Set your project endpoint:

export AZURE_AI_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"

Then create the chat model:

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.chat_models import AzureAIOpenAIApiChatModel

llm = AzureAIOpenAIApiChatModel(
    model="gpt-5.2",  # your Foundry model deployment name
    credential=DefaultAzureCredential(),
)

For a complete setup guide, see the Microsoft Foundry chat model integration.

Azure OpenAI

For direct Azure OpenAI access, create an Azure deployment and install the langchain-openai package:

pip install -U langchain-openai

uv add langchain-openai

On the v1 API, use ChatOpenAI directly against your Azure endpoint—no api_version required:

pip install azure-identity

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from langchain_openai import ChatOpenAI

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default",
)

llm = ChatOpenAI(
    model="gpt-5.4-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
)

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-5.4-mini",  # your Azure deployment name
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key="your-azure-api-key",
)

For traditional Azure OpenAI API versions, use AzureChatOpenAI:

from langchain_openai import AzureChatOpenAI

See the Azure ChatOpenAI integration page for end-to-end setup, Entra ID authentication, tool calling, and reasoning examples.

Responses API

Azure OpenAI supports the Responses API, which provides stateful conversations, built-in tools (web search, file search, code interpreter), and structured reasoning summaries. ChatOpenAI automatically routes to the Responses API when you set the reasoning parameter, or you can opt in explicitly with use_responses_api=True:

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from langchain_openai import ChatOpenAI

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default",
)

llm = ChatOpenAI(
    model="gpt-5.4-mini",
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider,
    use_responses_api=True,
)

response = llm.invoke("Summarize the bitter lesson.")
print(response.text)

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-5.4-mini",
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key="your-azure-api-key",
    use_responses_api=True,
)

response = llm.invoke("Summarize the bitter lesson.")
print(response.text)

For a walkthrough of reasoning effort, reasoning summaries, and streaming with the Responses API, see the Azure ChatOpenAI integration page.

LLMs

Microsoft offers two main options for accessing LLMs through Azure:

1. Azure OpenAI (recommended): Use Azure OpenAI text-completion deployments with AzureOpenAI from langchain-openai.
2. Azure ML: Use custom or open-source models hosted on Azure Machine Learning online endpoints.

Azure OpenAI

See a usage example.

pip install -U langchain-openai

uv add langchain-openai

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from langchain_openai import AzureOpenAI

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default",
)

llm = AzureOpenAI(
    azure_deployment="gpt-5.4-mini",  # your Azure deployment name
    api_version="2025-04-01-preview",
    azure_ad_token_provider=token_provider,
)

print(llm.invoke("Write a haiku about the ocean."))

from langchain_openai import AzureOpenAI

llm = AzureOpenAI(
    azure_deployment="gpt-5.4-mini",  # your Azure deployment name
    api_version="2025-04-01-preview",
    azure_endpoint="https://YOUR-RESOURCE-NAME.openai.azure.com/",
    api_key="your-azure-api-key",
)

print(llm.invoke("Write a haiku about the ocean."))

Embedding models

Choose an embeddings integration based on how your application connects to Azure:

1. Microsoft Foundry (recommended for project-centric applications): Use AzureAIOpenAIApiEmbeddingsModel from langchain-azure-ai with Foundry project configuration and Azure credentials.
2. Azure OpenAI: Use AzureOpenAIEmbeddings from langchain-openai for direct or traditional Azure OpenAI endpoints, existing applications, or a smaller dependency surface.

Microsoft Foundry

Install langchain-azure-ai:

pip install -U langchain-azure-ai

uv add langchain-azure-ai

Set your project endpoint:

export AZURE_AI_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"

Then create the embeddings model:

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.embeddings import AzureAIOpenAIApiEmbeddingsModel

embeddings = AzureAIOpenAIApiEmbeddingsModel(
    model="text-embedding-3-small",  # your Foundry model deployment name
    credential=DefaultAzureCredential(),
)

For more information, see the Microsoft Foundry embeddings integration.

Azure OpenAI

See a usage example.

pip install -U langchain-openai

uv add langchain-openai

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from langchain_openai import AzureOpenAIEmbeddings

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default",
)

embeddings = AzureOpenAIEmbeddings(
    azure_deployment="text-embedding-3-small",  # your Azure deployment name
    api_version="2025-04-01-preview",
    azure_ad_token_provider=token_provider,
)

vector = embeddings.embed_query("LangChain makes agents easy.")

from langchain_openai import AzureOpenAIEmbeddings

embeddings = AzureOpenAIEmbeddings(
    azure_deployment="text-embedding-3-small",  # your Azure deployment name
    api_version="2025-04-01-preview",
    azure_endpoint="https://YOUR-RESOURCE-NAME.openai.azure.com/",
    api_key="your-azure-api-key",
)

vector = embeddings.embed_query("LangChain makes agents easy.")

Middleware

Azure AI Content Safety middleware

Azure AI Content Safety provides guardrails you can apply to LangChain agents through middleware. The langchain-azure-ai package currently exports middleware for text moderation, image moderation, prompt injection detection, protected material detection, and groundedness evaluation.

Install the middleware package:

pip install -U langchain-azure-ai

uv add langchain-azure-ai

See the Microsoft Foundry middleware guide.

from langchain_azure_ai.agents.middleware import AzureContentModerationMiddleware

Document loaders

Azure Blob Storage

Azure Blob Storage is Microsoft's object storage solution for the cloud. Blob Storage is optimized for storing massive amounts of unstructured data. Unstructured data is data that doesn't adhere to a particular data model or definition, such as text or binary data.

Azure Blob Storage is designed for:

• Serving images or documents directly to a browser.
• Storing files for distributed access.
• Streaming video and audio.
• Writing to log files.
• Storing data for backup and restore, disaster recovery, and archiving.
• Storing data for analysis by an on-premises or Azure-hosted service.

pip install langchain-azure-storage

uv add langchain-azure-storage

See usage examples for the Azure Blob Storage Loader.

from langchain_azure_storage.document_loaders import AzureBlobStorageLoader

Backends

Azure Blob Storage Backend

Azure Blob Storage is Microsoft's object storage solution for the cloud. AzureBlobBackend implements the Deep Agents BackendProtocol, so a deep agent can persist its entire workspace (files, memories, and artifacts) in a blob container.

Install with the deepagents extra (requires Python 3.11+):

pip install -U "langchain-azure-storage[deepagents]"

uv add "langchain-azure-storage[deepagents]"

from langchain_azure_storage.deepagents import AzureBlobBackend

Quick start:

from deepagents import create_deep_agent
from langchain_azure_storage.deepagents import AzureBlobBackend

backend = AzureBlobBackend(
    account_url="https://<my-storage-account-name>.blob.core.windows.net",
    container_name="agent-workspace",
    prefix="session-001/",  # Optional: isolate each agent/session under a prefix.
)

agent = create_deep_agent(backend=backend)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Write a hello world script to hello.py"}]}
)

The backend defaults to DefaultAzureCredential and accepts a credential override.

For more information, see Backend integrations. See the package repository for full usage details and security guidance.

Memory

Azure cosmos DB chat message history

Azure Cosmos DB provides chat message history storage for conversational AI applications, enabling you to persist and retrieve conversation history with low latency and high availability.

pip install langchain-azure-cosmosdb

uv add langchain-azure-cosmosdb

Configure your Azure Cosmos DB connection (sync or async, with access key or Microsoft Entra ID):

from langchain_azure_cosmosdb import CosmosDBChatMessageHistory

history = CosmosDBChatMessageHistory(
    cosmos_endpoint="https://<your-account>.documents.azure.com:443/",
    cosmos_database="<your-database>",
    cosmos_container="<your-container>",
    session_id="<session-id>",
    user_id="<user-id>",
    credential="<your-key-or-token-credential>",
    ttl=3600,  # optional: messages expire after 1 hour
)
history.prepare_cosmos()

history.add_user_message("Hello!")
history.add_ai_message("Hi there!")

For async usage, import AsyncCosmosDBChatMessageHistory from the same package.

Azure cosmos DB semantic cache

AzureCosmosDBNoSqlSemanticCache caches LLM responses in Azure Cosmos DB for NoSQL using vector similarity, returning cached results when a semantically similar prompt is seen again.

pip install langchain-azure-cosmosdb

uv add langchain-azure-cosmosdb

from azure.cosmos import CosmosClient, PartitionKey
from langchain_core.globals import set_llm_cache
from langchain_azure_cosmosdb import AzureCosmosDBNoSqlSemanticCache

cosmos_client = CosmosClient("<endpoint>", "<key>")

cache = AzureCosmosDBNoSqlSemanticCache(
    cosmos_client=cosmos_client,
    embedding=embedding,
    vector_embedding_policy=vector_embedding_policy,
    indexing_policy=indexing_policy,
    cosmos_container_properties={"partition_key": PartitionKey(path="/id")},
    cosmos_database_properties={"id": "cache-db"},
    vector_search_fields={"text_field": "text", "embedding_field": "embedding"},
    database_name="cache-db",
    container_name="cache-container",
)

set_llm_cache(cache)

For async usage, import AsyncAzureCosmosDBNoSqlSemanticCache.

Vector stores

Azure cosmos DB

AI agents can rely on Azure Cosmos DB as a unified memory system solution, enjoying speed, scale, and simplicity. This service successfully enabled OpenAI's ChatGPT service to scale dynamically with high reliability and low maintenance. Powered by an atom-record-sequence engine, it is the world's first globally distributed NoSQL, relational, and vector database service that offers a serverless mode.

Below are two available Azure Cosmos DB APIs that can provide vector store functionalities.

Azure cosmos DB for MongoDB (vCore)

Azure Cosmos DB for MongoDB vCore makes it easy to create a database with full native MongoDB support. You can apply your MongoDB experience and continue to use your favorite MongoDB drivers, SDKs, and tools by pointing your application to the API for MongoDB vCore account's connection string. Use vector search in Azure Cosmos DB for MongoDB vCore to seamlessly integrate your AI-based applications with your data that's stored in Azure Cosmos DB.

Installation and setup

See detailed configuration instructions.

We need to install langchain-azure-ai and pymongo python packages.

pip install langchain-azure-ai pymongo

uv add langchain-azure-ai pymongo

Deploy Azure cosmos DB on Microsoft Azure

Azure Cosmos DB for MongoDB vCore provides developers with a fully managed MongoDB-compatible database service for building modern applications with a familiar architecture.

With Cosmos DB for MongoDB vCore, developers can enjoy the benefits of native Azure integrations, low total cost of ownership (TCO), and the familiar vCore architecture when migrating existing applications or building new ones.

Sign Up for free to get started today.

See a usage example.

from langchain_azure_ai.vectorstores import AzureCosmosDBMongoVCoreVectorSearch

Azure cosmos DB NoSQL

Azure Cosmos DB for NoSQL now offers vector indexing and search in preview. This feature is designed to handle high-dimensional vectors, enabling efficient and accurate vector search at any scale. You can now store vectors directly in the documents alongside your data. This means that each document in your database can contain not only traditional schema-free data, but also high-dimensional vectors as other properties of the documents. This colocation of data and vectors allows for efficient indexing and searching, as the vectors are stored in the same logical unit as the data they represent. This simplifies data management, AI application architectures, and the efficiency of vector-based operations.

Installation and setup

See detail configuration instructions.

We need to install langchain-azure-cosmosdb and azure-cosmos python packages.

pip install langchain-azure-cosmosdb azure-cosmos

uv add langchain-azure-cosmosdb azure-cosmos

Deploy Azure cosmos DB on Microsoft Azure

Azure Cosmos DB offers a solution for modern apps and intelligent workloads by being very responsive with dynamic and elastic autoscale. It is available in every Azure region and can automatically replicate data closer to users. It has SLA guaranteed low-latency and high availability.

Sign Up for free to get started today.

See a usage example.

from langchain_azure_cosmosdb import AzureCosmosDBNoSqlVectorSearch

Azure Database for PostgreSQL

Azure Database for PostgreSQL - Flexible Server is a relational database service based on the open-source Postgres database engine. It's a fully managed database-as-a-service that can handle mission-critical workloads with predictable performance, security, high availability, and dynamic scalability.

See set up instructions for Azure Database for PostgreSQL.

Simply use the connection string from your Azure Portal.

Since Azure Database for PostgreSQL is open-source Postgres, you can use the LangChain's Postgres support to connect to Azure Database for PostgreSQL.

Azure SQL Database

Azure SQL Database is a robust service that combines scalability, security, and high availability, providing all the benefits of a modern database solution. It also provides a dedicated Vector data type & built-in functions that simplifies the storage and querying of vector embeddings directly within a relational database. This eliminates the need for separate vector databases and related integrations, increasing the security of your solutions while reducing the overall complexity.

By leveraging your current SQL Server databases for vector search, you can enhance data capabilities while minimizing expenses and avoiding the challenges of transitioning to new systems.

Installation and setup

See detail configuration instructions.

We need to install the langchain-sqlserver python package.

!pip install langchain-sqlserver==0.1.1

Deploy Azure SQL DB on Microsoft Azure

Sign Up for free to get started today.

See a usage example.

from langchain_sqlserver import SQLServer_VectorStore

Vector store

Azure Database for PostgreSQL

Azure Database for PostgreSQL - Flexible Server is a relational database service based on the open-source Postgres database engine. It's a fully managed database-as-a-service that can handle mission-critical workloads with predictable performance, security, high availability, and dynamic scalability.

See set up instructions for Azure Database for PostgreSQL.

You need to enable pgvector extension in your database to use Postgres as a vector store. Once you have the extension enabled, you can use the PGVector in LangChain to connect to Azure Database for PostgreSQL.

See a usage example. Simply use the connection string from your Azure Portal.

Tools

Microsoft Foundry tools

Microsoft Foundry exposes LangChain service tools for Azure AI Content Understanding, Document Intelligence, Image Analysis, and Text Analytics for Health.

Install the package with the tools extra:

pip install -U "langchain-azure-ai[tools]"

uv add "langchain-azure-ai[tools]"

See the Microsoft Foundry Tools guide.

from langchain_azure_ai.tools import AzureAIDocumentIntelligenceTool

Image generation tool

Microsoft Foundry Models has several models available in the catalog for image generation.

See the Microsoft Foundry tools guide.

from langchain_azure_ai.tools import AzureOpenAIModelImageGenTool

Transcriptions tool

Microsoft Foundry Models has Whisper models available in the catalog for speech-to-text transcriptions.

See the Microsoft Foundry tools guide.

from langchain_azure_ai.tools import AzureOpenAITranscriptionsTool

Code interpreter tool (server-side)

Run Python code server-side in a sandboxed container with the Code Interpreter tool.

See the Microsoft Foundry tools guide.

from langchain_azure_ai.tools.builtin import CodeInterpreterTool

Web search tool (server-side)

Search the internet for current information and sources.

See the Microsoft Foundry tools guide.

from langchain_azure_ai.tools.builtin import WebSearchTool

File search tool (server-side)

Search vector stores for relevant document content.

See the Microsoft Foundry tools guide.

from langchain_azure_ai.tools.builtin import FileSearchTool

Image generation tool (server-side)

Generate or edit images using GPT image models server-side in Azure AI Foundry.

See the Microsoft Foundry tools guide.

from langchain_azure_ai.tools.builtin import ImageGenerationTool

MCP tool (server-side)

Access external Model Context Protocol (MCP) servers.

See the Microsoft Foundry tools guide.

from langchain_azure_ai.tools.builtin import McpTool

Azure Container Apps Dynamic Sessions

We need to get the POOL_MANAGEMENT_ENDPOINT environment variable from the Azure Container Apps service. See the Azure dynamic sessions setup instructions.

We need to install a python package.

pip install langchain-azure-dynamic-sessions

uv add langchain-azure-dynamic-sessions

See a usage example.

from langchain_azure_dynamic_sessions import SessionsPythonREPLTool

Azure Logic Apps

Trigger Azure Logic Apps workflows to automate business processes and integrations.

Install the package with the tools extra:

pip install -U "langchain-azure-ai[tools]"

uv add "langchain-azure-ai[tools]"

See the Azure Logic Apps integration guide.

from langchain_azure_ai.tools import AzureLogicAppTool

Toolkits

Microsoft Foundry Project Toolbox

Load tools dynamically from an Azure AI Foundry Toolbox via the Model Context Protocol (MCP).

Install the package with the tools extra:

pip install -U "langchain-azure-ai[tools]" langchain-mcp-adapters httpx

uv add "langchain-azure-ai[tools]" langchain-mcp-adapters httpx

See the Azure AI Foundry Toolbox guide.

from langchain_azure_ai.tools import AzureAIProjectToolbox

Microsoft Foundry tools (formerly Azure AI Services)

Install the integration package:

pip install -U "langchain-azure-ai[tools]"

uv add "langchain-azure-ai[tools]"

See a usage example.

from langchain_azure_ai.tools import AzureAIServicesToolkit

The AzureAIServicesToolkit toolkit includes the following tools:

• Image Analysis: AzureAIImageAnalysisTool
• Document Intelligence: AzureAIDocumentIntelligenceTool
• Speech to Text: AzureAISpeechToTextTool
• Text to Speech: AzureAITextToSpeechTool
• Text Analytics for Health: AzureAITextAnalyticsHealthTool

Runtime

Microsoft Foundry hosted agents

Microsoft Foundry hosted agents run custom LangGraph code in a managed runtime. Use the langchain_azure_ai.agents.hosting package to expose a compiled LangGraph graph while Foundry manages the runtime, sessions, scaling, identity, and protocol endpoints.

Before you begin, you need an Azure subscription, a Foundry project, a deployed chat model, Python 3.10 or later, and Azure CLI authentication. Deploying the agent also requires the Foundry Project Manager role on the project.

Choose a hosting protocol based on how clients interact with the agent:

See the complete run samples for the Responses protocol and Invocations protocol.

Use the configuration-driven runner

If your agent already runs with the LangGraph CLI, use langchain_azure_ai.agents.hosting.run tool from the same project directory. The runner uses the existing langgraph.json configuration to load the compiled graph, so no code change is needed.

Set the Foundry project endpoint and model deployment name, then select the protocol when you start the host:

export FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="<model-deployment-name>"
python -m langchain_azure_ai.agents.hosting.run --protocol responses

export FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="<model-deployment-name>"
python -m langchain_azure_ai.agents.hosting.run --protocol invocations

For deployment, set codeConfiguration.entryPoint on the agent service in azure.yaml to the same runner and protocol. Keep the existing project path, runtime, and dependency resolution settings:

services:
    my-agent:
        codeConfiguration:
            entryPoint: '-m langchain_azure_ai.agents.hosting.run --protocol responses'

services:
    my-agent:
        codeConfiguration:
            entryPoint: '-m langchain_azure_ai.agents.hosting.run --protocol invocations'
...

Use the SDK host classes

Use the SDK host classes when you need to customize server construction, control the server lifecycle directly, or implement advanced hosting behavior such as custom routes or handlers:

from langchain_azure_ai.agents.hosting import ResponsesHostServer

ResponsesHostServer(graph).run()

from langchain_azure_ai.agents.hosting import InvocationsHostServer

InvocationsHostServer(graph).run()

To deploy either approach, use azd ai agent init to initialize a hosted-agent project, azd ai agent run to test it locally, and azd deploy to deploy it. Run azd provision first only when you need to create the Foundry project or other Azure resources. You can also deploy with the Foundry Toolkit Visual Studio Code extension.

The Microsoft Learn guide includes complete examples for both protocols, conversation state, human-in-the-loop flows, testing, deployment, and troubleshooting.