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 becomeproject_endpointorendpoint,model, andcredential. - Default behavior differs.
AzureAIOpenAIApiChatModeldefaults to the Responses API when it resolves a project endpoint. Setuse_responses_api=Falseto keep Chat Completions behavior. - No completion-LLM equivalent to
AzureOpenAIexists inlangchain-azure-ai. AzureChatOpenAIcarries 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:- Microsoft Foundry (recommended for project-centric applications): Use
AzureAIOpenAIApiChatModelfromlangchain-azure-aiwith a Foundry project endpoint and Azure credentials. This package also integrates with Foundry agents, hosting, tools, Content Safety, retrieval, and observability. - Azure OpenAI: Use
ChatOpenAIfromlangchain-openaifor direct v1 API calls or code that switches between OpenAI and Azure. UseAzureChatOpenAIfor traditional Azure OpenAI API versions and existing applications. - Azure ML: Allows deployment and management of custom or fine-tuned open-source models with Azure Machine Learning.
langchain-azure-ai to access the models available in Azure AI Foundry.
Azure AI chat completions
Access models like Azure OpenAI, DeepSeek R1, Cohere, Phi and Mistral using theAzureAIOpenAIApiChatModel class.
DefaultAzureCredential, or set an API key directly.
LLMs
Microsoft offers two main options for accessing LLMs through Azure:- Azure OpenAI (recommended): Use Azure OpenAI text-completion deployments with
AzureOpenAIfromlangchain-openai. - Azure ML: Use custom or open-source models hosted on Azure Machine Learning online endpoints.
Embedding models
Choose an embeddings integration based on how your application connects to Azure:- Microsoft Foundry (recommended for project-centric applications): Use
AzureAIOpenAIApiEmbeddingsModelfromlangchain-azure-aiwith Foundry project configuration and Azure credentials. - Azure OpenAI: Use
AzureOpenAIEmbeddingsfromlangchain-openaifor direct or traditional Azure OpenAI endpoints, existing applications, or a smaller dependency surface.
Microsoft Foundry embeddings
DefaultAzureCredential, or set an API key directly.
Foundry project configuration currently derives a direct
/openai/v1 endpoint because embeddings are not yet served through the project endpoint itself.Backends
Azure Blob Storage Backend
Azure Blob Storage is Microsoft’s object storage solution for the cloud.AzureBlobBackendimplements the Deep AgentsBackendProtocol, so a deep agent can persist its entire workspace (files, memories, and artifacts) in a blob container.
The
AzureBlobBackend is part of the langchain-azure-storage package, which is currently in Public Preview.deepagents extra (requires Python 3.11+):
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.
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.
AsyncAzureCosmosDBNoSqlSemanticCache.
Vector stores
Azure CosmosDB NoSQL vector search
Azure CosmosDB NoSQL is a fully managed, globally distributed, serverless document database for modern applications. It stores data in flexible JSON documents and uses a SQL-like query language. This provides high performance, low latency, and automatic, elastic scalability. It also features integrated vector search capabilities for AI workloads like generative AI and RAG. This allows you to store, index, and query vector embeddings alongside your operational data in the same database. You can combine vector similarity search with traditional keyword-based search for relevant results and choose from various indexing methods for optimal performance. This unified approach simplifies application architecture and ensures data consistency.We need to install the
langchain-azure-cosmosdb and azure-cosmos packages to use this vector store.
Azure CosmosDB mongo vCore vector search
Azure CosmosDB Mongo vCore architecture 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) cluster’s connection string.Install
pymongo and langchain-azure-cosmosdb to use this vector store.
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. Install thelangchain-sqlserver package:
Deploy Azure SQL DB on Microsoft Azure
Sign Up for free to get started today. See a usage example.Azure AI Search
Azure AI Search is a cloud search service for vector, keyword, and hybrid retrieval.The
AzureSearch vector store and the AzureAISearchRetriever retriever ship in langchain-azure-ai.
Runtime
Microsoft Foundry hosted agents
Microsoft Foundry hosted agents run custom LangGraph code in a managed runtime. Use thelangchain_azure_ai.agents.hosting package to expose a compiled LangGraph graph while Foundry manages the runtime, sessions, scaling, identity, and protocol endpoints.
LangGraph hosting support requires
langchain-azure-ai[hosting]>=1.2.8.For hosted graphs using
BaseChatOpenAI-based models with the Responses API, use output_version="responses/v1". You can omit this setting in langchain-openai 1.0.0 or later, unless overridden by LC_OUTPUT_VERSION. This guidance applies to both Responses and Invocations hosting protocols.Use the configuration-driven runner
If your agent already runs with the LangGraph CLI, uselangchain_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:
- Responses
- Invocations
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:
- Responses
- 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:- Responses
- Invocations
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.
Durable LangGraph execution with Azure Durable Task Scheduler
langchain_azure_compute.graph wraps a compiled LangGraph StateGraph, a LangChain create_agent workflow, or a Deep Agents create_deep_agent graph in a deterministic Azure Durable Task Scheduler (DTS) orchestration with attach_durability(graph, name="..."). Model calls, tools, and graph steps run in activities rather than in the replaying orchestrator. create_deep_agent also requires the deepagents package.
The durable execution integration is in public preview. Its API may change. Requires
langchain-azure-compute 0.2.0 or later.SqliteSaver, PostgresSaver, or CosmosDBSaver. Make persistent checkpoint storage accessible to every worker. With a persistent saver, step transitions pass checkpoint references, while durable tool/node inputs and outputs and final results still pass through DTS. Without a checkpointer, the adapter attaches an InMemorySaver and carries checkpoint bundles in DTS payloads.
- Activity isolation: Use
@durable_tool(retries=3)to configure a tool’s independent retry policy, and@durable_nodeto isolate a graph node as an activity. - Worker crash failover: Another worker registered with the same graph and task hub can resume execution from persisted progress.
- Human-in-the-loop waits: LangGraph
interrupt()pauses execution using DTS external events without holding worker threads or consuming compute for the wait. Read the interrupt withrun.wait_pending()and continue it withrun.resume(pending, value). - Azure Functions HTTP routes:
LangGraphFunctionAppexposes start, status, and respond routes on Azure Functions Python v2. HTTP control routes do not replace a graph worker. Run dedicatedDurableTaskSchedulerWorkerreplicas against the same scheduler and hub; embedded workers are not supported on Consumption or Flex plans. Function apps also require verified caller identity and per-instance ownership checks. See the Azure Functions human-in-the-loop sample.
AZURE_AI_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME for your deployed model, and authenticate with Microsoft Entra ID (az login for local development). Your credential requires the Foundry User role on the Foundry project.
For Azure DTS, set DURABLE_TASK_SCHEDULER_CONNECTION_STRING. Use managed identity in production and grant the identity the Durable Task Data Contributor role on the intended scheduler/task hub. For a running local DTS emulator, set DTS_ENDPOINT=127.0.0.1:8080 instead. sdk_options() resolves these connection and authentication settings.
This example runs a read-only tool as an isolated activity with up to three attempts:
Samples and tutorials
- microsoft-foundry/foundry-samples LangGraph hosted agent samples: Run LangGraph agents locally or deploy them to Microsoft Foundry with Responses, Invocations, and A2A samples.
- Durable Task Scheduler (DTS) LangGraph samples: Run durable graphs and agents with per-tool retries, human approvals, checkpoint storage, and Azure Functions HTTP hosting.
- Azure-Samples/langchain-azure-openai-starter: Start with a production-ready LangChain and Azure OpenAI app template that lets you deploy directly to Azure with a single
azdcommand. - microsoft/langchain-for-beginners: A hands-on course introducing LangChain with Azure OpenAI.
- Azure-Samples/langchain-agent-python: Build and deploy LangChain agents on Azure.
Connect these docs to your agent of choice via MCP for real-time answers.

