通过 Azure API Management 暴露 Microsoft Foundry A2A 智能体完整指南

直接向网络客户端开放企业级 AI 智能体（Agent）会导致不可控的 API 调用、Token 消耗扩散以及安全审计缺失。Microsoft AI Foundry 提供了强大的智能体构建能力，但若绕过 API 网关直接暴露终点，将给企业基础设施带来严重的安全与性能隐患。

通过在 Microsoft AI Foundry 的 Agent2Agent (A2A) 协议终点前部署 Azure API Management (APIM)，企业能够统一实施订阅密钥验证、单客户限流配额、内容安全策略以及 OpenTelemetry / Application Insights 全链路追踪。对于需要在多个模型供应商之间进行调度的大模型架构，开发者还可以结合 n1n.ai 等聚合 API 服务，将内部智能体与第三方高性能 LLM 节点进行无缝整合。

本教程将手把手带你通过 APIM 与系统分配托管身份（System-Assigned Managed Identity），安全地对外暴露 Microsoft AI Foundry A2A 智能体。

架构设计与调用流程

客户端请求首先到达 APIM 网关，APIM 验证订阅密钥后，通过自身托管身份向 Microsoft Entra ID 申请 Bearer Token，随后将 JSON-RPC 2.0 请求代理转发至 AI Foundry 智能体终点。

Postman / 业务系统 / 调用方智能体
        │
        │  POST https://api.yourcompany.com/agents/helper-agent
        │  Header: Ocp-Apim-Subscription-Key: <key>
        ▼
Azure API Management (APIM)
   ├── 1. 验证订阅密钥与配额速率限制
   ├── 2. 获取 Entra ID 令牌 (Scope: https://ai.azure.com)
   └── 3. 强制注入 Header A2A-Version: 1.0
        │
        ▼  POST https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/a2a
        │  Header: Authorization: Bearer <Entra_Token>
        ▼
Microsoft AI Foundry Agent 终点 (helper-agent)

企业级优势

1. 统一治理与审计：在不修改底层模型配置的前提下，提供基于 API 产品的统一鉴权、访问速率限制与日志采集。
2. 统一前端入口：为托管在 AI Foundry 的原生智能体与托管在 Azure Container Apps 或其他云端的智能体提供一致的 URL 访问路径 (/agents/*)。
3. 零信任身份转换：通过 APIM 的系统托管身份自动完成 OAuth2 Token 申请与刷新，避免在客户端硬编码敏感凭据。

前置条件与环境变量准备

在开始配置前，请确保具备以下资源与权限：

环境变量占位符说明

在接下来的步骤中，请将以下占位符替换为实际资源名称：

• Foundry 账号名称：contoso-agents-poc
• Foundry 项目名称：contoso-agents-poc
• 智能体名称：helper-agent
• APIM 实例名称：contoso-apim
• 网关对外域名：https://api.yourcompany.com（或 https://contoso-apim.azure-api.net）

目标 A2A 协议 URL 结构

每个 AI Foundry 智能体均拥有固定的 A2A 终点路径：

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

替换参数后的完整后端 URL 为： https://contoso-agents-poc.services.ai.azure.com/api/projects/contoso-agents-poc/agents/helper-agent/endpoint/protocols/a2a

第一步：配置 Microsoft AI Foundry 智能体与 Agent Card

1. 登录 Microsoft AI Foundry 门户 (ai.azure.com)，确保右上角 New Foundry experience 切换开关处于开启状态。
2. 进入项目 (contoso-agents-poc)，点击左侧 Build → Agents，点击 + Create agent。
3. 命名智能体为 helper-agent，选择已部署的聊天模型（如 gpt-4o-mini）。
4. 在 Instructions 中填入明确系统提示词：

   "你负责解答公司假期与休假政策的相关问题。回答需简明扼要。若接收到无关问题，请明确回复超出服务范围。"

5. 点击右上角 Save。智能体终点即刻生效。

创建 Agent Card（智能体名片）

Agent Card 是供机器识别和智能体间协同（Inter-Agent Collaboration）的标准化 JSON 声明。

1. 点击 helper-agent 进入 Details 标签页。
2. 找到 A2A / Agent card 区域，点击 Create an agent card。
3. 填写机器可读的名片元数据：
   • Name: helper-agent
   • Description: 解答公司休假与假期政策咨询，不处理薪酬及 IT 问题。
   • Topics: holiday, leave, policy, hr
   • Capabilities: 根据休假提问，返回符合公司 HR 规范的政策指引。
   • Sample Prompt: 每年有多少天带薪年假？
4. 点击 Save 保存。

第二步：在 Azure API Management 中导入 A2A API

1. 打开 Azure Portal，进入 APIM 实例 (contoso-apim)。
2. 在左侧菜单选择 APIs → + Add API。
3. 选择 A2A Agent 卡片。

版本说明：A2A API 导入卡片已在 APIM v2 层级及 2026 年 6 月更新后的 Classic 层级全面上线（GA）。若无该卡片，可通过手动创建 HTTP API 并配置相同 Policy 方式替代。

4. 在 URL 字段中填入 Agent Card 终点 URL： https://contoso-agents-poc.services.ai.azure.com/api/projects/contoso-agents-poc/agents/helper-agent/endpoint/protocols/a2a/agentCard/v1.0
5. 点击 Next。

忽略导入错误警告

界面将弹出红框警告："We couldn't retrieve the agent card, possibly due to a wrong url or your network configuration."

原因分析：这是预期行为。APIM 向 Foundry 发送了匿名 GET 请求获取名片，而 Foundry 强制要求 Entra ID Bearer 身份认证。URL 本身没有任何错误。忽略警告并手动填写参数：

• Protocol: JSON-RPC（灰显不可更改）
• Runtime URL (JSON-RPC): https://contoso-agents-poc.services.ai.azure.com/api/projects/contoso-agents-poc/agents/helper-agent/endpoint/protocols/a2a
• Agent ID: helper-agent
• Display name: Helper Agent
• Name: helper-agent
• Base path: agents/helper-agent

点击 Create 完成创建。

第三步：配置 Entra ID RBAC 托管身份授权

APIM 必须代表自身向 Foundry 申请访问令牌，需按以下两步完成授权：

开启 APIM 系统托管身份

1. 进入 APIM 实例主页 → 左侧菜单 Security → Managed identities。
2. 在 System assigned 标签页中，将 Status 切换为 On 并点击 Save。记录生成的 Object (principal) ID。

在 Foundry 项目中分配 RBAC 角色

1. 打开 Azure Portal，找到你的 Foundry Project 资源（注意：需选择 Project 资源而非 Parent Account）。
2. 左侧菜单进入 Access control (IAM) → + Add → Add role assignment。
3. 在角色列表搜索并选择 Foundry User 角色（如需精细化最小权限，可通过 CLI 分配 ID 为 eed3b665-ab3a-47b6-8f48-c9382fb1dad6 的 Foundry Agent Consumer 角色）。
4. 在 Members 选项卡中选择 Managed identity → 点击 + Select members。
5. 选择你的 APIM 实例 contoso-apim，点击 Select 并确认分配。

重要提示：Azure RBAC 角色分配存在 3 到 5 分钟的异步同步延迟。若立即进行测试将触发 401 Unauthorized 错误。

第四步：配置 APIM 入站策略 (Inbound Policy)

此步骤将指示 APIM 自动获取令牌、注入终点以及强制指定 A2A 协议版本。

进入 APIM → APIs → helper-agent → Policies 代码编辑窗口，将默认 XML 替换为以下配置：

<policies>
    <inbound>
        <base />
        <authentication-managed-identity resource="https://ai.azure.com" />
        <set-backend-service base-url="https://contoso-agents-poc.services.ai.azure.com/api/projects/contoso-agents-poc/agents/helper-agent/endpoint/protocols/a2a" />
        <set-header name="A2A-Version" exists-action="override">
            <value>1.0</value>
        </set-header>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

策略逻辑解析

• authentication-managed-identity: 指示 APIM 使用自身托管身份向资源 https://ai.azure.com 请求 OAuth2 Token，并自动注入到请求头的 Authorization: Bearer <token> 中。
• set-backend-service: 将客户端请求动态重定向至目标 AI Foundry 智能体的实际 A2A 终点。
• set-header (A2A-Version): 显式指定请求 A2A 1.0 协议版本。若缺失此 Header，Foundry 将默认回退至 0.3 旧版协议格式。

第五步：使用 Postman 进行端到端测试

在 APIM 菜单的 Subscriptions 中获取订阅密钥（如 Built-in all-access subscription 密钥）。

Postman 请求设置

• HTTP Method: POST（切勿使用 GET）
• URL: https://api.yourcompany.com/agents/helper-agent
• Headers:
  • Ocp-Apim-Subscription-Key: <你的_APIM_订阅密钥>
  • Content-Type: application/json

请求 Body 载荷 (A2A v1.0 JSON-RPC 2.0 规范)

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "msg-001",
      "role": "ROLE_USER",
      "parts": [
        { "text": "请问公司的带薪年假标准是多少天？" }
      ]
    }
  }
}

预期响应体 (HTTP Status 200 OK)

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "result": {
    "task": {
      "id": "resp_task_99823",
      "contextId": "ctxt_session_4412",
      "status": {
        "state": "TASK_STATE_COMPLETED",
        "timestamp": "2026-09-06T04:18:09+00:00"
      },
      "artifacts": [
        {
          "artifactId": "msg_art_1102",
          "parts": [
            {
              "text": "根据公司政策，员工每年享受 25 天带薪年假。请通过 HR 系统提交休假申请。"
            }
          ]
        }
      ]
    }
  }
}

智能体返回文本位于 result.task.artifacts[0].parts[0].text。在多轮对话场景中，客户端需在后续请求中携带 contextId 以维持上下文连贯性。

常见错误与排查矩阵

企业级扩展与多模型网关治理

将 Microsoft AI Foundry 智能体接入 APIM 解决了内网智能体的安全治理问题。然而，在复杂的大模型系统架构中，企业往往还需要调用其他模型供应商（如 Anthropic Claude 3.5 Sonnet、DeepSeek-V3 或 OpenAI o3）。如果针对每个供应商都建立独立的治理架构，会导致维护成本急剧上升。

在这种环境下，开发者可结合使用 n1n.ai 等大模型 API 聚合基础设施，在统一接口下实现多模型的高可用路由与低延迟调度。同时，APIM 网关层依然负责托管企业内部的自定义 A2A 智能体，实现内外架构的无缝解耦。

进阶场景：将 A2A 智能体转换为 MCP 工具

若需将已暴露的 A2A 智能体转化为 Model Context Protocol (MCP) Server 供外部工具调用：

1. 在 APIM 中新建指向智能体 Responses 终点（.../endpoint/protocols/openai/responses）的 HTTP API。
2. 启用 APIM 原生的 Expose as MCP server 功能，系统将自动把 HTTP 接口转换为标准 MCP 工具 Schema。

借助结构化的网关设计以及 n1n.ai 提供的稳定大模型 API 支持，企业能够快速构建出具备弹性、安全且可扩展的生产级 Agentic AI 体系。

Get a free API key at n1n.ai