本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

在 AgentCore 執行期中部署 AG-UI 伺服器

Amazon Bedrock AgentCore 執行期可讓您在 AgentCore 執行期中部署和執行 Agent User Interface (AG-UI) 伺服器。本指南會逐步解說如何建立、測試和部署您的第一個 AG-UI 伺服器。

在本區段，您會學習：

如需 AG-UI 的詳細資訊，請參閱 AG-UI 通訊協定合約。

Amazon Bedrock AgentCore 如何支援 AG-UI

Amazon Bedrock AgentCore 的 AG-UI 通訊協定支援透過做為代理層來啟用與代理程式使用者介面伺服器的整合。為 AG-UI 設定時，Amazon Bedrock AgentCore 預期容器在 HTTP/SSE 或 /ws WebSocket 連線/invocations路徑8080的連接埠上執行伺服器。雖然 AG-UI 使用與 HTTP 通訊協定相同的連接埠和路徑，但執行時間會根據部署組態期間指定的--protocol旗標來區分它們。

Amazon Bedrock AgentCore 做為用戶端和 AG-UI 容器之間的代理。來自 InvokeAgentRuntime API 的請求會傳遞至您的容器，無需修改。Amazon Bedrock AgentCore 會處理身分驗證 (SigV4/OAuth 2.0)、工作階段隔離和擴展。

與其他通訊協定的主要差異：

如需詳細資訊，請參閱https://docs.ag-ui.com/introduction。

搭配 AgentCore 執行期使用 AG-UI

在本教學課程中，您會建立、測試和部署 AG-UI 伺服器。

如需完整的範例和架構特定的實作，請參閱 AG-UI Quickstart 文件和 AG-UI Dojo。

先決條件

步驟 1：建立 AG-UI 伺服器

多個代理程式架構支援 AG-UI。本教學課程使用 AWS Strands for Python。

安裝必要套件

安裝支援 AG-UI 的 AWS Strands 套件：

pip install fastapi
pip install uvicorn
pip install ag-ui-strands

如需其他架構，請參閱 AG-UI 架構整合。

建立您的第一個 AG-UI 伺服器

建立名為 my_agui_server.py 的檔案。此範例使用 AWS Strands 搭配 AG-UI。伺服器接聽連接埠 8080、公開 /invocations AG-UI 流量，以及公開/ping運作狀態檢查。AgentCore Runtime 需要 AG-UI 容器的此合約。

# my_agui_server.py
import uvicorn
from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse, JSONResponse
from ag_ui_strands import StrandsAgent
from ag_ui.core import RunAgentInput
from ag_ui.encoder import EventEncoder
from strands import Agent

# Create a simple Strands agent
strands_agent = Agent(
    system_prompt="You are a helpful assistant.",
)

# Wrap with AG-UI protocol support
agui_agent = StrandsAgent(
    agent=strands_agent,
    name="my_agent",
    description="A helpful assistant",
)

# FastAPI server
app = FastAPI()

@app.post("/invocations")
async def invocations(input_data: dict, request: Request):
    """Main AG-UI endpoint that returns event streams."""
    accept_header = request.headers.get("accept")
    encoder = EventEncoder(accept=accept_header)

    async def event_generator():
        run_input = RunAgentInput(**input_data)
        async for event in agui_agent.run(run_input):
            yield encoder.encode(event)

    return StreamingResponse(
        event_generator(),
        media_type=encoder.get_content_type()
    )

@app.get("/ping")
async def ping():
    return JSONResponse({"status": "Healthy"})

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8080)

如需架構特有的完整範例，請參閱：

了解程式碼

步驟 2：在本機測試 AG-UI 伺服器

在本機開發環境中執行和測試 AG-UI 伺服器。

啟動您的 AG-UI 伺服器

在本機執行 AG-UI 伺服器：

python my_agui_server.py

您應該會看到輸出，指出伺服器正在連接埠 上執行8080。

測試端點

使用格式正確的 AG-UI 請求測試 SSE 端點：

curl -N -X POST http://localhost:8080/invocations \
-H "Content-Type: application/json" \
-d '{
  "threadId": "test-123",
  "runId": "run-456",
  "state": {},
  "messages": [{"role": "user", "content": "Hello, agent!", "id": "msg-1"}],
  "tools": [],
  "context": [],
  "forwardedProps": {}
}'

您應該會看到以 SSE 格式傳回的 AG-UI 事件串流，包括 RUN_STARTED 、 TEXT_MESSAGE_CONTENT 和 RUN_FINISHED事件。

步驟 3：將您的 AG-UI 伺服器部署到 Bedrock AgentCore 執行期

AWS 使用 AgentCore CLI 將您的 AG-UI 伺服器部署到 。

安裝部署工具

安裝 AgentCore CLI：

npm install -g @aws/agentcore

首先建立具有下列結構的專案資料夾：

## Project Folder Structure
your_project_directory/
├── my_agui_server.py          # Your main agent code
├── requirements.txt           # Dependencies for your agent

requirements.txt 使用相依性建立名為 的新檔案：

fastapi
uvicorn
ag-ui-strands

設定 Cognito 使用者集區以進行身分驗證

設定身分驗證以安全存取已部署的伺服器。如需 Cognito 設定說明的詳細資訊，請參閱設定 Cognito 使用者集區以進行身分驗證。這可提供安全存取已部署伺服器所需的 OAuth 權杖。

完成 Cognito 設定後，匯出部署命令使用的值：

export REGION="<your-region>"
export POOL_ID="<your-user-pool-id>"
export CLIENT_ID="<your-app-client-id>"

設定您的 AG-UI 伺服器以進行部署

建立空的 AgentCore 專案。然後使用上一個步驟的 Cognito 組態，將您在建立您的第一個 AG-UI 伺服器中建立的伺服器註冊為 BYO 代理程式：

agentcore create --project-name AguiProject --no-agent
cd AguiProject
agentcore add agent \
  --name AguiAgent \
  --type byo \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none \
  --code-location .. \
  --entrypoint my_agui_server.py \
  --protocol AGUI \
  --authorizer-type CUSTOM_JWT \
  --discovery-url "https://cognito-idp.$REGION.amazonaws.com/$POOL_ID/.well-known/openid-configuration" \
  --allowed-clients "$CLIENT_ID" \
  --request-header-allowlist Authorization

命令會使用 AG-UI 通訊協定和上一個步驟的 Cognito OAuth 組態註冊現有的實作。

部署至 AWS

部署您的代理程式：

agentcore deploy

部署之後，您會收到客服人員執行期 ARN，如下所示：

arn:aws:bedrock-agentcore:us-west-2:accountId:runtime/my_agui_server-xyz123

步驟 4：叫用您部署的 AG-UI 伺服器

叫用您部署的 Amazon Bedrock AgentCore AG-UI 伺服器，並與事件串流互動。

設定環境變數

設定環境變數

叫用 AG-UI 伺服器

若要以程式設計方式叫用 AG-UI 伺服器，請選擇符合您用戶端的語言：

如需建置完整的 UI 應用程式，請參閱 CopilotKit 或 AG-UI TypeScript 用戶端 SDK。

附錄

設定 Cognito 使用者集區以進行身分驗證

如需 Cognito 設定說明的詳細資訊，請參閱 MCP 文件中的設定 Cognito 使用者集區以進行身分驗證。AG-UI 伺服器的設定程序完全相同。

疑難排解

常見的 AG-UI-specific問題

以下是您可能遇到的常見問題：