你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

什么是托管代理?

使用开源框架生成代理应用程序时,通常管理容器化、Web 服务器设置、安全集成、内存持久性、基础结构缩放、数据传输、检测和版本回滚。 在异类云环境中,这些任务变得更加具有挑战性。

Microsoft Foundry 代理服务中的托管代理解决了这些难题。 使用此完全托管的平台,您可以安全地大规模部署和运营 AI 代理。 可以通过无缝部署和管理使用自定义代理代码或首选代理框架。

先决条件

了解关键概念

托管代理

托管代理是在 Foundry 代理服务上运行的容器化代理 AI 应用程序。 与基于提示的代理程序不同,托管代理是通过代码构建的,并以容器映像的形式部署在Microsoft管理的按需付费基础设施上。

托管代理遵循标准生命周期:创建、启动、更新、停止、删除。 每个阶段提供特定的功能和状态转换,以有效管理代理部署。

注释

托管代理目前正处于预览阶段。 有关预览期间的托管定价和限制,请参阅 Microsoft Foundry 主页。

宿主适配器

宿主适配器是一个框架抽象层,可将常用代理框架自动转换为与 Microsoft Foundry 兼容的 HTTP 服务。 此适配器无需手动实现 REST API 和消息处理。

托管适配器为开发人员提供了几个关键优势:

单行部署:将复杂的代理部署转换为单个代码行(from_langgraph(my_agent).run()),该代码行可立即托管代理 localhost:8088 ,其中包含所有必要的 HTTP 终结点、流式处理支持和 Foundry 协议符合性。

自动协议转换:适配器处理 Foundry 请求/响应格式与代理框架的本机数据结构之间的所有复杂转换。 这些活动包括:

  • 对话管理
  • 消息序列化
  • 流式事件生成

内置生产功能:在不进行其他配置的情况下自动获取以下企业就绪功能:

  • OpenTelemetry 跟踪
  • 跨域资源共享 (CORS) 支持
  • 服务器发送事件 (SSE) 流式传输
  • 结构化日志记录

无缝 Foundry 集成:本地开发的代理立即使用 Foundry 响应 API、聊天管理和身份验证流。 这种集成弥合了开发框架与 Azure 生产 AI 平台之间的差距。

托管服务能力

Foundry代理服务处理事项:

  • 代理的配置和自动扩展。
  • 会话编排和状态管理。
  • 标识管理。
  • 与 Microsoft Foundry 工具和模型集成。
  • 内置可观测性和评估功能。
  • 企业级安全性、合规性和治理。

重要

如果使用 Foundry 代理服务来托管与非Microsoft服务器或代理交互的代理,请自行承担此风险。 建议查看与非Microsoft服务器或代理共享的所有数据,并了解保留数据和位置的非Microsoft做法。 您有责任管理您的数据是否流出组织的 Azure 合规性和地理边界,以及任何相关影响。

框架和语言支持

Framework Python C#
Microsoft代理框架
LangGraph
自定义代码

公共适配器包

  • Python:azure-ai-agentserver-coreazure-ai-agentserver-agentframeworkazure-ai-agentserver-langgraph
  • .NET: Azure.AI.AgentServer.CoreAzure.AI.AgentServer.AgentFramework

在本地打包代码和测试

在部署到 Microsoft Foundry 之前,可以在本地生成和测试代理:

  1. 在本地运行代理:使用托管适配器启动自动将代理公开为 REST API 的本地 Web 服务器。
  2. 使用 REST 调用进行测试:本地服务器运行 localhost:8088 并接受标准 HTTP 请求。
  3. 生成容器映像:使用 azure-ai-agents-server-* 包包装代理代码,从源文件创建容器映像。
  4. 使用 Azure 开发人员 CLI:用于 azd 简化打包和部署过程。

使用 REST API 进行本地测试

使用托管适配器在本地运行代理时,它会自动启动 localhost:8088Web 服务器。 可以使用任何 REST 客户端测试代理:

@baseUrl = http://localhost:8088

POST {{baseUrl}}/responses
Content-Type: application/json
 
{
    "input": {
        "messages": [
            {
                "role": "user",
                "content": "Where is Seattle?"
            }
        ]
    }
}

使用此本地测试方法,可以:

  • 在容器化之前验证代理行为。
  • 在开发环境中排查问题。
  • 快速测试不同的输入方案。
  • 验证 API 与 Foundry 响应 API 的兼容性。

使用 Azure 开发人员 CLI 创建托管代理

开发人员可以使用 Azure 开发人员 CLIai agent 扩展在 Microsoft Foundry 上无缝快速预配和部署代理应用程序。

此扩展简化了 Foundry 资源、模型、工具和知识资源的设置。 例如,它简化了以下设置:用于自带容器的 Azure 容器注册表、用于日志记录和监视的 Application Insights、托管标识以及基于角色的访问控制 (RBAC)。 换句话说,它提供了在 Foundry 代理服务中开始使用托管代理所需的一切。

此扩展当前处于预览状态。 不建议将其用于生产用途。

开始之前:

  1. 在设备上安装 Azure 开发人员 CLI。

    如果已安装 Azure 开发人员 CLI,请检查是否已安装最新版本 azd

    azd version
    

    若要升级到最新版本,请参阅 安装或更新 Azure 开发人员 CLI

  2. 如果从没有现有 Foundry 资源开始,并且想要简化所有必需的基础结构预配和 RBAC,请下载 Foundry 初学者模板。 该模板会自动安装 ai agent 扩展。

    azd init -t https://github.com/Azure-Samples/azd-ai-starter-basic
    

    检查所有已安装的扩展:

    azd ext list
    

    建议安装最新版本的 Foundry azd 代理扩展。

    如果已有要在其中部署代理的 Foundry 项目,并且只想预配部署代理所需的其他资源,请之后运行以下命令:

    azd ai agent init --project-id /subscriptions/[SUBSCRIPTIONID]/resourceGroups/[RESOURCEGROUPNAME]/providers/Microsoft.CognitiveServices/accounts/[ACCOUNTNAME]/projects/[PROJECTNAME]
    
  3. 通过在代理定义中配置参数来初始化模板:

    azd ai agent init -m <repo-path-to-agent.yaml>
    

    要托管在 Foundry 上的代理的 GitHub 存储库包含应用程序代码、引用的依赖项、用于容器化的 Dockerfile 以及 agent.yaml 包含代理定义的文件。 若要配置代理,请为系统提示的参数设置值。 此操作会将你的智能体在下载的模板的 Services 下注册到 azure.yaml 中。 可以在 GitHub 上开始使用示例。

  4. 若要打开并查看与基于 azd 的部署相关的所有 Bicep 和配置文件,请使用以下命令:

    code .
    
  5. 在 Foundry 上将代理代码打包、预配和部署为托管应用程序:

    azd up
    

    此命令对命令 azd infra generateazd provisionazd deploy 的底层执行进行了抽象化。 它还在 Foundry 代理服务上创建托管代理版本和部署。 如果您已有一个托管代理的版本,azd 将创建相同代理的新版本。 若要详细了解如何执行非版本控制更新以及启动、停止和删除托管代理部署和版本,请参阅本文 的管理部分

请确保已启用 RBAC ,以便 azd 为你预配服务和模型。

角色和权限

如果有现有的 Foundry 资源,并且需要创建新的 Foundry 项目来部署托管代理,则需要帐户所有者和 Azure AI 用户角色。

如果有现有项目并且想要在项目中创建模型部署和容器注册表,则除了 Azure 订阅上的参与者角色外,还需要 Foundry 上的帐户所有者和 Azure AI 用户角色。

如果项目中已配置好部署托管智能体所需的所有内容,则你需要读取者角色和 Azure AI 用户角色。

资源清理

若要防止产生不必要的费用,在完成应用程序工作后,请务必清理 Azure 资源。

何时清理:

  • 完成测试或演示应用程序后
  • 不再需要应用程序或过渡到其他项目或环境时
  • 完成开发并准备好停用该应用程序时

若要删除所有关联的资源并关闭应用程序,请运行以下命令:

azd down

此过程可能需要长达 20 分钟才能完成。

使用 Foundry SDK 创建托管代理

创建托管代理时,系统会在 Microsoft Foundry 中注册代理定义,并尝试为该代理版本创建部署。

部署的先决条件

在部署托管代理之前,请确保具备:

  • Azure 容器注册表中托管的容器映像。 有关详细信息,请参阅 创建专用容器注册表

  • 在 Azure 容器注册表中分配角色的访问权限。 至少需要对容器注册表具有用户访问管理员或所有者权限。

  • 已安装的 Azure AI Projects SDK:

    pip install azure-ai-projects
    

生成 Docker 映像并将其推送到 Azure 容器注册表

若要构建代理为 Docker 容器并将其上传到 Azure 容器注册表,请执行以下步骤:

  1. 在本地生成 Docker 映像:

    docker build -t myagent:v1 .
    
  2. 登录到 Azure 容器注册表:

    az acr login --name myregistry
    
  3. 为注册表标记你的映像:

    docker tag myagent:v1 myregistry.azurecr.io/myagent:v1
    
  4. 将映像推送到 Azure 容器注册表:

    docker push myregistry.azurecr.io/myagent:v1
    

有关在 Azure 容器注册表中使用 Docker 映像的详细指南,请参阅 推送和拉取 Docker 映像

配置 Azure 容器注册表权限

创建智能体之前,授予项目的托管标识从存储映像的容器注册表中拉取映像的权限。 此步骤可确保容器中的所有依赖项都可用。

  1. Azure 门户中,转到 Foundry 项目资源。

  2. 在左窗格中,选择“标识”。

  3. “系统分配”下,复制 “对象”(主体)ID 值。 此值是你要分配 Azure 容器实例角色的托管标识。

  4. 通过在容器注册表上为项目的托管标识分配容器注册表存储库读取者角色,授予拉取权限。 有关详细步骤,请参阅 Azure 容器注册表角色和权限

创建帐户级功能主机

不支持更新功能主机。 如果你已为 Microsoft Foundry 帐户创建功能主机,则必须删除现有功能主机并将属性 enablePublicHostingEnvironment 设置为 true 进行重新创建。

curl --request PUT \
  --url 'https://management.azure.com/subscriptions/[SUBSCRIPTIONID]/resourceGroups/[RESOURCEGROUPNAME]/providers/Microsoft.CognitiveServices/accounts/[ACCOUNTNAME]/capabilityHosts/accountcaphost?api-version=2025-10-01-preview' \
  --header 'content-type: application/json' \
  --data '{
  "properties": {
    "capabilityHostKind": "Agents",
    "enablePublicHostingEnvironment": true
  }

创建托管代理版本

使用 Azure AI Projects SDK 创建和注册代理:

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import ImageBasedHostedAgentDefinition, ProtocolVersionRecord, AgentProtocol
from azure.identity import DefaultAzureCredential

# Initialize the client
client = AIProjectClient(
    endpoint="https://your-project.services.ai.azure.com/api/projects/project-name",
    credential=DefaultAzureCredential()
)

# Create the agent from a container image
agent = client.agents.create_version(
    agent_name="my-agent",
    definition=ImageBasedHostedAgentDefinition(
        container_protocol_versions=[ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")],
        cpu="1",
        memory="2Gi",
        image="your-registry.azurecr.io/your-image:tag",
        environment_variables={
            "AZURE_AI_PROJECT_ENDPOINT": "https://your-project.services.ai.azure.com/api/projects/project-name",
            "API_KEY": "your-api-key",
            "MODEL_NAME": "gpt-4",
            "CUSTOM_SETTING": "value"
        }
    )
)

print(f"Agent created: {agent.id}")

下面是关键参数:

  • PROJECT_ENDPOINT:Foundry 项目的端点 URL。
  • AGENT_NAME:代理的唯一名称。
  • CONTAINER_IMAGE:包含标记的完整 Azure 容器注册表映像 URL。
  • CPU/Memory:资源分配(例如 CPU 12Gi 内存)。

注释

  • 确保可从 Foundry 项目访问容器映像。
  • DefaultAzureCredential 自动处理身份验证。

在创建代理后,它将显示在 Foundry 门户中。

管理托管代理

更新代理

可以通过两种方式更新代理:有版本更新和无版本更新。

版本更新

使用版本化更新以修改代理的运行时配置。 此过程将创建新版本的代理。

触发新版本的更改包括:

  • 容器映像:更新到新映像或标记。
  • 资源分配:更改 CPU 或内存设置。
  • 环境变量:添加、删除或修改环境变量。
  • 协议版本:更新支持的协议版本。

要创建新版本,请使用在创建示例中所示的相同方法 client.agents.create_version(),并应用您的更新配置。

非版本化更新

使用非版本控制更新来修改水平缩放配置(最小和最大副本)或代理元数据,例如说明和标记。 此过程不会创建新版本。

az cognitiveservices agent update

此代码的参数包括:

论点 必选 Description
--account-name -a Foundry Tools 帐户名称。
--agent-version Foundry Tools 托管代理版本。
--name -n Foundry Tools 托管代理名称。
--project-name AI 项目名称。
--description 智能体描述。
--max-replicas 横向扩展的最大副本数。
--min-replicas 横向扩展的最小副本数。
--tags 空格分隔标记: key[=value] [key[=value] ...]。 使用两个单引号 ('') 清除现有标记。

下面是一个示例:

az cognitiveservices agent update --account-name myAccount --project-name myProject --name myAgent --agent-version 1 --min-replicas 1 --max-replicas 2

启动智能体部署

创建托管代理版本后,可以使用 CLI 扩展启动部署 az ,使其可用于请求。 还可以启动已停止的托管代理。

az cognitiveservices agent start

此代码的参数包括:

论点 必选 Description
--account-name -a Foundry Tools 帐户名称
--agent-version Foundry Tools 托管智能体版本
--name -n Foundry Tools 托管代理名称
--project-name AI 项目名称
--min-replicas 水平扩展时的最小副本数
--max-replicas 水平缩放的最大副本数

下面是一个示例:

az cognitiveservices agent start --account-name myAccount --project-name myProject --name myAgent --agent-version 1

当您启动一个代理时:

  • 当前状态: 已停止
  • 允许的操作:启动
  • 临时状态: 正在启动
  • 最终状态: 已启动 (如果成功)或 失败 (如果失败)

停止代理部署

可以通过将代理部署配置的最大副本数设置为零,使用以下命令来强制停止托管代理:

az cognitiveservices agent stop

此代码的参数包括:

论点 必选 Description
--account-name -a Foundry Tools 帐户名称
--agent-version Foundry Tools 托管智能体版本
--name -n Foundry Tools 托管代理名称
--project-name AI 项目名称

下面是一个示例:

az cognitiveservices agent stop --account-name myAccount --project-name myProject --name myAgent --agent-version 1

停止代理时:

  • 当前状态: 正在运行
  • 允许的操作:停止
  • 暂时状态: 正在停止
  • 最终状态: 已停止 (如果成功)或 正在运行 (如果失败)

删除代理

可以根据要删除的内容,在各种级别删除代理。

仅删除部署

以下命令停止正在运行的代理,但保留代理版本以供将来使用。 如果要暂时停止代理或切换到其他版本,请使用它。

az cognitiveservices agent delete-deployment

此代码的参数包括:

论点 必选 Description
--account-name -a Foundry Tools 帐户名称
--agent-version Foundry Tools 托管智能体版本
--name -n Foundry Tools 托管代理名称
--project-name AI 项目名称

删除代理

以下命令删除代理的所有版本和部署。 当不再需要代理并想要清理所有关联的资源时,请使用它。

如果提供 agent_version 并删除代理部署,则会删除与该版本关联的代理定义。 如果代理部署正在运行,则该操作不会成功。

如果未提供 agent_version,将删除与代理名称关联的所有代理版本。

az cognitiveservices agent delete

此代码的参数包括:

论点 必选 Description
--account-name -a Foundry Tools 帐户名称。
--name -n Foundry Tools 托管代理名称。
--project-name AI 项目名称。
--agent-version Foundry Tools 托管代理版本。 如果未提供,该命令将删除所有版本。

列出托管代理

列出托管代理的所有版本

az cognitiveservices agent list-versions

此代码的参数包括:

论点 必选 Description
--account-name -a Foundry Tools 帐户名称
--name -n Foundry Tools 托管代理名称
--project-name AI 项目名称

显示托管代理的详细信息

az cognitiveservices agent show

此代码的参数包括:

论点 必选 Description
--account-name -a Foundry Tools 帐户名称
--name -n Foundry Tools 托管代理名称
--project-name AI 项目名称

调用托管代理

可以在代理游乐场界面中查看和测试托管的代理。 托管代理公开了一个 OpenAI 响应兼容的 API,可以使用 OpenAI SDK 调用该 API。

#!/usr/bin/env python3
"""
Call a deployed Microsoft Foundry agent
"""

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import AgentReference

# Configuration
PROJECT_ENDPOINT = "https://your-project.services.ai.azure.com/api/projects/your-project"
AGENT_NAME = "your-agent-name"
AGENT_VERSION = "1"  # Optional: specify version, or use latest

# Initialize the client and retrieve the agent
client = AIProjectClient(endpoint=PROJECT_ENDPOINT, credential=DefaultAzureCredential())
agent = client.agents.retrieve(agent_name=AGENT_NAME)

# Get the OpenAI client and send a message
openai_client = client.get_openai_client()
response = openai_client.responses.create(
    input=[{"role": "user", "content": "Hello! What can you help me with?"}],
    extra_body={"agent": AgentReference(name=agent.name, version=AGENT_VERSION).as_dict()}
)

print(f"Agent response: {response.output_text}")

将工具与托管代理配合使用

在托管代理可以运行工具之前,需要在 Foundry 上创建与远程模型上下文协议 (MCP) 服务器的连接。

连接 RemoteMCPTool 支持以下身份验证机制:

  • 存储的凭据:使用系统中存储的预定义凭据。
  • 项目托管标识:使用 Foundry 项目的托管标识。

选择身份验证方法

  • 对于共享标识:当代理的每个用户都应使用相同的标识时,请使用基于密钥或 Foundry 项目托管标识身份验证。 单个用户标识或上下文不会使用这些方法持久保存。

  • 对于单个用户上下文:当代理的每个用户都应使用自己的帐户向 MCP 服务器进行身份验证时,请使用 OAuth 身份透传。 此方法保留个人用户上下文。

若要了解如何创建 RemoteMCPTool 连接,请参阅 “连接到模型上下文协议服务器”。

将配套包与本地代理代码配合使用,从容器中列出和调用工具:

from azure.ai.agentshosting import tool_client, from_langgraph
from langchain_openai import AzureChatOpenAI
from langgraph.prebuilt import create_react_agent

async def agent_run(self, request_body: CreateResponse, context: AgentRunContext):
    deployment_name = os.getenv("AZURE_OPENAI_CHAT_DEPLOYMENT_NAME", "gpt-4o")
    model = AzureChatOpenAI(model=deployment_name)
    
    tools_client = await tool_client(context)

    try:
        tools = await tools_client.list_tools()
        agent = create_react_agent(model, tools)
        await from_langgraph(agent).run_async()
    except OAuthRequiresConsentException as oauthException:
        return ResponseOauthConsentRequestEvent(oauthException)

您还可以使用托管代理与 Foundry 的内置工具配合使用。 支持的工具包括:

  • 代码解释器
  • 图像生成
  • Web 搜索

使用托管代理管理可观测性

托管智能体支持通过 Application Insights 或任何用户指定的 OpenTelemetry 收集器终结点,将底层框架的 OpenTelemetry 跟踪、指标和日志暴露给 Microsoft Foundry。

如果使用 azd ai agent CLI 扩展,则会自动预配 Application Insights 并将其连接到 Foundry 项目。 项目的托管标识在 Foundry 资源上被授予 Azure AI 用户角色,以便将跟踪导出到 Application Insights。

如果使用 Foundry SDK,则必须独立执行这些步骤。 在此文中了解详细信息。

宿主适配器提供:

  • 完成 OpenTelemetry 设置TracerProviderMeterProviderLoggerProvider
  • 自动检测:HTTP 请求、数据库调用、AI 模型调用。
  • Azure Monitor 集成:导出程序、格式设置、身份验证。
  • 性能优化:采样、批处理、资源检测。
  • 实时指标:Application Insights 中的实时仪表板。

本地跟踪

  1. 请按照 AI 工具包中的 Trace 指南,安装和设置用于 Visual Studio Code (VS Code) 的 AI 工具包。

  2. 设置和导出环境变量 OTEL_EXPORTER_ENDPOINT。 选择 “启动收集器 ”按钮后,可以从 AI Toolkit for VS Code 中找到终结点。

  3. 启动代理并在 AI 工具包中查找痕迹。

Foundry 门户中的跟踪

你还可以在操场的“跟踪”选项卡上查看托管智能体的跟踪。

将跟踪导出到与 OpenTelemetry 兼容的服务器

若要将跟踪发送到你自己的 OpenTelemetry 收集器或兼容的可观测性平台,请使用环境变量 OTEL_EXPORTER_ENDPOINT

使用托管代理管理对话

托管代理与 Microsoft Foundry 中的聊天管理系统无缝集成。 此集成支持有状态的多轮交互,无需手动状态管理。

对话如何与托管智能体配合使用

对话对象:Foundry 自动创建持久会话对象,这些对象具有唯一标识符,这些标识符可跨多个代理交互持久保存。 当用户启动与托管代理的对话时,平台会自动维护此聊天上下文。

状态管理:与手动传递会话历史记录的传统 API 不同,托管代理会自动接收会话上下文。 Foundry 运行时管理:

  • 以前的消息和响应。
  • 工具调用及其输出。
  • 代理说明和配置。
  • 聊天元数据和时间戳。

对话项:每个会话都包含自动维护的结构化项:

  • 消息:带有时间戳的用户输入和代理响应。
  • 工具调用:具有参数和结果的函数调用。
  • 工具输出:来自外部服务的结构化响应。
  • 系统消息:内部状态和上下文信息。

聊天持久性和重用

跨会话连续性:会话在单个请求之外仍然存在。 用户可以返回到以前的讨论,并保留完整的上下文。

对话重用:用户可以从多个通道和应用程序访问同一对话。 对话保持一致的状态和历史记录。

自动清理:Foundry 根据项目的保留策略管理对话生命周期和清理。

评估和测试托管代理

Microsoft Foundry 提供针对托管代理设计的综合性评估和测试功能。 可以使用这些功能来验证性能、比较版本并帮助确保部署前的质量。

内置评估功能

代理性能评估:Foundry 包含用于评估您托管代理有效性的内置评估指标:

  • 响应质量和相关性
  • 任务完成准确性
  • 工具使用效率
  • 会话一致性和上下文保留
  • 响应时间和效率指标

特定于代理的评估:将 Azure AI 评估 SDK 与专为代理工作流设计的内置评估程序结合使用来评估托管代理。 SDK 提供专门的计算器,用于跨关键维度(例如意向解析、任务遵循和工具使用准确性)测量代理性能。

测试托管代理的工作流

开发测试:在部署之前使用代理场和本地测试工具在开发期间在本地测试托管代理。

暂存验证:部署到过渡环境,以验证实际 Foundry 基础结构的行为,同时保持与生产隔离。

生产监视:使用自动评估运行持续监视已部署的托管代理,以检测性能下降或问题。

结构化评估方法

测试数据集创建:创建全面的测试数据集,涵盖:

  • 常见的用户交互模式。
  • 边缘用例和错误场景。
  • 多轮对话流程。
  • 工具使用方案。
  • 性能压力测试。

支持的评估指标:Azure AI 评估 SDK 为代理工作流提供以下评估程序:

  • 意向解决:衡量代理识别和理解用户请求的方式。
  • 任务符合性:评估代理的响应是否符合分配的任务和系统指令。
  • 工具调用准确性:评估代理是否为用户请求发出正确的函数工具调用。
  • 其他质量指标:允许对代理消息使用相关性、一致性和流畅性。

评估最佳做法

使用代表性数据进行测试:创建表示实际用户交互和用例的评估数据集。

监视代理性能:使用 Foundry 门户跟踪代理性能和查看会话跟踪。

使用迭代评估:在开发过程中定期评估代理版本,以提前捕获问题并衡量改进。

有关评估代理的详细信息,请参阅 本地评估 AI 代理代理评估器

将托管智能体发布到频道

发布会将托管智能体从开发资产转换为具有专用终结点、独立标识和治理功能的 Azure 托管资源。 发布托管代理后,可以跨多个通道和平台共享它。

托管代理的发布过程

发布托管代理时,Microsoft Foundry 自动:

  1. 使用专用调用 URL 创建代理应用程序资源。
  2. 提供与项目共享标识分离的独立智能体标识。
  3. 在 Microsoft Entra 代理注册表中注册代理,以便进行发现和治理。
  4. 支持稳定的终结点访问,且在部署新智能体版本时保持一致。

与可在门户中编辑的基于提示的代理不同,托管代理在获得相同的发布和共享功能的同时维护其基于代码的实现。

可用的发布频道

Web 应用程序预览:获取一个即时可共享的 Web 界面,以便向利益相关者演示和测试您的托管代理。

Microsoft 365 Copilot 和 Teams:通过简化的无代码发布流将托管代理直接集成到 Microsoft 365 Copilot 和 Microsoft Teams。 你的智能体将出现在智能体商店中,用于组织级或共享范围分发。

稳定 API 端点:通过一个在更新代理版本时保持不变的一致 REST API,以编程方式访问你的托管代理。

自定义应用程序:使用稳定的终结点和 SDK 集成将托管代理嵌入现有应用程序中。

托管代理的发布注意事项

标识管理:已发布的托管代理接收其自己的代理标识,这要求重新配置代理访问的任何 Azure 资源的权限。 共享开发标识的权限不会自动转移。

版本控制:发布会创建引用当前智能体版本的部署。 可以通过部署新版本来更新已发布的代理,而无需更改公共终结点。

身份验证:默认情况下,已发布的代理支持基于 RBAC 的身份验证。 此身份验证包括向 Microsoft 365 渠道发布时 Azure 机器人服务集成的自动权限处理。

有关详细的发布说明,请参阅 发布和共享代理

排查托管代理终结点问题

如果代理部署失败,请选择“ 查看部署日志”来查看错误日志。 如果收到 4xx 错误,请使用下表确定后续步骤。 如果代理终结点返回 5xx 状态代码,请联系Microsoft支持人员。

错误分类 HTTP 状态代码 解决方案
SubscriptionIsNotRegistered 400 注册功能或订阅提供程序。
InvalidAcrPullCredentialsAcrPullWithMSIFailed 401 修复托管标识或注册表 RBAC。
UnauthorizedAcrPullAcrPullUnauthorized 403 提供正确的凭据或标识。
AcrImageNotFound 404 更正映像名称/标记或发布映像。
RegistryNotFound 400/404 修复注册表 DNS/服务器拼写或网络可访问性。
ValidationError 400 更正无效的请求字段。
UserError (泛型) 400 检查消息并修复配置。

了解预览详细信息

预览期间的限制

尺寸 限度
每个 Azure 订阅每个区域的 Microsoft Foundry 资源 100
每个 Foundry 资源的最大代理数 200
智能体部署的最大 (min_replica) 数量 2
智能体部署的最大 (max_replica) 数量 5

托管定价

在预览版期间,托管主机运行时的计费将不会早于 2026 年 2 月 1 日启用。 有关定价的更新,请查看 Foundry 定价页

区域可用性

目前,仅美国中北部区域支持托管智能体。