Build generative UI for AI agents on Amazon Bedrock AgentCore with the AG-UI protocol

在 Amazon Bedrock AgentCore 上使用 AG-UI 协议构建 AI 代理的生成式 UI | 人工智能

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

AI 代理的功能远不止聊天。通过合适的协议，代理可以在对话中直接渲染交互式图表、实时更新共享画布，或在执行过程中暂停以征求你的批准后再继续执行。这些交互（生成式 UI、共享状态和人机协作）需要一种标准化的方式，让代理后端能够与前端通信动态事件。

AG-UI（Agent-User Interaction Protocol）是一项开放协议，定义了这种标准。它兼容多种代理框架（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 运行时提供了一个安全、无服务器且专用的托管环境，用于部署和运行 AI 代理或工具。AgentCore 运行时支持多种代理协议。模型上下文协议（MCP）将代理连接到工具，Agent2Agent（A2A）将代理连接到其他代理，而 AG-UI 将代理连接到用户。当你使用 AG-UI 协议标志部署代理容器时，AgentCore 会作为透明代理运行。它处理身份验证（Signature Version 4 [SigV4] 或通过 Amazon Cognito 的 OAuth 2.0）、会话隔离、扩展性和可观测性。你的容器在端口 8080 上暴露 POST /invocations 用于 AG-UI 请求，以及 GET /ping 用于健康检查。AgentCore 会原样传递请求。有关详细信息，请参阅 [在 AgentCore 运行时中部署 AGUI 服务器](Deploy AGUI servers in AgentCore Runtime)。

FAST 是一个即开即用的启动项目。它通过 AWS 云开发工具包（AWS CDK）将 AgentCore 运行时、网关、身份验证、记忆和代码解释器与 React 前端和 Amazon Cognito 身份验证连接起来。它内置了 Strands Agents、LangGraph 和 Claude Agent SDK 的代理模式。FAST v0.4.1 新增了两种 AG-UI 模式（agui-strands-agent 和 agui-langgraph-agent），它们共享一个单一的前端解析器。如需全面了解 FAST 的架构和部署，请参阅 [使用 Amazon Bedrock AgentCore 的全栈启动模板加速代理应用程序开发](Accelerate agentic application development with a full-stack starter template for Amazon Bedrock AgentCore)。

该解决方案包含两个层次。FAST 中的 AG-UI 提供了两种新的代理模式和一个统一的前端解析器，该解析器能够处理这两种模式，因此前端无需知晓当前运行的是哪种代理框架。CopilotKit + FAST 是一个独立示例，它用 CopilotKit 替换了 FAST 内置的聊天界面。该示例新增了生成式用户界面（内联图表和组件）、双向共享状态（待办事项画布）以及人机协作交互（暂停代理并等待用户输入的会议安排器）。这两个层次均部署在 AgentCore Runtime 上，采用 Cognito 认证，通过 AgentCore Gateway 实现 MCP 工具连接，并使用 AgentCore Memory 实现对话持久化。

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

演示说明

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

源代码：

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

• CopilotKit + FAST 示例。

先决条件

进行本演示之前，您需要满足以下先决条件：

• 具备 AWS 账户，并拥有对 AWS CloudFormation、Amazon Elastic Container Registry（Amazon ECR）、Amazon Bedrock AgentCore、Amazon Cognito 和 AWS Amplify 的访问权限。

• 已安装并配置 AWS Command Line Interface（AWS CLI）v2。

• 已安装 AWS CDK。

• 安装了 Node.js 18 或更高版本以及 Python 3.11 或更高版本。

• 正在运行 Docker，用于容器构建。

• 在 Amazon Bedrock 控制台中已为代理使用的模型启用模型访问权限。

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

agui-strands-agent 模式通过 ag-ui-strands 库中的 StrandsAgent 包装 Strands 代理。该包装器会自动将 Strands 流式事件转换为 AG-UI Server-Sent Events。

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

# patterns/agui-strands-agent/agent.py
from ag_ui_strands import StrandsAgent, StrandsAgentConfig
from bedrock_agentcore.runtime import BedrockAgentCoreApp, RequestContext
from strands import Agent

app = BedrockAgentCoreApp()

# 在模块加载时一次性构建模型和代码解释器
MODEL = BedrockModel(model_id="us.anthropic.claude-sonnet-4-5-20250929-v1:0")
CODE_INTERPRETER = StrandsCodeInterpreterTools(REGION).execute_python_securely

@app.entrypoint async def invocations(payload: dict, context: RequestContext): input_data = RunAgentInput.model_validate(payload) actor_id = extract_user_id_from_context(context)

每个请求创建新的代理实例 --- 继承调用者的身份和工具

agent = Agent( model=MODEL, system_prompt=SYSTEM_PROMPT, tools=[create_gateway_mcp_client(actor_id), CODE_INTERPRETER], session_manager=get_memory_session_manager(actor_id, session_id), ) agui_agent = StrandsAgent( agent=agent, name="agui_strands_agent", config=StrandsAgentConfig( session_manager_provider=make_memory_provider(actor_id), replay_history_into_strands=False, ), ) async for event in agui_agent.run(input_data): yield event.model_dump(mode="json", by_alias=True, exclude_none=True)

BedrockAgentCoreApp 读取 AgentCore 运行时头信息（WorkloadAccessToken、Authorization、Session-Id）并填充上下文变量，因此网关认证和内存管理与 HTTP 模式的工作方式相同。

agui-langgraph-agent 模式使用 copilotkit 库中的 LangGraphAGUIAgent。它在每次请求时都会构建新的编译图，因此每次调用都会获得针对调用者的 MCP 工具。此处 AgentCore 内存也是可选启用的：当 MEMORY_ID 未设置时，辅助函数会返回 None，因此可以在不启用内存的情况下运行该模式：

patterns/agui-langgraph-agent/agent.py

from copilotkit import CopilotKitMiddleware, LangGraphAGUIAgent

async def build_graph(actor_id: str): """构建包含网关工具的新 LangGraph 编译图.""" mcp_client = await create_gateway_mcp_client(actor_id) tools = await mcp_client.get_tools() tools.append(CODE_INTERPRETER) return create_agent( model=MODEL, tools=tools, checkpointer=get_memory_saver(), # 当 MEMORY_ID 未设置时为 None middleware=[CopilotKitMiddleware()], system_prompt=SYSTEM_PROMPT, )

@app.entrypoint async def invocations(payload: dict, context: RequestContext): input_data = RunAgentInput.model_validate(payload) actor_id = extract_user_id_from_context(context) graph = await build_graph(actor_id) agui_agent = LangGraphAGUIAgent( name="agui_langgraph_agent", graph=graph, config={"configurable": {"actor_id": actor_id}}, ) async for event in agui_agent.run(input_data): yield event.model_dump(mode="json", by_alias=True, exclude_none=True)

两种模式都会产生相同的 AG-UI 事件。协议定义了基于 Server-Sent Events 的类型化事件流。例如，单个工具调用会产生以下序列：

data: {"type": "RUN_STARTED", "threadId": "t1", "runId": "r1"} data: {"type": "TEXT_MESSAGE_START", "messageId": "m1", "role": "assistant"} data: {"type": "TEXT_MESSAGE_CONTENT", "messageId": "m1", "delta": "Let me check "} data: {"type": "TEXT_MESSAGE_CONTENT", "messageId": "m1", "delta": "that for you."} data: {"type": "TEXT_MESSAGE_END", "messageId": "m1"} data: {"type": "TOOL_CALL_START", "toolCallId": "tc1", "toolCallName": "get_weather"} data: {"type": "TOOL_CALL_ARGS", "toolCallId": "tc1", "delta": "{\"location\": \"Seattle\"}"} data: {"type": "TOOL_CALL_END", "toolCallId": "tc1"} data: {"type": "TOOL_CALL_RESULT", "toolCallId": "tc1", "content": "{\"temp\": 55}"} data: {"type": "RUN_FINISHED", "threadId": "t1", "runId": "r1"}

前端解析器将每个事件映射到前端操作：

// frontend/src/lib/agentcore-client/parsers/agui.ts export const parseAguiChunk: ChunkParser = (line, callback) => { if (!line.startsWith("data: ")) return; const json = JSON.parse(line.substring(6).trim()); switch (json.type) { case "TEXT_MESSAGE_CONTENT": callback({ type: "text", content: json.delta ?? "" }); break; case "TOOL_CALL_START": callback({ type: "tool_use_start", toolUseId: json.toolCallId, name: json.toolCallName }); break; case "TOOL_CALL_RESULT": callback({ type: "tool_result", toolUseId: json.toolCallId, result: json.content ?? "" }); break; case "RUN_FINISHED": callback({ type: "result", stopReason: "end_turn" }); } };

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

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

backend: pattern: agui-strands-agent # 或 agui-langgraph-agent deployment_type: docker

cd infra-cdk cdk deploy --require-approval never python3 ../scripts/deploy-frontend.py

### 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运行时之间的服务器端桥梁，处理AG-UI事件解析、生成式UI路由和身份验证转发。

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

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

// 注册代理可渲染的饼图组件 useComponent({ name: "pieChart", description: "以饼图形式显示数据。", parameters: PieChartPropsSchema, render: PieChart, });

当代理调用 pieChart 工具时，CopilotKit 会拦截 TOOL_CALL_START 和 TOOL_CALL_ARGS 事件，并直接在对话中渲染 PieChart 组件。代理首先调用 query_data 工具从示例逗号分隔值（CSV）文件中获取数据，然后将结果传递给图表组件。

#### 共享状态：与代理同步的待办事项画布

该示例包含一个待办事项画布，它在代理和 UI 之间双向同步。当你告诉代理“添加三个任务：设计 API、编写测试、部署到预发布环境”时，代理会调用 manage_todos，画布通过 AG-UI 状态快照事件实时更新。你也可以直接在 UI 中编辑待办事项。由于 Strands 模式会将当前待办事项注入系统提示中，代理在下一次回合能看到更新后的状态：

def state_context_builder(state: dict) -> str: todos = state.get("todos", []) if todos: return f"\nCurrent todos:\n{json.dumps(todos, indent=2)}" return ""

#### 人工介入：代理暂停并等待

该示例演示了一个会议调度器，其中代理在执行过程中暂停并渲染时间选择器。用户选择时间后，代理继续使用该选择：

useHumanInTheLoop({ name: "scheduleTime", description: "与用户安排会议。", parameters: z.object({ reasonForScheduling: z.string(), meetingDuration: z.number(), }), render: ({ respond, status, args }) => ( <MeetingTimePicker status={status} respond={respond} {...args} /> ), });

这通过 AG-UI 的工具调用流程实现：代理为 scheduleTime 发出 TOOL_CALL_START，CopilotKit 渲染选择器而非执行后端工具，用户的响应作为 TOOL_CALL_RESULT 流回。

#### 部署 CopilotKit 示例

克隆 FAST 示例仓库并部署：

git clone https://github.com/aws-samples/sample-FAST-applications.git cd sample-FAST-applications/samples/copilotkit-generative-ui cp config.yaml.example config.yaml

编辑 config.yaml --- 设置 stack_name_base 和 admin_user_email

./deploy-langgraph.sh # 或 ./deploy-strands.sh

部署脚本会创建完整堆栈：Amazon Cognito 用户池、Amazon ECR 仓库、AgentCore 运行时、AgentCore 网关、AgentCore 内存、带有 Amazon API Gateway 的 CopilotKit 运行时 Lambda，以及 AWS Amplify 托管服务。完成后，打开最后打印的 Amplify URL 并登录。你将进入 CopilotKit 聊天界面，通过以下快速检查确认部署成功：

- 向代理请求示例数据的饼图。它会在对话中内联渲染。

- 要求向待办事项画布添加三个任务。画布会实时更新。

- 要求安排会议。代理会暂停并显示时间选择器。

### 清理资源

该操作指南部署了两个独立堆栈。请拆除你部署的堆栈以停止产生费用。

要删除 FAST 部署：

cd infra-cdk npx cdk destroy --all

要删除 CopilotKit 示例：

cd sample-FAST-applications/samples/copilotkit-generative-ui npx cdk destroy --all

如果 Amazon ECR 仓库中仍有容器镜像，需手动删除，因为部分 CDK 配置会保留仓库。

## 结论

本文介绍了如何使用AG-UI协议在Amazon Bedrock AgentCore上构建交互式代理前端。FAST中的AG-UI集成使您能够在不修改前端代码的情况下，在Strands和LangGraph代理后端之间进行切换。CopilotKit示例在此基础上增加了生成式UI、共享状态和人机协作交互功能，所有功能均在AgentCore上运行，并支持托管的认证、扩展性和内存管理。

如需了解更多内容，请查看以下资源：

- FAST代码库：克隆并部署AG-UI模式，使用模式：agui-strands-agent 或 pattern: agui-langgraph-agent。

- CopilotKit生成式UI示例：体验AgentCore上的生成式UI、共享状态和人机协作功能。

- AgentCore AG-UI文档：完整的协议契约和部署细节。

- AG-UI协议规范：核心事件类型和协议设计。

- CopilotKit文档：生成式UI的前端集成指南。

如您有任何问题或反馈，请在FAST代码库或FAST示例代码库中提交问题。

## 作者简介

'"`