Microsoft 集成

使用 LangChain Python 与 Microsoft 集成。

本页涵盖 LangChain 与 Microsoft Azure 及其他 Microsoft 产品的所有集成。

TIP

推荐：Microsoft Foundry

对于以 Microsoft Foundry 为核心的新 LangChain 或 LangGraph 应用，请从 langchain-azure-ai 开始。它添加了 Foundry 项目端点、Azure 凭据集成、Agent Service、托管、工具、Content Safety、检索和 Azure 可观测性。

如需直接访问 Azure OpenAI v1 API 模型、在 OpenAI 与 Azure 之间切换的代码、传统 Azure OpenAI API 版本、补全 LLM，或更小的依赖面，请使用 langchain-openai 包。

Foundry 资源包含 Azure OpenAI 能力，并添加了更广泛的模型目录、智能体服务和评估能力。如果你使用 Azure OpenAI 资源，请将其升级为 Foundry 资源，以保留现有的 API 端点、状态和安全配置，同时获得 Foundry 能力。

对于智能体托管，请使用 Microsoft Foundry 托管智能体在托管智能体平台上部署自定义 LangGraph 代码，该平台内置运行时、会话、扩缩容、身份和协议端点。

示例和教程：

microsoft-foundry/foundry-samples LangGraph 托管智能体示例：在本地运行 LangGraph 智能体，或使用 Responses、Invocations 和 A2A 示例将其部署到 Microsoft Foundry。
Azure-Samples/langchain-azure-openai-starter：从生产就绪的 LangChain 和 Azure OpenAI 应用模板开始，只需一条 azd 命令即可直接部署到 Azure。
microsoft/langchain-for-beginners：一门介绍如何配合 Azure OpenAI 使用 LangChain 的动手实践课程。
Azure-Samples/langchain-agent-python：在 Azure 上构建和部署 LangChain 智能体。

NOTE

Azure 上的 Claude

Microsoft Foundry 还提供对所有 Anthropic Claude 模型的访问，包括 Opus、Sonnet 和 Haiku。Claude 模型通过专用的 Anthropic 原生端点提供服务，而不是 Azure OpenAI v1 API。请将 langchain-anthropic 指向你的 Foundry Anthropic 端点。

选择包

langchain-azure-ai 和 langchain-openai 是互补关系，而非二选一。langchain-azure-ai 依赖 langchain-openai，其聊天和嵌入类分别继承自 ChatOpenAI 和 OpenAIEmbeddings，因此安装 Azure 包并不会从依赖链中移除 OpenAI 包。

使用下表来选择一个起点：

场景	包
以 Foundry 项目为核心的新应用	`langchain-azure-ai`
Foundry Agent Service、托管 LangGraph、Toolbox、Content Safety、Azure 工具或 Application Insights	`langchain-azure-ai`
从 Foundry 项目端点配置的嵌入	`langchain-azure-ai`
直接进行 Azure OpenAI v1 聊天调用	`langchain-openai`
同一份代码必须在 OpenAI 和 Azure 之间切换	`langchain-openai`
现有的 `AzureChatOpenAI` 应用	`langchain-openai`
传统的带日期 Azure OpenAI API 版本	`langchain-openai`
补全 LLM 接口	`langchain-openai`
最小依赖和运维面	`langchain-openai`

将现有的 langchain-openai 应用迁移到 langchain-azure-ai 并不是简单地替换导入即可完成：

配置不同。azure_endpoint、azure_deployment、api_version 和 token-provider 参数会变为 project_endpoint 或 endpoint、model 和 credential。
默认行为不同。AzureAIOpenAIApiChatModel 在解析项目端点时默认使用 Responses API。设置 use_responses_api=False 以保留 Chat Completions 行为。
langchain-azure-ai 中没有与 AzureOpenAI 等价的补全 LLM。
AzureChatOpenAI 带有 Azure 特有的响应元数据和内容过滤处理，而 Foundry 聊天模型不会复现这些行为。
两个包都遵循官方 OpenAI schema，因此 DeepSeek 或 Mistral 等兼容服务商返回的非标准字段可能无法保留。

聊天模型

Microsoft 提供三种通过 Azure 访问聊天模型的主要方式：

Microsoft Foundry（推荐用于以项目为中心的应用）：将 langchain-azure-ai 中的 AzureAIOpenAIApiChatModel 与 Foundry 项目端点和 Azure 凭据一起使用。该包还与 Foundry 智能体、托管、工具、Content Safety、检索和可观测性集成。
Azure OpenAI：对于直接的 v1 API 调用或在 OpenAI 与 Azure 之间切换的代码，使用 langchain-openai 中的 ChatOpenAI。对于传统 Azure OpenAI API 版本和现有应用，使用 AzureChatOpenAI。
Azure ML：允许使用 Azure Machine Learning 部署和管理自定义或微调的开源模型。

Microsoft Foundry

Microsoft Foundry 提供对模型和 Azure 服务的项目级访问。当你的应用使用 Foundry 项目、Azure 凭据或其他 Foundry 能力时，请使用 langchain-azure-ai 中的 AzureAIOpenAIApiChatModel。

pipuv

bash

pip install -U langchain-azure-ai

bash

uv add langchain-azure-ai

设置你的项目端点：

bash

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

然后创建聊天模型：

python

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(),
)

有关完整的设置指南，请参阅 Microsoft Foundry 聊天模型集成。

Azure OpenAI

如需直接访问 Azure OpenAI，请创建 Azure 部署并安装 langchain-openai 包：

pipuv

bash

pip install -U langchain-openai

bash

uv add langchain-openai

在 v1 API 上，直接对 Azure 端点使用 ChatOpenAI——无需 api_version：

bash

pip install azure-identity

python

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
)

对于传统 Azure OpenAI API 版本，请使用 AzureChatOpenAI：

python

from langchain_openai import AzureChatOpenAI

有关端到端设置、Entra ID 身份认证、工具调用和推理示例，请参阅 Azure ChatOpenAI 集成页面。

Responses API

Azure OpenAI 支持 Responses API，它提供有状态对话、内置工具（网络搜索、文件搜索、代码解释器）和结构化推理摘要。当你设置 reasoning 参数时，ChatOpenAI 会自动路由到 Responses API，你也可以使用 use_responses_api=True 显式启用：

python

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)

有关推理力度、推理摘要以及配合 Responses API 的流式传输的演练，请参阅 Azure ChatOpenAI 集成页面。

LLM

Microsoft 提供两种通过 Azure 访问 LLM 的主要方式：

Azure OpenAI（推荐）：将 Azure OpenAI 文本补全部署与 langchain-openai 中的 AzureOpenAI 一起使用。
Azure ML：使用托管在 Azure Machine Learning 在线端点上的自定义或开源模型。

Azure OpenAI

请参阅使用示例。

pipuv

bash

pip install -U langchain-openai

bash

uv add langchain-openai

python

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."))

嵌入模型

根据你的应用连接 Azure 的方式选择嵌入集成：

Microsoft Foundry（推荐用于以项目为中心的应用）：将 langchain-azure-ai 中的 AzureAIOpenAIApiEmbeddingsModel 与 Foundry 项目配置和 Azure 凭据一起使用。
Azure OpenAI：对于直接或传统的 Azure OpenAI 端点、现有应用或更小的依赖面，使用 langchain-openai 中的 AzureOpenAIEmbeddings。

Microsoft Foundry

安装 langchain-azure-ai：

pipuv

bash

pip install -U langchain-azure-ai

bash

uv add langchain-azure-ai

设置你的项目端点：

bash

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

然后创建嵌入模型：

python

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(),
)

NOTE

Foundry 项目配置目前会推导出一个直接的 /openai/v1 端点，因为嵌入尚未通过项目端点本身提供服务。

有关更多信息，请参阅 Microsoft Foundry 嵌入集成。

Azure OpenAI

请参阅使用示例。

pipuv

bash

pip install -U langchain-openai

bash

uv add langchain-openai

python

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.")

中间件

Azure AI Content Safety 中间件

Azure AI Content Safety 提供你可以通过中间件应用于 LangChain 智能体的护栏。langchain-azure-ai 包目前导出用于文本审核、图像审核、提示词注入检测、受保护材料检测和接地性（groundedness）评估的中间件。

安装中间件包：

pipuv

bash

pip install -U langchain-azure-ai

bash

uv add langchain-azure-ai

请参阅 Microsoft Foundry 中间件指南。

python

from langchain_azure_ai.agents.middleware import AzureContentModerationMiddleware

文档加载器

Azure Blob Storage

Azure Blob Storage 是 Microsoft 的云对象存储解决方案。Blob Storage 针对存储海量非结构化数据进行了优化。非结构化数据是指不遵循特定数据模型或定义的数据，例如文本或二进制数据。

Azure Blob Storage 专为以下用途而设计：

直接向浏览器提供图片或文档。
存储文件以供分布式访问。
流式传输视频和音频。
写入日志文件。
存储数据以用于备份和还原、灾难恢复以及存档。
存储数据以供本地或 Azure 托管的服务进行分析。

pipuv

bash

pip install langchain-azure-storage

bash

uv add langchain-azure-storage

请参阅 Azure Blob Storage Loader 的使用示例。

python

from langchain_azure_storage.document_loaders import AzureBlobStorageLoader

后端

Azure Blob Storage 后端

Azure Blob Storage 是 Microsoft 的云对象存储解决方案。AzureBlobBackend 实现了 Deep Agents 的 BackendProtocol，因此深度智能体可以将其整个工作区（文件、记忆和产物）持久化到 blob 容器中。

NOTE

AzureBlobBackend 是 langchain-azure-storage 包的一部分，该包目前处于 公开预览 阶段。

使用 deepagents 附加项安装（需要 Python 3.11+）：

pipuv

bash

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

bash

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

python

from langchain_azure_storage.deepagents import AzureBlobBackend

快速开始：

python

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"}]}
)

该后端默认使用 DefaultAzureCredential，并接受 credential 覆盖。

有关更多信息，请参阅后端集成。有关完整的使用细节和安全指南，请参阅包仓库。

记忆

Azure cosmos DB 聊天消息历史

Azure Cosmos DB 为对话式 AI 应用提供聊天消息历史存储，使你能够以低延迟和高可用性持久化和检索对话历史。

pipuv

bash

pip install langchain-azure-cosmosdb

bash

uv add langchain-azure-cosmosdb

配置你的 Azure Cosmos DB 连接（同步或异步，使用访问密钥或 Microsoft Entra ID）：

python

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!")

如需异步使用，请从同一个包导入 AsyncCosmosDBChatMessageHistory。

Azure cosmos DB 语义缓存

AzureCosmosDBNoSqlSemanticCache 使用向量相似度将 LLM 响应缓存到 Azure Cosmos DB for NoSQL 中，当再次看到语义相似的提示词时返回缓存结果。

pipuv

bash

pip install langchain-azure-cosmosdb

bash

uv add langchain-azure-cosmosdb

python

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)

如需异步使用，请导入 AsyncAzureCosmosDBNoSqlSemanticCache。

向量存储

Azure cosmos DB

AI 智能体可以依托 Azure Cosmos DB 作为统一的记忆系统解决方案，享受速度、规模和简洁性。该服务成功支撑了 OpenAI 的 ChatGPT 服务，使其以高可靠性和低维护成本实现动态扩展。它由 atom-record-sequence 引擎驱动，是全球首个提供无服务器模式的全局分布式 NoSQL、关系型和向量数据库服务。

以下是两个可提供向量存储功能的 Azure Cosmos DB API。

Azure cosmos DB for MongoDB（vCore）

Azure Cosmos DB for MongoDB vCore 让你可以轻松创建完全原生支持 MongoDB 的数据库。你可以运用自己的 MongoDB 经验，通过将应用指向 API for MongoDB vCore 账户的连接字符串，继续使用你喜爱的 MongoDB 驱动、SDK 和工具。在 Azure Cosmos DB for MongoDB vCore 中使用向量搜索，将你基于 AI 的应用与存储在 Azure Cosmos DB 中的数据无缝集成。

安装与设置

请参阅详细配置说明。

我们需要安装 langchain-azure-ai 和 pymongo 这两个 Python 包。

pipuv

bash

pip install langchain-azure-ai pymongo

bash

uv add langchain-azure-ai pymongo

在 Microsoft Azure 上部署 Azure cosmos DB

Azure Cosmos DB for MongoDB vCore 为开发者提供完全托管的、兼容 MongoDB 的数据库服务，让你能以熟悉的架构构建现代应用。

借助 Cosmos DB for MongoDB vCore，开发者在迁移现有应用或构建新应用时，可以享受原生 Azure 集成、低总拥有成本（TCO）以及熟悉的 vCore 架构带来的好处。

免费注册立即开始。

请参阅使用示例。

python

from langchain_azure_ai.vectorstores import AzureCosmosDBMongoVCoreVectorSearch

Azure cosmos DB NoSQL

Azure Cosmos DB for NoSQL 现已在预览版中提供向量索引和搜索。该功能旨在处理高维向量，能够以任意规模实现高效且准确的向量搜索。现在你可以将向量与数据一起直接存储在文档中。这意味着数据库中的每个文档不仅可以包含传统的无架构数据，还可以包含高维向量作为文档的其他属性。这种数据和向量的共置实现了高效的索引和搜索，因为向量与其所代表的数据存储在同一个逻辑单元中。这简化了数据管理、AI 应用架构，以及基于向量的操作的效率。

安装与设置

查看详细配置说明。

我们需要安装 langchain-azure-cosmosdb 和 azure-cosmos python 包。

pipuv

bash

pip install langchain-azure-cosmosdb azure-cosmos

bash

uv add langchain-azure-cosmosdb azure-cosmos

在 Microsoft Azure 上部署 Azure cosmos DB

Azure Cosmos DB 通过动态且弹性的自动扩缩容实现极快的响应能力，为现代应用和智能工作负载提供解决方案。它可用于每个 Azure 区域，并能自动将数据复制到更靠近用户的位置。它具备 SLA 保障的低延迟和高可用性。

免费注册即刻开始使用。

查看使用示例。

python

from langchain_azure_cosmosdb import AzureCosmosDBNoSqlVectorSearch

Azure Database for PostgreSQL

Azure Database for PostgreSQL - Flexible Server 是一项基于开源 Postgres 数据库引擎的关系数据库服务。它是一项完全托管的数据库即服务，能够以可预测的性能、安全性、高可用性和动态可扩展性处理关键任务工作负载。

有关 Azure Database for PostgreSQL，请参阅设置说明。

只需使用 Azure 门户中的连接字符串即可。

由于 Azure Database for PostgreSQL 是开源 Postgres，你可以使用 LangChain 的 Postgres 支持连接到 Azure Database for PostgreSQL。

Azure SQL Database

Azure SQL Database 是一项强大的服务，融合了可扩展性、安全性和高可用性，具备现代数据库解决方案的所有优势。它还提供专用的 Vector 数据类型和内置函数，可直接在关系数据库中简化向量嵌入的存储和查询。这消除了对独立的向量数据库及相关集成的需求，在降低整体复杂性的同时提高了解决方案的安全性。

通过利用你当前的 SQL Server 数据库进行向量搜索，你可以在增强数据能力的同时最大限度地降低费用，并避免迁移到新系统的挑战。

安装与设置

查看详细配置说明。

我们需要安装 langchain-sqlserver python 包。

bash

!pip install langchain-sqlserver==0.1.1

在 Microsoft Azure 上部署 Azure SQL DB

免费注册即刻开始使用。

查看使用示例。

python

from langchain_sqlserver import SQLServer_VectorStore

向量存储

Azure Database for PostgreSQL

Azure Database for PostgreSQL - Flexible Server 是一项基于开源 Postgres 数据库引擎的关系数据库服务。它是一项完全托管的数据库即服务，能够以可预测的性能、安全性、高可用性和动态可扩展性处理关键任务工作负载。

有关 Azure Database for PostgreSQL，请参阅设置说明。

你需要在数据库中启用 pgvector 扩展才能将 Postgres 用作向量存储。启用该扩展后，你可以使用 LangChain 中的 PGVector 连接到 Azure Database for PostgreSQL。

查看使用示例。只需使用 Azure 门户中的连接字符串即可。

工具

Microsoft Foundry 工具

Microsoft Foundry 为 Azure AI Content Understanding、Document Intelligence、Image Analysis 和 Text Analytics for Health 提供 LangChain 服务工具。

使用 tools extra 安装该包：

pipuv

bash

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

bash

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

参阅 Microsoft Foundry 工具指南。

python

from langchain_azure_ai.tools import AzureAIDocumentIntelligenceTool

图像生成工具

Microsoft Foundry Models 在目录中有多个可用于图像生成的模型。

参阅 Microsoft Foundry 工具指南。

python

from langchain_azure_ai.tools import AzureOpenAIModelImageGenTool

转录工具

Microsoft Foundry Models 在目录中有可用于语音转文本转录的 Whisper 模型。

参阅 Microsoft Foundry 工具指南。

python

from langchain_azure_ai.tools import AzureOpenAITranscriptionsTool

代码解释器工具（服务端）

使用 Code Interpreter 工具在沙箱容器中于服务端运行 Python 代码。

参阅 Microsoft Foundry 工具指南。

python

from langchain_azure_ai.tools.builtin import CodeInterpreterTool

网络搜索工具（服务端）

在互联网上搜索最新信息和来源。

参阅 Microsoft Foundry 工具指南。

python

from langchain_azure_ai.tools.builtin import WebSearchTool

文件搜索工具（服务端）

在向量存储中搜索相关的文档内容。

参阅 Microsoft Foundry 工具指南。

python

from langchain_azure_ai.tools.builtin import FileSearchTool

图像生成工具（服务端）

在 Azure AI Foundry 中使用 GPT 图像模型在服务端生成或编辑图像。

参阅 Microsoft Foundry 工具指南。

python

from langchain_azure_ai.tools.builtin import ImageGenerationTool

MCP 工具（服务端）

访问外部的 Model Context Protocol (MCP) 服务器。

参阅 Microsoft Foundry 工具指南。

python

from langchain_azure_ai.tools.builtin import McpTool

Azure Container Apps Dynamic Sessions

我们需要从 Azure Container Apps 服务获取 POOL_MANAGEMENT_ENDPOINT 环境变量。请参阅 Azure 动态会话设置说明。

我们需要安装一个 python 包。

pipuv

bash

pip install langchain-azure-dynamic-sessions

bash

uv add langchain-azure-dynamic-sessions

查看使用示例。

python

from langchain_azure_dynamic_sessions import SessionsPythonREPLTool

Azure Logic Apps

触发 Azure Logic Apps 工作流，以自动化业务流程和集成。

使用 tools extra 安装该包：

pipuv

bash

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

bash

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

参阅 Azure Logic Apps 集成指南。

python

from langchain_azure_ai.tools import AzureLogicAppTool

工具包

Microsoft Foundry Project Toolbox

通过 Model Context Protocol (MCP) 从 Azure AI Foundry Toolbox 动态加载工具。

使用 tools extra 安装该包：

pipuv

bash

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

bash

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

参阅 Azure AI Foundry Toolbox 指南。

python

from langchain_azure_ai.tools import AzureAIProjectToolbox

Microsoft Foundry 工具（原 Azure AI Services）

安装集成包：

pipuv

bash

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

bash

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

查看使用示例。

python

from langchain_azure_ai.tools import AzureAIServicesToolkit

AzureAIServicesToolkit 工具包包含以下工具：

图像分析：AzureAIImageAnalysisTool
文档智能：AzureAIDocumentIntelligenceTool
语音转文本：AzureAISpeechToTextTool
文本转语音：AzureAITextToSpeechTool
健康文本分析：AzureAITextAnalyticsHealthTool

运行时

Microsoft Foundry 托管智能体

Microsoft Foundry 托管智能体在托管运行时中运行自定义 LangGraph 代码。使用 langchain_azure_ai.agents.hosting 包来暴露编译后的 LangGraph 图，同时由 Foundry 管理运行时、会话、扩缩容、身份和协议端点。

NOTE

LangGraph 托管支持需要 langchain-azure-ai[hosting]>=1.2.8。

开始之前，你需要一个 Azure 订阅、一个 Foundry 项目、一个已部署的聊天模型、Python 3.10 或更高版本，以及 Azure CLI 身份认证。部署智能体还需要在项目上拥有 Foundry Project Manager 角色。

根据客户端与智能体的交互方式选择托管协议：

协议	运行参数	SDK 主机类	端点	使用场景
Responses	`--protocol responses`	`ResponsesHostServer`	`/responses`	你需要 OpenAI 兼容的聊天、流式传输、响应历史记录或会话线程。大多数对话式智能体都可以从这里开始。
Invocations	`--protocol invocations`	`InvocationsHostServer`	`/invocations`	你需要自定义 JSON 结构、Webhook 风格端点或非对话式处理。

NOTE

对于使用基于 BaseChatOpenAI 的模型并搭配 Responses API 的托管图，请使用 output_version="responses/v1"。在 langchain-openai 1.0.0 或更高版本中，你可以省略此设置，除非被 LC_OUTPUT_VERSION 覆盖。此指导适用于 Responses 和 Invocations 两种托管协议。

有关完整运行示例，请参阅 Responses 协议和 Invocations 协议。

使用配置驱动的运行器

如果你的智能体已经使用 LangGraph CLI 运行，请在同一项目目录中使用 langchain_azure_ai.agents.hosting.run 工具。该运行器使用现有的 langgraph.json 配置来加载编译后的图，因此无需更改代码。

设置 Foundry 项目端点和模型部署名称，然后在启动主机时选择协议：

bash

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

部署时，将 azure.yaml 中智能体服务上的 codeConfiguration.entryPoint 设置为相同的运行器和协议。保留现有的项目路径、运行时和依赖解析设置：

yaml

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

使用 SDK 主机类

当你需要自定义服务器构建、直接控制服务器生命周期，或实现诸如自定义路由或处理器之类的高级托管行为时，请使用 SDK 主机类：

python

from langchain_azure_ai.agents.hosting import ResponsesHostServer

ResponsesHostServer(graph).run()

要部署任一方案，请使用 azd ai agent init 初始化托管式智能体项目，使用 azd ai agent run 在本地测试它，并使用 azd deploy 进行部署。仅当你需要创建 Foundry 项目或其他 Azure 资源时，才需要先运行 azd provision。你也可以使用 Foundry Toolkit Visual Studio Code 扩展进行部署。

Microsoft Learn 指南包含两种协议的完整示例，涵盖对话状态、人在回路流程、测试、部署和故障排查。

数据集

创建数据集

运行评估

评估技术

定义评估目标

打分方法

实验配置

多模态评估

分析实验结果

微调

教程

常见数据类型

评估器类型

UI

SDK

框架与集成

改进评估器

反馈

追踪设置

集成

手动埋点

配置与故障排除

项目与环境设置

高级追踪技术

数据与隐私

故障排除指南

查看与管理追踪

批量导出追踪数据

轨迹视图

数据类型参考

监控与告警

在线评估器

自动化

开发你的应用

设置依赖

持久化

能力

助手

运行

并发消息处理

如何构建

鉴权与访问控制

自定义鉴权教程

服务器定制

静态加密

替换内置后端

扩展 HTTP 服务器

请求头与日志

部署指南

参考

配置

参考

提示词

创建与管理提示词

连接模型

上下文中枢

教程

全栈 Web 应用

Agent Server API

控制平面 API

计费与用量

参考

按云服务商起步

用 Terraform 部署

AWS

GCP

Azure

安装实例

配置实例

连接外部服务

平台鉴权与访问控制

管理实例

自托管可观测性

混合部署

脚本

参考

组织