Microsoft Foundry 中间件集成

使用 LangChain Python 集成 Azure AI 中间件。

专为 Microsoft Foundry 和 Azure AI Content Safety 设计的中间件。了解更多关于中间件的信息。

这些中间件类位于 langchain-azure-ai 包中，从 langchain_azure_ai.agents.middleware 导出。

Azure AI Content Safety 中间件目前在上游标记为实验性。随着 Azure AI Content Safety 和 LangChain 中间件支持的不断成熟，预计 API 接口会有所变化。

概述

中间件	描述
Text moderation	Screen input and output text for harmful content and blocklist matches
Image moderation	Screen image inputs and outputs using Azure AI Content Safety image analysis
Prompt shield	Detect direct and indirect prompt injection attempts
Protected material	Detect copyrighted or otherwise protected text or code
Groundedness	Evaluate model outputs against grounding sources and flag hallucinations

Features

• Text moderation for harmful content and custom blocklists.
• Image moderation for data URLs and public HTTP(S) image inputs.
• Prompt injection detection with Prompt Shield.
• Protected material detection for text and code.
• Groundedness evaluation for generated answers against retrieved context.
• Custom context_extractor hooks to adapt screening and evaluation to your agent state.

设置

To use the Azure AI Content Safety middleware, install the integration package, configure either an Azure AI Foundry project endpoint or an Azure Content Safety endpoint, and provide a credential.

安装

Install the package:

pip

pip install -U langchain-azure-ai

凭证

For authentication, pass either DefaultAzureCredential() or an API-key string through the credential argument. Using a Foundry Project requires the use of Microsoft Entra ID for authentication.

Initialize credential

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()

实例化

The middleware supports two endpoint styles:

• An Azure Content Safety resource endpoint via AZURE_CONTENT_SAFETY_ENDPOINT
• An Azure AI Foundry project endpoint via AZURE_AI_PROJECT_ENDPOINT

If both are available, prefer project_endpoint because it gives better defaults for Azure AI Foundry-based workflows. In most setups, you can set the environment variable once and omit endpoint or project_endpoint from each middleware instantiation.

Configure endpoint

import os

os.environ["AZURE_AI_PROJECT_ENDPOINT"] = "https://<resource>.services.ai.azure.com/api/projects/<project>"

Import and configure your middleware from langchain_azure_ai.agents.middleware.

Initialize middleware

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.agents.middleware import AzureContentModerationMiddleware

middleware = AzureContentModerationMiddleware(
    project_endpoint="https://<resource>.services.ai.azure.com/api/projects/<project>",
    credential=DefaultAzureCredential(),
    categories=["Hate", "Violence"],
    exit_behavior="error",
)

Use with an agent

Pass middleware to create_agent in order. You can combine Azure AI middleware with built-in middleware.

Agent with middleware

from azure.identity import DefaultAzureCredential
from langchain.agents import create_agent
from langchain_azure_ai.agents.middleware import AzureContentModerationMiddleware

agent = create_agent(
    model="azure_ai:gpt-5.4",
    middleware=[
        AzureContentModerationMiddleware(
            project_endpoint="https://<resource>.services.ai.azure.com/api/projects/<project>",
            credential=DefaultAzureCredential(),
            categories=["Hate", "Violence"],
            exit_behavior="error",
        )
    ],
)

If AZURE_AI_PROJECT_ENDPOINT is already set, you can usually omit project_endpoint during instantiation.

Azure AI Content Safety

Text moderation

Use AzureContentModerationMiddleware to screen the last HumanMessage before the agent runs and the last AIMessage after the agent runs. This middleware uses Azure AI Content Safety harm detection and can also check custom blocklists configured in your resource.

文本审核适用于以下场景：

• 在模型调用前阻止有害的用户输入
• 在模型输出到达最终用户前进行过滤
• 在受监管或企业部署中强制执行自定义阻止列表
• 使用不同的类别和方向设置组合多个审核通道

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.agents.middleware import AzureContentModerationMiddleware

middleware = AzureContentModerationMiddleware(
    project_endpoint="https://<resource>.services.ai.azure.com/api/projects/<project>",
    credential=DefaultAzureCredential(),
    categories=["Hate", "SelfHarm", "Sexual", "Violence"],
    severity_threshold=4,
    exit_behavior="error",
    apply_to_input=True,
    apply_to_output=True,
)

配置选项

categories · list[str] | None

Harm categories 提供自然语言接口alyze. Valid values are 'Hate', 'SelfHarm', 'Sexual', and 'Violence'. Defaults to all four categories.

severity_threshold · int · default: "4"

Minimum severity score from 0 to 6 that triggers the configured behavior.

exit_behavior · string · default: "error"

One of 'error', 'continue', or 'replace'.

apply_to_input · bool · default: "True"

Whether to screen the last HumanMessage before the agent runs.

apply_to_output · bool · default: "True"

Whether to screen the last AIMessage after the agent runs.

blocklist_names · list[str] | None

Names of custom blocklists configured in your Azure Content Safety resource.

context_extractor · Callable | None

Optional callable that extracts the text to screen from agent state and runtime.

Image moderation

Use AzureContentModerationForImagesMiddleware when your agent handles visual content. It extracts images from the latest input or output message and screens them with the Azure AI Content Safety image analysis API.

This middleware supports:

• Base64 data URLs such as data:image/png;base64,...
• Public HTTP(S) image URLs

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.agents.middleware import (
    AzureContentModerationForImagesMiddleware,
)

middleware = AzureContentModerationForImagesMiddleware(
    endpoint="https://<resource>.cognitiveservices.azure.com/",
    credential=DefaultAzureCredential(),
    categories=["Hate", "SelfHarm", "Sexual", "Violence"],
    severity_threshold=4,
    exit_behavior="error",
    apply_to_input=True,
    apply_to_output=False,
)

配置选项

categories · list[str] | None

Image harm categories 提供自然语言接口alyze. Defaults to all four supported categories.

severity_threshold · int · default: "4"

Minimum severity score from 0 to 6 that triggers the configured behavior.

exit_behavior · string · default: "error"

One of 'error' or 'continue'.

apply_to_input · bool · default: "True"

Whether to screen images in the latest HumanMessage.

apply_to_output · bool · default: "False"

Whether to screen images in the latest AIMessage.

context_extractor · Callable | None

Optional callable that extracts images from agent state and runtime.

Prompt shield

Use AzurePromptShieldMiddleware to detect prompt injection in user prompts and optional supporting documents. By default it screens input only, because prompt injection is usually an input-side attack, but you can also enable output screening.

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.agents.middleware import AzurePromptShieldMiddleware

middleware = AzurePromptShieldMiddleware(
    project_endpoint="https://<resource>.services.ai.azure.com/api/projects/<project>",
    credential=DefaultAzureCredential(),
    exit_behavior="continue",
    apply_to_input=True,
    apply_to_output=False,
)

配置选项

exit_behavior · string · default: "error"

One of 'error', 'continue', or 'replace'.

apply_to_input · bool · default: "True"

Whether to screen the latest HumanMessage before the agent runs.

apply_to_output · bool · default: "False"

Whether to screen the latest AIMessage after the agent runs.

context_extractor · Callable | None

Optional callable that extracts the user prompt and grounding documents from agent state and runtime.

Protected material

Use AzureProtectedMaterialMiddleware to detect protected content such as copyrighted text or code. This middleware can screen both the latest user input and the latest model output.

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.agents.middleware import AzureProtectedMaterialMiddleware

middleware = AzureProtectedMaterialMiddleware(
    endpoint="https://<resource>.cognitiveservices.azure.com/",
    credential=DefaultAzureCredential(),
    type="code",
    exit_behavior="replace",
    apply_to_input=False,
    apply_to_output=True,
    violation_message="Protected material detected. Please provide a higher-level summary instead.",
)

配置选项

type · string · default: "text"

The content type to screen: 'text' or 'code'.

exit_behavior · string · default: "error"

One of 'error', 'continue', or 'replace'.

apply_to_input · bool · default: "True"

Whether to screen the latest HumanMessage.

apply_to_output · bool · default: "True"

Whether to screen the latest AIMessage.

context_extractor · Callable | None

Optional callable that extracts text from agent state and runtime.

Groundedness

Use AzureGroundednessMiddleware to evaluate whether a model response is grounded in the context available to the agent. Unlike the other middleware classes on this page, groundedness runs after model generation and inspects the generated answer against supporting sources.

By default, groundedness collects sources from the current conversation, including system content, tool outputs, and relevant annotations attached to model responses.

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.agents.middleware import AzureGroundednessMiddleware

middleware = AzureGroundednessMiddleware(
    project_endpoint="https://<resource>.services.ai.azure.com/api/projects/<project>",
    credential=DefaultAzureCredential(),
    domain="Generic",
    task="QnA",
    exit_behavior="continue",
)

配置选项

domain · string · default: "Generic"

The analysis domain. Supported values are 'Generic' and 'Medical'.

task · string · default: "Summarization"

The task type for the analysis. Supported values are 'Summarization' and 'QnA'.

exit_behavior · string · default: "error"

One of 'error' or 'continue'.

context_extractor · Callable | None

Optional callable that extracts the answer, grounding sources, and optional question from agent state and runtime.

API 参考

For the full public API, see the middleware exports in langchain_azure_ai.agents.middleware and the underlying Content Safety middleware package in langchain_azure_ai.agents.middleware.content_safety.

---

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.