使用AG-UI协议在Amazon Bedrock AgentCore上为AI代理构建生成式UI

AI代理的功能远不止聊天。通过合适的协议，代理可以在对话中内联渲染交互式图表，实时更新共享画布，或者在执行过程中暂停以请求用户批准。这些交互（生成式UI、共享状态和人机交互）需要一种标准方式，让代理后端能够将动态事件传递给前端。

AG-UI（代理-用户交互协议）就是定义这一标准的开放协议。它支持多种代理框架（Strands Agents、LangGraph、CrewAI）和前端库（React、Angular、Vue）。使用AG-UI，代理代码和前端代码保持解耦。你可以为后端选择最佳的框架，为前端选择最佳的库，而AG-UI负责连接它们。

Amazon Bedrock AgentCore是Amazon Bedrock生成式AI系列服务的一部分。AgentCore是一个代理平台，用于安全地进行大规模构建、部署和运行AI代理，支持任何框架和任何模型。

本文首先介绍AG-UI如何集成到全栈AgentCore解决方案模板（FAST）中，以在Amazon Bedrock AgentCore上构建交互式代理前端。然后展示CopilotKit如何通过生成式UI、共享状态和人机交互来扩展这一功能，所有这些都部署在Amazon Bedrock AgentCore上。

解决方案概述

Amazon Bedrock AgentCore Runtime提供了一个安全、无服务器且专门构建的托管环境，用于部署和运行AI代理或工具。AgentCore Runtime支持多种代理协议。模型上下文协议（MCP）连接代理与工具，代理到代理（A2A）连接代理与其他代理，而AG-UI连接代理与用户。当你使用AG-UI协议标志部署代理容器时，AgentCore充当透明代理。它处理身份验证（Signature Version 4 [SigV4] 或通过Amazon Cognito的OAuth 2.0）、会话隔离、扩展和可观测性。你的容器在端口8080上暴露POST /invocations用于AG-UI请求和GET /ping用于健康检查。AgentCore原封不动地传递请求。更多详情，请参阅在AgentCore Runtime中部署AGUI服务器。

FAST是一个可立即部署的入门项目。它将AgentCore Runtime、Gateway、Identity、Memory和Code Interpreter与React前端和Amazon Cognito身份验证连接起来，所有这些都通过AWS Cloud Development Kit (AWS CDK)定义。它预置了Strands Agents、LangGraph和Claude Agent SDK的代理模式。FAST v0.4.1添加了两个AG-UI模式（agui-strands-agent和agui-langgraph-agent），它们共享一个前端解析器。有关FAST架构和部署的完整介绍，请参阅使用Amazon Bedrock AgentCore的全栈入门模板加速代理应用程序开发。

该解决方案包含两层。FAST中的AG-UI提供了两个新的代理模式和一个处理这两种模式的前端解析器，因此前端不需要知道运行的是哪个代理框架。CopilotKit + FAST是一个独立的示例，它将FAST内置的聊天UI替换为CopilotKit。它增加了生成式UI（内联图表和组件）、双向共享状态（待办事项画布）和人机交互（会议调度器暂停代理并等待用户输入）。这两层都部署在AgentCore Runtime上，并使用Cognito身份验证、AgentCore Gateway用于MCP工具连接以及AgentCore Memory用于持久化对话。

架构概览。前端通过AG-UI事件与AgentCore Runtime通信。AgentCore处理身份验证、扩展和会话隔离。代理运行时将框架特定事件转换为AG-UI协议。

详细步骤

本教程分为两部分。首先，我们展示AG-UI模式如何在FAST中工作，以及单个前端解析器如何同时处理Strands和LangGraph后端。其次，我们部署CopilotKit示例，以演示AgentCore上的生成式UI、共享状态和人机交互。

源代码：

FAST仓库（包含AG-UI模式）。

CopilotKit + FAST示例。

先决条件

对于本教程，你需要具备以下先决条件：

一个具有AWS CloudFormation、Amazon Elastic Container Registry (Amazon ECR)、Amazon Bedrock AgentCore、Amazon Cognito和AWS Amplify权限的AWS账户。

安装并配置了AWS命令行界面（AWS CLI）v2。

安装了AWS CDK。

Node.js 18或更高版本以及Python 3.11或更高版本。

运行中的Docker，用于容器构建。

在Amazon Bedrock控制台中为代理使用的模型启用了模型访问。

FAST中的AG-UI：一个解析器，两种框架

agui-strands-agent模式将Strands Agent包装在来自ag-ui-strands库的StrandsAgent中。包装器自动将Strands流式事件转换为AG-UI服务器发送事件。

每个请求都会创建一个新的代理，并带有Gateway MCP工具。AgentCore Memory通过会话管理器提供程序附加到每个线程，因此对话历史记录在AgentCore Runtime扩展中保持不变。Memory是可选的：当MEMORY_ID未设置时，提供程序返回None。

BedrockAgentCoreApp读取AgentCore Runtime头（WorkloadAccessToken, Authorization, Session-Id）并填充上下文变量，因此Gateway身份验证和Memory与HTTP模式的工作方式相同。

agui-langgraph-agent模式使用来自copilotkit库的LangGraphAGUIAgent。它在每个请求上构建编译后的图，因此每次调用都会获得作用域为调用者的MCP工具。AgentCore Memory同样是可选的：当MEMORY_ID未设置时，辅助函数返回None。

两种模式产生相同的AG-UI事件。该协议定义了通过服务器发送事件的类型化事件流。例如，单个工具调用产生以下序列：RUN_STARTED, TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END, TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END, TOOL_CALL_RESULT, RUN_FINISHED。

前端解析器将每个事件映射到前端动作。例如，parseAguiChunk函数处理TEXT_MESSAGE_CONTENT、TOOL_CALL_START、TOOL_CALL_RESULT和RUN_FINISHED。

与HTTP模式相比，Strands、LangGraph和Claude-agent-sdk各自需要单独的解析器来处理其不同的流式格式。使用AG-UI，后端框架被抽象化。你可以在配置中交换agui-strands-agent和agui-langgraph-agent，前端无需更改。

要部署，请在infra-cdk/config.yaml中设置模式并运行CDK。

CopilotKit + FAST：生成式UI、共享状态和人机交互

基本的FAST前端提供了功能性的聊天界面，但AG-UI支持更丰富的交互：代理渲染自定义UI组件、与前端同步状态以及在执行过程中暂停以等待用户输入。CopilotKit是一个专门为这些模式构建的React库。CopilotKit团队在FAST之上构建了一个示例应用程序，在AgentCore上演示了这些功能。它包含LangGraph和Strands代理模式，你可以在部署时选择一种。

生成式UI涵盖从高级前端控制到高级代理自由度的范围。该示例位于受控端：前端拥有预构建的React组件，代理选择要渲染的组件并通过AG-UI事件提供数据。在频谱的更远处，代理返回声明性UI描述，由前端渲染，或者返回前端嵌入的完整UI表面。AG-UI支持所有三种，因为它标准化了事件和状态流而不是UI本身。你赋予代理的自由度越多，你需要承担的责任就越多：开放式的表面需要沙箱和输入验证。

CopilotKit示例架构。CopilotKit运行时Lambda充当浏览器和AgentCore Runtime之间的服务器端桥梁，处理AG-UI事件解析、生成式UI路由和身份验证转发。

生成式UI：代理渲染React组件

使用CopilotKit，代理可以在聊天中内联渲染自定义React组件，而不仅仅是文本。前端注册组件，代理可以通过AG-UI工具调用事件调用这些组件。

例如，注册一个饼图组件，代理可以调用它来渲染数据。当代理调用pieChart工具时，CopilotKit拦截TOOL_CALL_START和TOOL_CALL_ARGS事件，并直接在对话中渲染PieChart组件。代理首先调用query_data工具来获取数据，然后渲染图表。

由于原始文章被截断，上述内容基于可用部分进行了总结。完整文章可能包含更多示例和细节。