使用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工具來獲取數據，然後渲染圖表。

由於原始文章被截斷，上述內容基於可用部分進行了總結。完整文章可能包含更多示例和細節。