随着智能体工作流从简单的文本交互演进为丰富的用户界面，开发者始终面临深度定制与无缝集成之间的权衡。

迄今为止，开发者通常不得不在两条截然不同的路径之间做出选择：

• 模型上下文协议（MCP）应用允许在 iframe 内使用标准 Web 技术实现创意自由。然而，这类应用对 iframe 的依赖可能导致碎片化的用户体验，表现为设计系统冲突或冗余滚动条等视觉不一致问题，同时在计算性能和安全性封装方面也带来显著挑战。
• 智能体到用户界面（A2UI）采用声明式框架。A2UI 不发送原始 HTML、CSS 和 JavaScript，而是使用 JSON 载荷定义渲染内容，让宿主应用通过其原生组件处理呈现。宿主应用随后安全地将这些数据转换为其自身的原生 UI 元素。虽然这能确保设计一致性和更高的安全性，但开发者被限制在特定的组件库中。这种方法提供了高性能、安全且集成的体验，尤其适用于图表和表单等结构化数据，但在处理复杂的客户端逻辑时存在局限。

为应对这些权衡，我们分享了三种架构模式，并附有实现指南和示例代码，以展示 A2UI 与 MCP 应用的无缝集成。我们正在考虑开发一个 MCP 扩展来支持 A2UI，使这些模式更易于采用。如果您感兴趣，请告知我们。

集成这两种方法，使开发者能够为标准 UI 元素利用原生组件渲染，同时为高度定制化的复杂体验保留自定义 iframe 嵌入。

模式 1：在 MCP 服务器上使用 A2UI

在 MCP 服务器上提供 A2UI，使开发者能够为其工具添加丰富的原生渲染 UI，作为 MCP 应用的替代方案。它将广泛采用的 MCP 工具连接的简洁性与原生 A2UI 渲染相结合。

这种方法降低了开发者采用生成式 UI 的门槛。它提供了动态 UI 的优势，而无需构建完整的智能体间（A2A）架构或处理复杂的发现机制。

架构优势

• 绕过 iframe 限制：在 MCP 服务器中使用 MCP Apps 实现 UI 会导致视觉脱节和延迟。A2UI-over-MCP 绕过了 iframe，允许宿主应用使用自己的设计系统原生渲染智能体的意图。
• 关注点分离：MCP 处理后端工具和数据访问，而 A2UI 处理前端组件渲染。这使得智能体逻辑保持清晰，专注于推理而非 UI 实现细节。
• 增强的环境可移植性：MCP 服务器可以将数据提供给在 React、Flutter 或 Angular 上渲染的 A2UI 客户端，无需自定义连接。它提供了“一次编写，随处原生渲染”的能力，解决了服务器必须为每个不同界面准备独特响应的问题。
• 简化的安全性：来自 MCP 工具的数据与 A2UI 默认安全的 JSON 架构集成。与传递原始 HTML 的传统方法不同，A2UI 使用基于能力的安全模型，客户端仅从预定义目录中渲染受信任的组件。
• 加速开发周期：现在，编写 MCP 工具或定义资源的专业知识可以直接转化为生成复杂用户界面的能力。通过使用 A2UI Agent SDK，工程团队可以绕过手动编写 JSON 的复杂性，因为该库原生处理模式强制和验证。

实际演示

以下是一个由 A2UI-over-MCP 架构驱动的演示应用。该应用由两个面板组成。左侧面板包含一个简单的表单，允许用户选择烹饪风格和蛋白质类型，右侧面板显示一个食谱卡片。用户在左侧面板中选择烹饪风格和蛋白质类型，然后点击“获取食谱”按钮，即可获取新的食谱卡片并显示在右侧面板上。

此应用中的两个面板均由 A2UI 生成，并且都利用了基于 MCP 的 A2UI 架构，即 A2UI 负载直接从 MCP 服务器获取，并由 A2UI 框架直接渲染。通过利用 A2UI 框架进行 UI 渲染，宿主应用无需维护任何 UI 组件逻辑，同时只需将自身的主题应用于 A2UI 组件，即可保持设计一致性。

基于 MCP 的 A2UI 配方工作室（A2UI-over-MCP Recipe Studio）实际运行效果

底层原理：它是如何工作的

MCP 服务器不再返回标准文本响应或打包的 HTML/JS 网页应用，而是返回结构化的 JSON 负载，其特定 MIME 类型为：application/a2ui+json。

{
  "content": [
    {
      "type": "resource",
      "resource": {
        "uri": "a2ui://dynamic-ui/recipe-card",
        "mimeType": "application/a2ui+json",
        "text": "[
          { "version": "v0.9",
            "createSurface": { ... }
          }
        ]"
      }
    }
  ]
}

JSON

示例：通过 MCP 工具调用以嵌入式资源形式交付的 A2UI 负载 —— 查看 GitHub 上的完整示例代码

开发者可以利用两种不同的交付机制来传输此负载：通过 MCP 资源（resources/read）或通过 MCP 工具调用（tools/call）。无论采用哪种方法，端点都使用 a2ui:// URI 方案。接收到负载后，支持 A2UI 的宿主环境会自动将 JSON 结构导向其原生渲染引擎进行执行。

实现策略：静态交付与动态交付

1. 通过 MCP 资源进行静态交付（resources/read）

对于需要预设界面且该界面不随对话上下文变化的工作流程，开发者可以将 A2UI 负载作为标准 MCP 资源提供。宿主应用只需获取一个专用 URI（例如 a2ui://config-panel），服务器便会直接交付不可变的 JSON 结构。

• 理想用例：基础组件，如隐私声明、标准化配置表单或持久性偏好设置。
• 主要优势：此方法确保了高度的可预测性和高效的缓存，且计算开销为零，因为它无需大语言模型进行实时 UI 合成。

2. 通过 MCP 工具调用进行动态交付（tools/call）

为了解锁真正的生成式用户界面和实时数据注入，客户端可以调用一个 MCP 工具。后端执行逻辑以获取实时上下文，从而允许智能体动态组装 A2UI 布局。然后，这个定制化的负载会作为 CallToolResult 中的嵌入式资源返回。

• 理想用例：响应式数据可视化、上下文感知的天气模块，或根据特定用户需求定制的个性化内容卡片。
• 主要优势：提供架构上的灵活性，使智能体能够构建复杂、具有原生体验感且能响应用户目标的交互体验。

架构图：智能体使用 MCP 检索本地数据集上下文，并使用 A2UI 将动态数据可视化组件直接流式传输到客户端。

探索代码

要查看此架构的实际运行效果，请查阅 A2UI-over-MCP 快速入门指南，运行上方演示中所示的 A2UIxMCP Recipe Studio Web 应用。这个交互式演示同时运行了从 MCP 资源（一个食谱选择表单）加载的静态 A2UI 界面，以及从 MCP 工具（一张自定义生成的食谱卡片）提供的动态 A2UI 界面。

理解差异：基于 MCP 的 A2UI 与基于 A2A 的 A2UI

工程团队中一个常见的疑问是，除了传输协议之外，基于 MCP 的 A2UI 实现与原生智能体间（A2A）架构有何不同。其区别在于动态性和编排复杂度的层级：

• 基于 MCP（资源）的 A2UI：静态且规定性的 UI。这是固定结构需求（如固定数据输入表单）的最佳选择。
• 基于 MCP（工具）的 A2UI：基于工具参数的模板化动态 UI。它也可以提供静态且规定性的 UI。动态控件仅限于工具的输入参数。
• 基于 A2A 的 A2UI：在支持目录中的组件范围内，是完全生成式和开放式的。智能体拥有完整的对话上下文，并实时驱动 UI 构建。如果需要，这种方法也可以提供模板化 UI 和静态 UI。

虽然工程师通常利用 MCP 工具来获得确定性结果，但这些端点本身并不局限于静态逻辑。尽管在标准的 MCP 工具配置中使用后端大语言模型并不常见，但如果开发者选择这样做，他们可以在工具调用背后编排一个智能体层，通过 A2UI-over-MCP 架构提供更具生成性的 UI 体验。然而，驱动 UI 生成的上下文仍将局限于工具参数和为后端智能体预设的提示词。

模式二：在 A2UI 组件中运行 MCP 应用

虽然基于 MCP 的 A2UI 非常适合原生集成，但有时你需要 MCP 应用那种隔离且高度自定义的环境。你可以通过将 MCP 应用封装在 A2UI 组件内部来实现这一点，同时不破坏宿主原生的设计系统或安全边界。通过将 MCP 应用封装在 A2UI 组件中，工程师可以将复杂、状态密集的模块委托给安全的 iframe，以获得高度定制化的体验。

这种混合方法赋予了工程师针对复杂、状态密集型模块的创造性灵活性，同时确保主要界面与宿主的原生设计保持一致，并维持稳健的状态同步协议。

架构优势

• 品牌一致性与可控委托：宿主在 MCP 应用 iframe 之外保持对用户体验的设计控制，同时将 MCP 应用内部的用户体验审慎地委托给外部工具开发者。
• 专业化能力：复杂、状态密集的模块——例如具有实时状态转换的交互式游戏，或像演唱会座位选择这样带有定制验证逻辑的复杂工作流——通常难以用纯声明式组件构建。嵌入 MCP 应用解决了这一问题，让开发者在最需要的地方获得创作自由。
• 安全状态对齐：宿主应用通过一个受管控的、基于事件的循环与 MCP 应用的内部状态保持同步。通过利用 A2UI 渲染引擎作为中介，这种架构在确保状态一致性的同时，将主环境的上下文与第三方代码隔离开来。

实际演示

以下是一个演示应用，展示了将 MCP 应用作为 A2UI 组件使用的效果。服务端智能体返回一个 A2UI 数据包，其中包含一个 MCP 应用组件，该组件的输入参数包含了一款基于网页的乒乓球游戏的完整代码。该 A2UI 数据包还包含两个记分卡，它们不属于 MCP 应用。

当用户开始与电脑对战乒乓球游戏时，球拍控制和球的位置状态由嵌入的 MCP 应用内的代码管理。然而，每当有得分时，该事件会被转发给智能体，原生 A2UI 组件会使用更新后的分数进行重新渲染，从而实现 A2UI 界面中所有组件（原生 A2UI 和 MCP 应用）之间的状态同步。

示例：A2UI 乒乓球游戏运行效果

底层原理：它是如何工作的

为了实现这种混合方法，开发者需要定义一个自定义的 A2UI 组件，该组件充当安全的 iframe 包装器（称为 MCP 应用组件）。这个通用包装器可以容纳任何标准的 MCP 应用，并提供一个桥接通道，供应用与外部世界通信。

每当智能体请求时，MCP 服务器会将应用的 HTML 和 JavaScript 资源传输给智能体。然后，智能体将应用代码嵌入到结构化的 A2UI JSON 中，并将其与指定的组件参数集成。整合后的 JSON 被发送到宿主，MCP 应用在上述 iframe 包装器内与其他 A2UI 原生组件一起渲染。

A2UI 渲染引擎通过一个安全的、事件驱动的循环来维护原生组件和嵌入的 MCP 应用之间的状态，我们称之为状态同步。同步不依赖于实时的 DOM 抓取或状态轮询，而是遵循一个显式的拦截循环：

1. 拦截与转换：当 MCP 应用内部发生关键状态转换时（例如，乒乓球游戏中得分），应用会触发一个标准的 MCP 工具调用。包装层的 A2UI 组件会在本地拦截此请求，将 JSON 参数映射为结构化的 A2UI 动作上下文，并立即返回确认信息，以便应用的本地 UI 循环不被阻塞。
2. 请求路由：宿主应用将转换后的上下文打包为 A2UI Action，并将其路由至后端 AI 智能体。该智能体作为全局协调器，仅追踪宏观“关键状态”（如游戏得分或预约确认），而不记录微观状态（如球拍/球坐标或临时表单输入）。
3. 水合：智能体评估整体界面状态后，返回一个格式化的 DataModel Update JSON。A2UI 引擎直接更新原生组件（如记分牌），并通过 App Bridge 推送此更新后的资源，以重新水合内部 MCP 应用的内部状态。

探索代码

要查看这一架构的实际运行效果，请查阅我们的《MCP Apps in A2UI 快速入门指南》，运行一个实时客户端。该交互式演示集成了一个 AI 智能体，该智能体与一个 MCP 服务器相连，该服务器可提供计算器应用和乒乓球游戏，这些应用可在通用 MCP 应用包装器组件的 Angular 实现中运行。

模式 3：在 MCP 应用内运行 A2UI

该模式作为一种强大的现代化桥梁，允许开发者将动态的、由智能体驱动的 UI 注入到遗留应用或非 A2UI 环境中，而无需进行复杂的架构改造。

在此模式中，MCP 应用包包含其自身的 A2UI 渲染器。为了获取动态的 A2UI 界面，MCP 应用通过桥接一个工具调用到服务器来检索 A2UI 负载，利用了之前讨论的基于 MCP 的 A2UI 机制。一旦接收到 A2UI JSON 负载，MCP 应用便在其自身的 iframe 边界内完全解析并渲染它们。通过将生成式 UI 的复杂性吸收到一个自包含的渲染器中，该模式允许开发者以最小甚至无需架构改造的方式，将动态的 AI 驱动交互引入现有系统。

架构优势

• 为非 A2UI 宿主提供生成式 UI：这使得 MCP 应用能够提供由智能体驱动的 A2UI 能力，即使宿主环境本身并不原生支持 A2UI。
• 遗留系统升级：遗留应用只需支持一个基本的 MCP App iframe 容器。MCP App 承担了所有生成式 UI 的复杂性，以极少的工程投入为老旧系统解锁动态 AI 交互能力。
• 自包含交互循环：由于 A2UI 渲染器完全驻留在 iframe 化的 MCP App 边界内，本地状态转换（例如，接受/拒绝文档修订）可以在应用内部安全且直接地处理。只有受管理的、预定义的上下文会通过 App Bridge 回传给宿主。

实际演示

下方是一个演示应用，展示了 A2UI 嵌入式 MCP App。宿主应用加载了一个 MCP App，该 App 从 MCP 服务器获取了一个在线文本编辑器。这个 MCP App 与 A2UI 库打包在一起，后者提供了将 A2UI JSON 负载渲染为 UI 的能力。通过结合模式 1 中讨论的基于 MCP 的 A2UI 技术，该 MCP App 能够有效地与 MCP 服务器通信，从而通过 A2UI 协议支持生成式 UI 功能。

在此演示中，用户通过高亮选中部分文本来启动其 AI 辅助文本编辑。当用户高亮文本时，后端服务器将该文本作为参数，设计出与上下文相关的编辑参数。这些控件通过 A2UI 提供，MCP App 在接收到该负载后将其渲染出来。随后，用户可以调整这些参数，指导 AI 按照自己的意图编辑相应部分。当用户点击"生成修订"时，AI 智能体将考虑这些参数，并向用户提供编辑建议。

示例：生成式文档编辑器

底层原理：工作原理

与其他模式相比，这种架构模式消除了宿主环境原生支持 A2UI 的需求。通过将 A2UI 渲染引擎直接打包到 MCP App 包中，开发者可以将复杂性转移给嵌入式应用本身。

通过利用 App Bridge，嵌入式 MCP 应用使用模式 1 中的 A2UI-over-MCP 机制与后端 AI 智能体进行通信。它从 MCP 服务器收到的任何包含 MIME 类型 `application/a2ui+json` 的响应，都会被视作 A2UI 负载，并交由 A2UI 库进行渲染。

为了实现具有生成式特性的功能，此演示应用在 MCP 服务器后端部署了一个 AI 智能体。这使得 MCP 工具调用能够利用大语言模型，根据提供的参数生成与上下文相关的控制参数和文本修订内容。

以下交互生命周期支配着这个自包含循环：

1. 上下文触发：用户与主界面进行交互，例如在文档编辑器中高亮选中特定段落。
2. 事件转发：App Bridge 通过 `postMessage` 将此事件传输给宿主，宿主随后将上下文路由至后端 AI 智能体。
3. 生成式负载返回：智能体评估需求，并通过 MCP 服务器返回一个定制的 A2UI JSON 负载，其中可能包含动态滑块或专门的编辑控件。
4. 内部渲染：在识别出 `application/a2ui+json` MIME 类型后，应用的内部渲染器会在指定面板中动态挂载该界面。
5. 受控通信：高级用户操作通过桥接器转发至后端进行处理，而本地状态转换——例如接受或拒绝修订——则直接在应用沙箱内管理，以维持安全隔离。

<html>
<body>

  <div>
    <h3>MCP App (Editor Panel)</h3>
    <p>This text is native to the sandboxed third-party app.</p>
    
    <!-- A2UI Surface custom element provided by the A2UI SDK -->
    <a2ui-surface surfaceId="recipe-card"></a2ui-surface>
  </div>

  <script>
    // Note: The pseudocode below assumes AppBridge from @modelcontextprotocol/ext-apps
    // and a2uiProcessor from the A2UI SDK are preloaded or inlined.
    const bridge = new AppBridge({ name: 'editor-panel', version: '1.0.0' });

    // Helper to extract and process dynamic A2UI responses from tool results
    function processA2UIResponse(result) {
      const a2uiResource = result?.content?.find(
        c => c.type === 'resource' && c.resource?.mimeType === 'application/a2ui+json'
      );
      if (a2uiResource?.resource?.text) {
        const payload = JSON.parse(a2uiResource.resource.text);
        window.a2uiProcessor.processMessages(payload);
      }
    }

    // 1. Initialize AppBridge and fetch initial controls
    async function initApp() {
      await bridge.connect();
      
      // Call server tool to load initial layout controls
      const result = await bridge.callServerTool({ name: 'fetch_controls', arguments: {} });
      processA2UIResponse(result);
    }

    // 2. Handle interactive User Actions routed by the A2UI SDK
    window.a2uiProcessor.events.subscribe(async (event) => {
      if (!event.message.userAction) return;
      const action = event.message.userAction;
      
      // Route the user action directly via the bridge to the MCP Server tool
      const result = await bridge.callServerTool({
        name: action.name,
        arguments: action.context
      });
      
      // Feed any updated server UI states back to the A2UI processor
      processA2UIResponse(result);
    });

    // Initialize the app on startup
    initApp();
  </script>
</body>
</html>

HTML

示例：嵌入式 MCP 应用功能逻辑的高级概览。它突出了使用 `postMessage` 进行宿主通信、检索动态 A2UI 布局，以及将用户交互转发回服务器的过程。

探索代码

要查看此架构的实际运行效果，请查阅我们的《MCP 应用中的 A2UI 快速入门指南》，以运行一个实时客户端。这个交互式演示包含一个拥有自身 A2UI 渲染引擎的 MCP 应用，旨在为用户提供生成式文本编辑体验。

结论

将 A2UI 与 MCP Apps 结合使用，有助于你的智能体用户界面在保持安全、强大且具有原生体验的同时，又不失创意表现力。这种统一的方法让你能够：在使用工具渲染 UI 时绕过 iframe（通过 MCP 的 A2UI），在声明式视图中展示丰富的自定义画布（A2UI 中的 MCP Apps），以及轻松地将动态 UI 嵌入到现有 Web 应用中（MCP Apps 中的 A2UI）。

选择正确的架构

A2UI 是一种灵活的消息格式，可以从任何后端传输到任何前端。这种灵活性意味着你在使用它时有很多选择。

为了帮助你理清这些选项，请使用下面的决策树，为你的项目在特定约束和要求下找到最优架构：

选择框架：请参考上述架构决策树，为你的特定智能体需求确定最佳的交付模式。

准备好在你自己的技术栈中集成 A2UI 和 MCP Apps 了吗？

• 请查阅 A2UI.org 上的 A2UI GenUI 文档。
• Read the guides
  • 通过 MCP 的 A2UI
  • A2UI 中的 MCP Apps
  • MCP Apps 中的 A2UI
• 请查阅模型上下文协议文档来设置你的服务器，并阅读 MCP Apps 概述以了解更多关于自定义应用嵌入的信息。
• 访问 A2UI GitHub 仓库，查看上述所有示例集成。