# AG-UI Server in AgentCore Runtime bereitstellen Mit Amazon Bedrock AgentCore Runtime können Sie Agent User Interface (AG-UI) -Server in der AgentCore Runtime bereitstellen und ausführen. Dieser Leitfaden führt Sie durch die Erstellung, das Testen und die Bereitstellung Ihres ersten AG-UI Servers. In diesem Abschnitt lernen Sie: + So unterstützt Amazon Bedrock AgentCore AG-UI + Wie erstelle ich einen Server AG-UI + Wie testest du deinen Server lokal + Wie stellen Sie Ihren Server bereit AWS + Wie rufen Sie Ihren bereitgestellten Server auf Weitere Informationen zu finden Sie AG-UI unter [AG-UI Protokollvertrag](runtime-agui-protocol-contract.md). **Topics** + [So unterstützt Amazon Bedrock AgentCore AG-UI](#runtime-agui-how-agentcore-supports) + [Verwendung mit Runtime AG-UI AgentCore](#runtime-agui-steps) + [Anhang](#runtime-agui-appendix) ## So unterstützt Amazon Bedrock AgentCore AG-UI AgentCoreDie AG-UI Protokollunterstützung von Amazon Bedrock ermöglicht die Integration mit Agenten-Benutzeroberflächenservern, indem sie als Proxyschicht fungiert. Wenn Amazon Bedrock für konfiguriert ist AG-UI, AgentCore erwartet es, dass Container Server auf dem Port `8080` am `/invocations` Pfad für HTTP/SSE oder `/ws` für WebSocket Verbindungen ausführen. Obwohl der gleiche Port und die gleichen Pfade wie das HTTP-Protokoll AG-UI verwendet werden, unterscheidet die Laufzeit zwischen ihnen anhand des bei der `--protocol` Bereitstellungskonfiguration angegebenen Flags. Amazon Bedrock AgentCore fungiert als Proxy zwischen Kunden und Ihrem AG-UI Container. Anfragen von der [InvokeAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html)API werden unverändert an Ihren Container weitergeleitet. Amazon Bedrock AgentCore kümmert sich um Authentifizierung (SigV4/OAuth 2.0), Sitzungsisolierung und Skalierung. Hauptunterschiede zu anderen Protokollen: **Port** AG-UI Server laufen auf Port 8080 (wie HTTP, gegenüber 8000 für MCP, 9000 für A2A) **Pfad** AG-UI Server verwenden `/invocations` für HTTP/SSE und `/ws` für WebSocket (entspricht dem HTTP-Protokoll) **Nachrichtenformat** Verwendet Event-Streams über Server-Sent Events (SSE) für Streaming oder WebSocket für bidirektionale Kommunikation **Fokus auf das Protokoll** Agent-to-User Interaktion (im Vergleich zu MCP für Tools, A2A für Agent-zu-Agenten) **Authentifizierung** Unterstützt sowohl SigV4- als auch OAuth 2.0-Authentifizierungsschemata Weitere Informationen finden Sie unter [https://docs.ag-ui.com/introduction](https://docs.ag-ui.com/introduction). ## Verwendung mit Runtime AG-UI AgentCore In diesem Tutorial erstellen, testen und implementieren Sie einen AG-UI Server. [Vollständige Beispiele und Framework-spezifische Implementierungen finden Sie in der [AG-UI Schnellstart-Dokumentation](https://docs.ag-ui.com/quickstart/introduction) und in Dojo. AG-UI ](https://dojo.ag-ui.com/) **Topics** + [Voraussetzungen](#runtime-agui-prerequisites) + [Schritt 1: Erstellen Sie Ihren Server AG-UI](#runtime-agui-create-server) + [Schritt 2: Testen Sie Ihren AG-UI Server lokal](#runtime-agui-test-locally) + [Schritt 3: Stellen Sie Ihren AG-UI Server auf Bedrock Runtime AgentCore bereit](#runtime-agui-deploy) + [Schritt 4: Rufen Sie Ihren bereitgestellten Server auf AG-UI](#runtime-agui-step-4) ### Voraussetzungen + Python 3.12 oder höher oder Node.js 18\+ für TypeScript, installiert mit Grundkenntnissen der von Ihnen gewählten Sprache + Ein AWS Konto mit entsprechenden Berechtigungen und konfigurierten lokalen Anmeldeinformationen + Verständnis der AG-UI protokoll- und ereignisbasierten Kommunikationskonzepte zwischen Agenten und Benutzern ### Schritt 1: Erstellen Sie Ihren Server AG-UI AG-UI wird von mehreren Agenten-Frameworks unterstützt. Wählen Sie das Framework, das Ihren Anforderungen am besten entspricht. AWS Strands bietet AG-UI Erstanbieter-Integrationen für Python und. TypeScript #### Installieren erforderlicher Pakete Installieren Sie Pakete für AWS Strands mit AG-UI Unterstützung: **Example** 1. ``` pip install fastapi pip install uvicorn pip install ag-ui-strands ``` 1. Erstellen Sie ein `package.json` erstes: ``` { "name": "my-agui-server", "type": "module", "scripts": { "build": "tsc" }, "dependencies": { "@ag-ui/aws-strands": "^0.1.0", "@strands-agents/sdk": "^1.1.0" }, "devDependencies": { "@types/express": "^5.0.0", "@types/node": "^22.0.0", "tsx": "^4.0.0", "typescript": "^5.0.0" } } ``` Installieren Sie dann Abhängigkeiten: ``` npm install ``` Weitere Frameworks finden Sie in den [AG-UI Framework-Integrationen.](https://docs.ag-ui.com/introduction#supported-integrations) #### Erstellen Sie Ihren ersten Server AG-UI Erstellen Sie Ihre AG-UI Serverdatei in der Sprache Ihrer Wahl. In den beiden folgenden Beispielen wird ein Server erzeugt, der den Port abhört`8080`, auf AG-UI Datenverkehr `/invocations` reagiert und Integritätsprüfungen `/ping` durchführt — der Vertrag, den AgentCore Runtime von AG-UI Containern erwartet. **Example** 1. Erstellen Sie eine neue Datei mit dem Namen. `my_agui_server.py` In diesem Beispiel wird AWS Strands verwendet mit 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) ``` 1. Erstellen Sie eine neue Datei mit dem Namen`my-agui-server.ts`. In diesem Beispiel wird AWS Strands verwendet mit AG-UI: ``` // my-agui-server.ts import { Agent } from "@strands-agents/sdk"; import { StrandsAgent } from "@ag-ui/aws-strands"; import { createStrandsApp } from "@ag-ui/aws-strands/server"; async function main(): Promise { // Create a simple Strands agent const strandsAgent = new Agent({ systemPrompt: "You are a helpful assistant.", }); // Wrap with AG-UI protocol support const aguiAgent = new StrandsAgent({ agent: strandsAgent, name: "my_agent", description: "A helpful assistant", }); // Express app exposing the AgentCore-required paths on port 8080 const app = await createStrandsApp(aguiAgent, { path: "/invocations", pingPath: "/ping", }); app.listen(8080, () => { console.log("AG-UI server running on port 8080"); }); } void main(); ``` Vollständige, Framework-spezifische Beispiele finden Sie unter: + [LangGraph \+ AG-UI](https://docs.copilotkit.ai/langgraph/) + [CrewAI \+ AG-UI](https://docs.copilotkit.ai/crewai-flows) + [AWS Stränge \+ AG-UI](https://docs.copilotkit.ai/aws-strands) #### Den Code verstehen **Event-Streams** AG-UI verwendet Server-Sent Events (SSE), um typisierte Ereignisse an den Client zu streamen **/invocations Endpunkt** Primärer Endpunkt für die HTTP/SSE Kommunikation (entspricht dem HTTP-Protokoll) **Port 8080** AG-UI Server laufen in Runtime standardmäßig auf Port 8080 AgentCore ### Schritt 2: Testen Sie Ihren AG-UI Server lokal Führen Sie Ihren AG-UI Server in einer lokalen Entwicklungsumgebung aus und testen Sie ihn. #### Starten Sie Ihren AG-UI Server Führen Sie Ihren AG-UI Server lokal aus: **Example** 1. ``` python my_agui_server.py ``` 1. ``` npx tsx my-agui-server.ts ``` Sie sollten eine Ausgabe sehen, die darauf hinweist, dass der Server auf dem Port läuft`8080`. #### Testen des Endpunkts Testen Sie den SSE-Endpunkt mit einer ordnungsgemäß formatierten AG-UI Anfrage: ``` 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": {} }' ``` Sie sollten die im SSE-Format zurückgegebenen AG-UI Ereignisstreams sehen, einschließlich `RUN_STARTED``TEXT_MESSAGE_CONTENT`, und `RUN_FINISHED` Ereignisse. ### Schritt 3: Stellen Sie Ihren AG-UI Server auf Bedrock Runtime AgentCore bereit Stellen Sie Ihren AG-UI Server AWS mithilfe des Amazon Bedrock AgentCore Starter Toolkits bereit. #### Installieren Sie die Bereitstellungstools Installieren Sie das Amazon Bedrock AgentCore Starter Toolkit: ``` pip install bedrock-agentcore-starter-toolkit ``` Erstellen Sie zunächst einen Projektordner mit der folgenden Struktur: **Example** 1. ``` ## Project Folder Structure your_project_directory/ ├── my_agui_server.py # Your main agent code ├── requirements.txt # Dependencies for your agent ``` Erstellen Sie eine neue Datei `requirements.txt` mit dem Namen Ihrer Abhängigkeiten: ``` fastapi uvicorn ag-ui-strands ``` 1. ``` ## Project Folder Structure your_project_directory/ ├── my-agui-server.ts # Your main agent code ├── package.json # Dependencies for your agent └── tsconfig.json # TypeScript compiler configuration ``` Erstelle ein`tsconfig.json`: ``` { "compilerOptions": { "target": "ES2022", "lib": ["ES2022", "DOM"], "module": "NodeNext", "moduleResolution": "NodeNext", "outDir": "./dist", "strict": true, "esModuleInterop": true }, "include": ["*.ts"] } ``` #### Cognito-Benutzerpool für die Authentifizierung einrichten Konfigurieren Sie die Authentifizierung für den sicheren Zugriff auf Ihren bereitgestellten Server. Detaillierte Anweisungen zur Einrichtung von Cognito finden Sie unter [Cognito-Benutzerpool für die Authentifizierung einrichten](#runtime-agui-appendix-a). Dadurch werden die OAuth-Token bereitgestellt, die für den sicheren Zugriff auf Ihren bereitgestellten Server erforderlich sind. #### Konfigurieren Sie Ihren AG-UI Server für die Bereitstellung Nachdem Sie die Authentifizierung eingerichtet haben, erstellen Sie die Bereitstellungskonfiguration. Übergeben Sie den Einstiegspunkt, der der von Ihnen verwendeten Sprache entspricht: **Example** 1. ``` agentcore configure -e my_agui_server.py --protocol AGUI ``` 1. ``` agentcore configure -e my-agui-server.ts --protocol AGUI ``` + Wählen Sie das Protokoll als AGUI + Konfigurieren Sie mit der OAuth-Konfiguration wie im vorherigen Schritt #### Bereitstellen auf AWS Stellen Sie Ihren Agenten bereit: ``` agentcore deploy ``` Nach der Bereitstellung erhalten Sie einen Runtime-ARN für Agenten, der wie folgt aussieht: ``` arn:aws:bedrock-agentcore:us-west-2:accountId:runtime/my_agui_server-xyz123 ``` ### Schritt 4: Rufen Sie Ihren bereitgestellten Server auf AG-UI Rufen Sie Ihren bereitgestellten Amazon AgentCore AG-UI Bedrock-Server auf und interagieren Sie mit den Event-Streams. #### Umgebungsvariablen festlegen Umgebungsvariablen festlegen 1. Exportieren Sie das Bearer-Token als Umgebungsvariable. Informationen zur Einrichtung von Bearer-Token finden Sie unter [Cognito-Benutzerpool für die Authentifizierung einrichten](#runtime-agui-appendix-a). ``` export BEARER_TOKEN="" ``` 1. Exportieren Sie den Agenten-ARN. ``` export AGENT_ARN="arn:aws:bedrock-agentcore:us-west-2:accountId:runtime/my_agui_server-xyz123" ``` #### Rufen Sie den Server auf AG-UI Um den AG-UI Server programmgesteuert aufzurufen, wählen Sie die Sprache, die Ihrem Client entspricht: **Example** 1. Installieren Sie die erforderlichen Pakete: ``` pip install httpx httpx-sse ``` Verwenden Sie dann den folgenden Client-Code: ``` import asyncio import json import os from urllib.parse import quote from uuid import uuid4 import httpx from httpx_sse import aconnect_sse async def invoke_agui_agent(message: str): agent_arn = os.environ.get('AGENT_ARN') bearer_token = os.environ.get('BEARER_TOKEN') escaped_arn = quote(agent_arn, safe='') url = f"https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/{escaped_arn}/invocations?qualifier=DEFAULT" headers = { "Authorization": f"Bearer {bearer_token}", "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": str(uuid4()), } payload = { "threadId": str(uuid4()), "runId": str(uuid4()), "messages": [{"id": str(uuid4()), "role": "user", "content": message}], "state": {}, "tools": [], "context": [], "forwardedProps": {}, } async with httpx.AsyncClient(timeout=300) as client: async with aconnect_sse(client, "POST", url, headers=headers, json=payload) as sse: async for event in sse.aiter_sse(): data = json.loads(event.data) event_type = data.get("type") if event_type == "TEXT_MESSAGE_CONTENT": print(data.get("delta", ""), end="", flush=True) elif event_type == "RUN_ERROR": print(f"Error: {data.get('code')} - {data.get('message')}") asyncio.run(invoke_agui_agent("Hello!")) ``` 1. Installieren Sie die erforderlichen Pakete: ``` npm install @ag-ui/client ``` Verwenden Sie dann den folgenden Client-Code: ``` import { HttpAgent, AgentSubscriber } from "@ag-ui/client"; import { randomUUID } from "crypto"; async function invokeAguiAgent(message: string): Promise { const agentArn = process.env.AGENT_ARN!; const bearerToken = process.env.BEARER_TOKEN!; const escapedArn = encodeURIComponent(agentArn); const agent = new HttpAgent({ url: `https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/${escapedArn}/invocations?qualifier=DEFAULT`, headers: { Authorization: `Bearer ${bearerToken}`, "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": randomUUID(), }, }); agent.messages = [{ id: randomUUID(), role: "user", content: message }]; const subscriber: AgentSubscriber = { onTextMessageContentEvent: ({ event }) => { process.stdout.write(event.delta); }, onRunErrorEvent: ({ event }) => { console.error(`Error: ${event.code ?? "RUN_ERROR"} - ${event.message}`); }, }; await agent.runAgent({}, subscriber); } void invokeAguiAgent("Hello!"); ``` Informationen zum Erstellen vollständiger UI-Anwendungen finden Sie unter [CopilotKit](https://docs.copilotkit.ai/)oder im [AG-UI TypeScript Client-SDK](https://docs.ag-ui.com/sdk/js/client/overview). ## Anhang **Topics** + [Cognito-Benutzerpool für die Authentifizierung einrichten](#runtime-agui-appendix-a) + [Fehlerbehebung](#runtime-agui-troubleshooting) ### Cognito-Benutzerpool für die Authentifizierung einrichten Detaillierte Anweisungen zur Einrichtung von Cognito finden Sie in der MCP-Dokumentation unter [Cognito-Benutzerpool für die Authentifizierung](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-mcp.html#set-up-cognito-user-pool-for-authentication) einrichten. Der Einrichtungsvorgang ist für Server identisch. AG-UI ### Fehlerbehebung **Häufig auftretende AG-UI-specific Probleme** Im Folgenden sind häufig auftretende Probleme aufgeführt: Portkonflikte AG-UI Server müssen in der AgentCore Runtime-Umgebung auf Port 8080 laufen Die Autorisierungsmethode stimmt nicht überein Stellen Sie sicher, dass Ihre Anfrage dieselbe Authentifizierungsmethode (OAuth oder SigV4) verwendet, mit der der Agent konfiguriert wurde Fehler beim Format des Ereignisses Stellen Sie sicher, dass Ihre Ereignisse der AG-UI Protokollspezifikation entsprechen. Siehe [Dokumentation zu AG-UI Veranstaltungen](https://docs.ag-ui.com/concepts/events)