深入解析 Microsoft Foundry Agent 端点：版本控制、金丝雀发布与 Teams 及 Copilot 集成

在开发测试环境（Playground）中构建 Prompt Agent 并不复杂。你编写系统指令、挂载向量数据库以实现 RAG、测试多轮对话边界条件，并确认输出符合 JSON Schema 规范。然而，当试图将原型推进至企业级生产环境时，一系列核心运维问题随之浮现：

如何在发布 Agent 的 v2 版本时，确保不破坏现有客户端应用或中断正在进行的对话？
如何安全地将 5% 的生产流量引流至候选 Prompt 或模型更新上，同时保持秒级回滚的能力？
如何在不重复维护多套业务逻辑的前提下，将同一个 Agent 暴露给 REST API、Microsoft Teams 频道、Microsoft 365 Copilot 插件以及 Agent-to-Agent（A2A）网络？

Microsoft Foundry Agent Service 通过解耦的架构模型解决了这些生产瓶颈。Foundry 没有将运行时行为直接绑定到静态 Prompt 字符串或简单部署脚本上，而是彻底拆分了 身份（Identity）、状态与逻辑（State & Logic）、路由（Routing）、传输（Transport） 以及 治理（Governance）。

在构建复杂的多 Agent 架构时，企业团队通常会将 Agent 治理平台与灵活的 API 聚合基础设施相结合。诸如 n1n.ai 这样的平台提供了对 OpenAI o3、Claude 3.5 Sonnet 和 DeepSeek-V3 等主流底层大模型的统一接入，为 Agent 编排层保障了高可用性、成本控制与低延迟响应。

本文将深入剖析 Microsoft Foundry Agent 端点的底层架构，演示金丝雀流量切分的具体代码实现，并详细讲解面向 Microsoft Teams 和 Copilot 的企业发布流水线。

1. 核心层级架构：四大嵌套实体

要在生产环境中稳定运行 Microsoft Foundry Agent，必须理解构建运行时执行逻辑的四个核心实体层级：

+-----------------------------------------------------------------------+
|                           Foundry Project                             |
|  (逻辑 RBAC 容器、资源分组、计费归属作用域)                              |
|                                                                       |
|   +---------------------------------------------------------------+   |
|   |                         Agent                                 |   |
|   |  (稳定身份、名称、永久不变的 URL 标识符)                             |   |
|   |                                                               |   |
|   |   +-------------------------------------------------------+   |   |
|   |   |                   Agent Version                       |   |   |
|   |   |  (不可变快照：系统指令、模型绑定、工具配置)                 |   |   |
|   |   +-------------------------------------------------------+   |   |
|   |                                                               |   |
|   |   +-------------------------------------------------------+   |   |
|   |   |                   Agent Endpoint                      |   |   |
|   |   |  (版本选择器、多协议适配器、身份验证方案)                    |   |   |
|   |   +-------------------------------------------------------+   |   |
|   +---------------------------------------------------------------+   |
+-----------------------------------------------------------------------+

Foundry Project（项目）：顶级逻辑容器，用于定义 RBAC 权限、访问策略、遥测跟踪与资源计费归属。
Agent（代理身份）：面向调用方的持久化身份。它拥有固定的名称、图标、描述以及唯一 URL。外部系统直接绑定至 Agent 身份，而非具体的代码版本。
Agent Version（代理版本）：不可变的配置快照。每当修改系统 Prompt、切换底层大模型（如通过 n1n.ai 升级至更高性能的模型）或添加自定义函数工具时，系统都会自动生成一个新的递增版本号（如 v1、v2、v3）。历史版本将被永久冻结。
Agent Endpoint（代理端点）：实际接收与处理网络请求的监听器。它位于稳定的 URI 上，通过配置动态路由规则决定将请求分发给哪一个具体的 Agent Version。

标准端点 URL 格式如下：

https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/{protocol}

2. 请求处理生命周期：四大执行关卡

当请求到达 Agent Endpoint 时，Foundry 运行时会在执行任何大模型推理或工具代码之前，按顺序依次执行四个校验关卡：

入站请求 Payload
      │
      ▼
┌───────────────────────────┐
│ 1. 协议协商               │ ──► 解析请求路径中的协议适配器 (Responses, Activity, A2A, MCP)
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│ 2. 身份验证检查           │ ──► 验证 Entra ID、BotServiceRbac 或 BotServiceTenant 凭据
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│ 3. 版本路由解析           │ ──► 根据 version_selector 规则决定目标版本 (Latest, Pinned, Canary)
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│ 4. 会话与隔离密钥解析     │ ──► 依据 user_isolation_key / chat_isolation_key 绑定上下文状态
└─────────────┬─────────────┘
              │
              ▼
   大模型推理与工具调用循环

协议协商（Protocol Negotiation）：根据请求 URI 路径匹配对应的协议处理器（例如 /protocols/responses 或 /protocols/activityprotocol）。
身份验证检查（Authorization Check）：校验请求方携带的 Token 或通道级别的信任凭据。
版本路由解析（Version Resolution）：求值 version_selector 中的规则，确定由哪个不可变版本的 Prompt 和工具集承接本次交互。
会话隔离解析（Session Isolation Resolution）：根据身份凭据或自定义隔离请求头加载对应的对话状态分区。

3. 多协议表面阵列（Protocol Surfaces）

Foundry 端点支持同时启用多种网络协议。这使得开发者可以使用单一的 Agent 定义，无缝对接多样化的应用场景：

协议类型	格式与规范	典型应用场景	主要调用客户端
Responses	OpenAI Responses API 兼容格式	Web 应用、后端微服务、自定义 SDK	Python/TS 应用程序、API 网关
Activity Protocol	Bot Framework Activity 规范	企业级即时通讯与协作频道	Microsoft Teams、M365 Copilot
Invocations	轻量级 REST 调用	无服务器函数、事件驱动 Webhook	Azure Functions、Event Grid
A2A (预览/GA)	Agent-to-Agent 对等协议	多 Agent 协同编排框架	外部对等 Agent、AutoGen、CrewAI
MCP (预览)	Model Context Protocol	将 Agent 能力作为工具暴露	支持 MCP 规范的宿主系统

通过使用 n1n.ai 等大模型 API 聚合服务，开发者可以在后端实现模型故障转移与备用路由，同时在前端通过 Activity Protocol 为 Teams 用户提供稳定的 Agent 交互体验。

4. 实战指南：配置金丝雀发布与多协议端点

在生产环境中，应避免使用全量覆盖（Blue-Green）的发布方式。通过配置 version_selector 中的 FixedRatio 规则，可以轻松实现基于权重的流量切分。

以下 Python SDK 示例演示了如何配置端点：将 90% 的生产流量保留在稳定版 v4，将 10% 的流量引流至候选版 v5 进行金丝雀观测，同时开启 Responses、Activity 和 A2A 协议：

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.projects.models import (
    AgentEndpointConfig,
    FixedRatioVersionSelectionRule,
    VersionSelector,
    ProtocolConfiguration,
    ResponsesProtocolConfiguration,
    ActivityProtocolConfiguration,
    A2AProtocolConfiguration,
    EntraAuthorizationScheme,
    BotServiceRbacAuthorizationScheme,
)

# 使用 Entra ID 凭据初始化项目客户端
PROJECT_ENDPOINT = os.environ.get("AZURE_FOUNDRY_PROJECT_ENDPOINT")
AGENT_NAME = "compliance-triage-agent"

project_client = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

with project_client:
    # 1. 定义版本选择器：90% 流量至 v4，10% 流量至 v5 (金丝雀切分)
    version_selector = VersionSelector(
        version_selection_rules=[
            FixedRatioVersionSelectionRule(agent_version="4

参考来源：https://dev.to/monuminu/inside-the-microsoft-foundry-agent-endpoint-versions-canary-rollouts-and-publishing-to-teams--2jc4