# Déployer AG-UI des serveurs dans AgentCore Runtime
Amazon Bedrock AgentCore Runtime vous permet de déployer et d'exécuter des serveurs Agent User Interface (AG-UI) dans le AgentCore Runtime. Ce guide explique comment créer, tester et déployer votre premier AG-UI serveur.
Dans cette section, vous allez apprendre :
+ Comment Amazon Bedrock soutient AgentCore AG-UI
+ Comment créer un AG-UI serveur
+ Comment tester votre serveur en local
+ Comment déployer votre serveur sur AWS
+ Comment appeler votre serveur déployé
Pour plus d'informations sur AG-UI, voir le [contrat de AG-UI protocole](runtime-agui-protocol-contract.md).
**Topics**
+ [Comment Amazon Bedrock soutient AgentCore AG-UI](#runtime-agui-how-agentcore-supports)
+ [Utilisation AG-UI avec AgentCore Runtime](#runtime-agui-steps)
+ [Annexe](#runtime-agui-appendix)
## Comment Amazon Bedrock soutient AgentCore AG-UI
La prise en charge AgentCore du AG-UI protocole d'Amazon Bedrock permet l'intégration aux serveurs d'interface utilisateur des agents en agissant comme une couche proxy. Lorsqu'il est configuré pour AG-UI, Amazon Bedrock AgentCore s'attend à ce que les conteneurs exécutent les serveurs sur le port `8080` situé sur le `/invocations` chemin pour HTTP/SSE ou `/ws` pour les WebSocket connexions. Bien qu'il AG-UI utilise le même port et les mêmes chemins que le protocole HTTP, le moteur d'exécution les distingue en fonction de l'`--protocol`indicateur spécifié lors de la configuration du déploiement.
Amazon Bedrock AgentCore agit comme un proxy entre les clients et votre AG-UI conteneur. Les demandes provenant de l'[InvokeAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html)API sont transmises à votre conteneur sans modification. Amazon Bedrock AgentCore gère l'authentification (SigV4/OAuth 2.0), l'isolation des sessions et le dimensionnement.
Principales différences par rapport aux autres protocoles :
**Port**
AG-UI les serveurs fonctionnent sur le port 8080 (identique au port HTTP, contre 8000 pour MCP, 9000 pour A2A)
**Chemin**
AG-UI les serveurs utilisent `/invocations` pour HTTP/SSE et `/ws` pour WebSocket (identique au protocole HTTP)
**Format du message**
Utilise les flux d' Server-Sent événements via Events (SSE) pour le streaming ou WebSocket pour la communication bidirectionnelle
**Focus sur le protocole**
Agent-to-User interaction (contre MCP pour les outils, A2A pour agent à agent)
**Authentification**
Supporte les schémas d'authentification Sigv4 et OAuth 2.0
Pour de plus amples informations, veuillez consulter [https://docs.ag-ui.com/introduction](https://docs.ag-ui.com/introduction).
## Utilisation AG-UI avec AgentCore Runtime
Dans ce didacticiel, vous allez créer, tester et déployer un AG-UI serveur.
[Pour des exemples complets et des implémentations spécifiques au framework, consultez la documentation [AG-UI Quickstart](https://docs.ag-ui.com/quickstart/introduction) et Dojo. AG-UI ](https://dojo.ag-ui.com/)
**Topics**
+ [Conditions préalables](#runtime-agui-prerequisites)
+ [Étape 1 : Créez votre AG-UI serveur](#runtime-agui-create-server)
+ [Étape 2 : Testez votre AG-UI serveur localement](#runtime-agui-test-locally)
+ [Étape 3 : Déployez votre AG-UI serveur sur Bedrock Runtime AgentCore](#runtime-agui-deploy)
+ [Étape 4 : Invoquez votre AG-UI serveur déployé](#runtime-agui-step-4)
### Conditions préalables
+ Python 3.12 ou supérieur, ou Node.js 18\+ pour TypeScript, installé avec une compréhension de base du langage que vous avez choisi
+ Un AWS compte avec les autorisations appropriées et les informations d'identification locales configurées
+ Compréhension du AG-UI protocole et des concepts de communication agent-utilisateur basés sur les événements
### Étape 1 : Créez votre AG-UI serveur
AG-UI est pris en charge par plusieurs frameworks d'agents. Choisissez le cadre qui correspond le mieux à vos besoins. AWS Strands fournit des AG-UI intégrations de première partie pour Python et. TypeScript
#### Installation des packages obligatoires
Installez des packages pour AWS Strands avec AG-UI support :
**Example**
1.
```
pip install fastapi
pip install uvicorn
pip install ag-ui-strands
```
1. Créez un `package.json` premier :
```
{
"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"
}
}
```
Installez ensuite les dépendances :
```
npm install
```
Pour les autres frameworks, consultez les [intégrations de AG-UI frameworks](https://docs.ag-ui.com/introduction#supported-integrations).
#### Créez votre premier AG-UI serveur
Créez votre fichier AG-UI serveur dans la langue de votre choix. Les deux exemples ci-dessous produisent un serveur qui écoute sur le port`8080`, expose le AG-UI trafic et effectue `/invocations` des bilans `/ping` de santé, le contrat que AgentCore Runtime attend des AG-UI conteneurs.
**Example**
1. Créez un nouveau fichier appelé`my_agui_server.py`. Cet exemple utilise AWS Strands avec 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. Créez un nouveau fichier appelé`my-agui-server.ts`. Cet exemple utilise AWS Strands avec 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();
```
Pour des exemples complets et spécifiques au framework, voir :
+ [LangGraph \+ AG-UI](https://docs.copilotkit.ai/langgraph/)
+ [Équipage AI \+ AG-UI](https://docs.copilotkit.ai/crewai-flows)
+ [AWS Brins \+ AG-UI](https://docs.copilotkit.ai/aws-strands)
#### Comprendre le code
**Streams d'événements**
AG-UI utilise Server-Sent Events (SSE) pour diffuser les événements typés vers le client
**Point de terminaison /invocations**
Point de terminaison principal pour HTTP/SSE la communication (identique au protocole HTTP)
**Port 8080**
AG-UI les serveurs s'exécutent sur le port 8080 par défaut dans Runtime AgentCore
### Étape 2 : Testez votre AG-UI serveur localement
Exécutez et testez votre AG-UI serveur dans un environnement de développement local.
#### Démarrez votre AG-UI serveur
Exécutez votre AG-UI serveur localement :
**Example**
1.
```
python my_agui_server.py
```
1.
```
npx tsx my-agui-server.ts
```
Vous devriez voir une sortie indiquant que le serveur fonctionne sur le port`8080`.
#### Tester le point de terminaison
Testez le point de terminaison SSE avec une AG-UI demande correctement formatée :
```
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": {}
}'
```
Vous devriez voir les flux d' AG-UI événements renvoyés au format SSE, y compris `RUN_STARTED``TEXT_MESSAGE_CONTENT`, et les `RUN_FINISHED` événements.
### Étape 3 : Déployez votre AG-UI serveur sur Bedrock Runtime AgentCore
Déployez votre AG-UI serveur à AWS l'aide du kit de AgentCore démarrage Amazon Bedrock.
#### Installation des outils de déploiement
Installez le kit de AgentCore démarrage Amazon Bedrock :
```
pip install bedrock-agentcore-starter-toolkit
```
Commencez par créer un dossier de projet avec la structure suivante :
**Example**
1.
```
## Project Folder Structure
your_project_directory/
├── my_agui_server.py # Your main agent code
├── requirements.txt # Dependencies for your agent
```
Créez un nouveau fichier appelé `requirements.txt` avec vos dépendances :
```
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
```
Créez un `tsconfig.json` :
```
{
"compilerOptions": {
"target": "ES2022",
"lib": ["ES2022", "DOM"],
"module": "NodeNext",
"moduleResolution": "NodeNext",
"outDir": "./dist",
"strict": true,
"esModuleInterop": true
},
"include": ["*.ts"]
}
```
#### Configuration du groupe d'utilisateurs Cognito pour l'authentification
Configurez l'authentification pour un accès sécurisé à votre serveur déployé. Pour obtenir des instructions détaillées sur la configuration de Cognito, voir [Configurer le groupe d'utilisateurs de Cognito](#runtime-agui-appendix-a) pour l'authentification. Cela fournit les jetons OAuth nécessaires pour un accès sécurisé à votre serveur déployé.
#### Configuration de votre AG-UI serveur pour le déploiement
Après avoir configuré l'authentification, créez la configuration de déploiement. Passez le point d'entrée correspondant à la langue que vous avez utilisée :
**Example**
1.
```
agentcore configure -e my_agui_server.py --protocol AGUI
```
1.
```
agentcore configure -e my-agui-server.ts --protocol AGUI
```
+ Sélectionnez le protocole AGUI
+ Configuration avec la configuration OAuth telle que définie à l'étape précédente
#### Déployer vers AWS
Déployez votre agent :
```
agentcore deploy
```
Après le déploiement, vous recevrez un ARN d'exécution de l'agent qui ressemble à ce qui suit :
```
arn:aws:bedrock-agentcore:us-west-2:accountId:runtime/my_agui_server-xyz123
```
### Étape 4 : Invoquez votre AG-UI serveur déployé
Appelez votre AgentCore AG-UI serveur Amazon Bedrock déployé et interagissez avec les flux d'événements.
#### Configurer les variables d’environnement
Configurer les variables d’environnement
1. Exportez le jeton porteur en tant que variable d'environnement. Pour la configuration du jeton porteur, voir [Configurer le groupe d'utilisateurs Cognito pour l'authentification.](#runtime-agui-appendix-a)
```
export BEARER_TOKEN=""
```
1. Exportez l'ARN de l'agent.
```
export AGENT_ARN="arn:aws:bedrock-agentcore:us-west-2:accountId:runtime/my_agui_server-xyz123"
```
#### Invoquer le AG-UI serveur
Pour appeler le AG-UI serveur par programmation, choisissez la langue qui correspond à votre client :
**Example**
1. Installez les packages requis :
```
pip install httpx httpx-sse
```
Utilisez ensuite le code client suivant :
```
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. Installez les packages requis :
```
npm install @ag-ui/client
```
Utilisez ensuite le code client suivant :
```
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!");
```
Pour créer des applications d'interface utilisateur complètes, consultez [CopilotKit](https://docs.copilotkit.ai/)le [SDK AG-UI TypeScript client](https://docs.ag-ui.com/sdk/js/client/overview).
## Annexe
**Topics**
+ [Configuration du groupe d'utilisateurs Cognito pour l'authentification](#runtime-agui-appendix-a)
+ [Résolution des problèmes](#runtime-agui-troubleshooting)
### Configuration du groupe d'utilisateurs Cognito pour l'authentification
Pour obtenir des instructions détaillées sur la configuration de Cognito, voir Configurer le groupe d'[utilisateurs de Cognito pour l'authentification](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-mcp.html#set-up-cognito-user-pool-for-authentication) dans la documentation MCP. Le processus de configuration est identique pour les AG-UI serveurs.
### Résolution des problèmes
** AG-UI-specific Problèmes courants**
Les problèmes courants que vous pouvez rencontrer sont les suivants :
Conflits portuaires
AG-UI les serveurs doivent fonctionner sur le port 8080 dans l' AgentCore environnement d'exécution
Incompatibilité entre les méthodes d'autorisation
Assurez-vous que votre demande utilise la même méthode d'authentification (OAuth ou Sigv4) que celle avec laquelle l'agent a été configuré
Erreurs de format d'événement
Assurez-vous que vos événements respectent les spécifications AG-UI du protocole. Voir la [documentation sur AG-UI les événements](https://docs.ag-ui.com/concepts/events)