# Implemente AG-UI servidores en AgentCore tiempo de ejecución
Amazon Bedrock AgentCore Runtime le permite implementar y ejecutar servidores de interfaz de usuario del agente (AG-UI) en AgentCore tiempo de ejecución. Esta guía explica cómo crear, probar e implementar su primer AG-UI servidor.
En esta sección, aprenderá lo siguiente:
+ Cómo apoya Amazon Bedrock AgentCore AG-UI
+ ¿Cómo crear un servidor AG-UI
+ ¿Cómo probar su servidor localmente
+ Cómo implementar su servidor en AWS
+ ¿Cómo invocar el servidor desplegado
Para obtener más información al respecto AG-UI, consulte el [contrato AG-UI de protocolo](runtime-agui-protocol-contract.md).
**Topics**
+ [Cómo apoya Amazon Bedrock AgentCore AG-UI](#runtime-agui-how-agentcore-supports)
+ [Uso con Runtime AG-UI AgentCore](#runtime-agui-steps)
+ [Apéndice](#runtime-agui-appendix)
## Cómo apoya Amazon Bedrock AgentCore AG-UI
La compatibilidad con AgentCore el AG-UI protocolo de Amazon Bedrock permite la integración con los servidores de la interfaz de usuario del agente al actuar como una capa de proxy. Cuando se configura para AG-UI, Amazon Bedrock AgentCore espera que los contenedores ejecuten servidores en el puerto `8080` de la `/invocations` ruta para HTTP/SSE o `/ws` para WebSocket las conexiones. Aunque AG-UI utiliza el mismo puerto y las mismas rutas que el protocolo HTTP, el tiempo de ejecución los distingue en función del `--protocol` indicador especificado durante la configuración de la implementación.
Amazon Bedrock AgentCore actúa como intermediario entre los clientes y su AG-UI contenedor. Las solicitudes de la [InvokeAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html)API se transfieren a su contenedor sin modificaciones. Amazon Bedrock AgentCore gestiona la autenticación (SigV4/OAuth 2.0), el aislamiento de sesiones y el escalado.
Diferencias clave con respecto a otros protocolos:
**Puerto**
AG-UI los servidores se ejecutan en el puerto 8080 (igual que el HTTP, frente al 8000 para el MCP y el 9000 para el A2A)
**Ruta**
AG-UI los servidores utilizan `/invocations` para HTTP/SSE y `/ws` para WebSocket (igual que el protocolo HTTP)
**Formato de mensaje**
Utiliza transmisiones de Server-Sent eventos a través de Events (SSE) para la transmisión o WebSocket para la comunicación bidireccional
**Enfoque de protocolo**
Agent-to-User interacción (frente a MCP para herramientas, A2A para agente a agente)
**Autenticación**
Soporta los esquemas de autenticación SigV4 y OAuth 2.0
Para obtener más información, consulte [https://docs.ag-ui.com/introduction](https://docs.ag-ui.com/introduction).
## Uso con Runtime AG-UI AgentCore
En este tutorial, creará, probará e implementará un AG-UI servidor.
[Para ver ejemplos completos e implementaciones específicas de marcos, consulte la documentación de inicio [AG-UI rápido](https://docs.ag-ui.com/quickstart/introduction) y Dojo. AG-UI ](https://dojo.ag-ui.com/)
**Topics**
+ [Requisitos previos](#runtime-agui-prerequisites)
+ [Paso 1: Crea tu servidor AG-UI](#runtime-agui-create-server)
+ [Paso 2: Pruebe su AG-UI servidor localmente](#runtime-agui-test-locally)
+ [Paso 3: Implemente su AG-UI servidor en Bedrock Runtime AgentCore](#runtime-agui-deploy)
+ [Paso 4: invoca el servidor desplegado AG-UI](#runtime-agui-step-4)
### Requisitos previos
+ Python 3.12 o superior, o superior a Node.js 18 años TypeScript, instalado con un conocimiento básico del idioma elegido
+ Una AWS cuenta con los permisos adecuados y las credenciales locales configuradas
+ Comprensión de los conceptos de comunicación entre agente y usuario basada en AG-UI protocolos y eventos
### Paso 1: Crea tu servidor AG-UI
AG-UI es compatible con varios marcos de agentes. Elija el marco que mejor se adapte a sus necesidades. AWS Strands proporciona AG-UI integraciones propias para Python y. TypeScript
#### Instalación de los paquetes obligatorios
Instala paquetes para AWS Strands con AG-UI soporte:
**Example**
1.
```
pip install fastapi
pip install uvicorn
pip install ag-ui-strands
```
1. Crea una `package.json` primera:
```
{
"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"
}
}
```
Luego instala las dependencias:
```
npm install
```
Para otros marcos, consulte las [integraciones del AG-UI marco](https://docs.ag-ui.com/introduction#supported-integrations).
#### Cree su primer servidor AG-UI
Cree su archivo de AG-UI servidor en el idioma que prefiera. Los dos ejemplos siguientes crean un servidor que escucha en el puerto`8080`, lo expone al `/invocations` AG-UI tráfico y a las comprobaciones `/ping` de estado, el contrato que AgentCore Runtime espera de AG-UI los contenedores.
**Example**
1. Cree un archivo nuevo llamado. `my_agui_server.py` En este ejemplo, se usa AWS Strands con 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. Cree un archivo nuevo llamado`my-agui-server.ts`. En este ejemplo, se usa AWS Strands con 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();
```
Para ver ejemplos completos y específicos del marco, consulte:
+ [LangGraph \+ AG-UI](https://docs.copilotkit.ai/langgraph/)
+ [CrewAI \+ AG-UI](https://docs.copilotkit.ai/crewai-flows)
+ [AWS Hilos \+ AG-UI](https://docs.copilotkit.ai/aws-strands)
#### Entendiendo el código
**Transmisiones de eventos**
AG-UI usa Server-Sent Events (SSE) para transmitir eventos escritos al cliente
**/invocations Endpoint**
Punto final principal para la HTTP/SSE comunicación (igual que el protocolo HTTP)
**Puerto 8080**
AG-UI los servidores se ejecutan en el puerto 8080 de forma predeterminada en Runtime AgentCore
### Paso 2: Pruebe su AG-UI servidor localmente
Ejecute y pruebe su AG-UI servidor en un entorno de desarrollo local.
#### Inicie su AG-UI servidor
Ejecute el AG-UI servidor localmente:
**Example**
1.
```
python my_agui_server.py
```
1.
```
npx tsx my-agui-server.ts
```
Debería ver un resultado que indica que el servidor se está ejecutando en el puerto`8080`.
#### Prueba del punto de conexión
Pruebe el punto final SSE con una AG-UI solicitud con el formato correcto:
```
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": {}
}'
```
Debería ver los flujos de AG-UI eventos devueltos en formato SSE `RUN_STARTED``TEXT_MESSAGE_CONTENT`, incluidos `RUN_FINISHED` los eventos y.
### Paso 3: Implemente su AG-UI servidor en Bedrock Runtime AgentCore
Implemente su AG-UI servidor para AWS utilizar el kit de herramientas de AgentCore inicio de Amazon Bedrock.
#### Instale las herramientas de implementación
Instale el kit de herramientas de AgentCore inicio de Amazon Bedrock:
```
pip install bedrock-agentcore-starter-toolkit
```
Comience por crear una carpeta de proyecto con la siguiente estructura:
**Example**
1.
```
## Project Folder Structure
your_project_directory/
├── my_agui_server.py # Your main agent code
├── requirements.txt # Dependencies for your agent
```
Crea un nuevo archivo llamado `requirements.txt` con tus dependencias:
```
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
```
Crea un`tsconfig.json`:
```
{
"compilerOptions": {
"target": "ES2022",
"lib": ["ES2022", "DOM"],
"module": "NodeNext",
"moduleResolution": "NodeNext",
"outDir": "./dist",
"strict": true,
"esModuleInterop": true
},
"include": ["*.ts"]
}
```
#### Configurar el grupo de usuarios de Cognito para la autenticación
Configure la autenticación para un acceso seguro al servidor implementado. Para obtener instrucciones detalladas de configuración de Cognito, consulte [Configurar el grupo de usuarios de Cognito para la autenticación](#runtime-agui-appendix-a). Esto proporciona los tokens de OAuth necesarios para un acceso seguro al servidor implementado.
#### Configura tu AG-UI servidor para el despliegue
Tras configurar la autenticación, cree la configuración de despliegue. Pase el punto de entrada que coincida con el idioma que utilizó:
**Example**
1.
```
agentcore configure -e my_agui_server.py --protocol AGUI
```
1.
```
agentcore configure -e my-agui-server.ts --protocol AGUI
```
+ Seleccione el protocolo como AGUI
+ Configure con la configuración de OAuth tal como se configuró en el paso anterior
#### Implemente en AWS
Despliegue a su agente:
```
agentcore deploy
```
Tras la implementación, recibirá un ARN de tiempo de ejecución del agente con el siguiente aspecto:
```
arn:aws:bedrock-agentcore:us-west-2:accountId:runtime/my_agui_server-xyz123
```
### Paso 4: invoca el servidor desplegado AG-UI
Invoque su AgentCore AG-UI servidor Amazon Bedrock implementado e interactúe con las transmisiones de eventos.
#### Configure las variables de entorno
Configure las variables de entorno
1. Exporte el token portador como variable de entorno. Para configurar el token de portador, consulte [Configurar el grupo de usuarios de Cognito para la autenticación](#runtime-agui-appendix-a).
```
export BEARER_TOKEN=""
```
1. Exporte el ARN del agente.
```
export AGENT_ARN="arn:aws:bedrock-agentcore:us-west-2:accountId:runtime/my_agui_server-xyz123"
```
#### Invoca el servidor AG-UI
Para invocar el AG-UI servidor mediante programación, elija el idioma que mejor se adapte a su cliente:
**Example**
1. Instale los paquetes obligatorios:
```
pip install httpx httpx-sse
```
A continuación, utilice el siguiente código de cliente:
```
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. Instale los paquetes obligatorios:
```
npm install @ag-ui/client
```
A continuación, utilice el siguiente código de cliente:
```
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!");
```
Para crear aplicaciones de interfaz de usuario completas, consulte [CopilotKit](https://docs.copilotkit.ai/)el [SDK del AG-UI TypeScript cliente](https://docs.ag-ui.com/sdk/js/client/overview).
## Apéndice
**Topics**
+ [Configurar el grupo de usuarios de Cognito para la autenticación](#runtime-agui-appendix-a)
+ [Resolución de problemas](#runtime-agui-troubleshooting)
### Configurar el grupo de usuarios de Cognito para la autenticación
Para obtener instrucciones detalladas de configuración de Cognito, consulte Configurar el grupo de [usuarios de Cognito para la autenticación en la documentación](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-mcp.html#set-up-cognito-user-pool-for-authentication) de MCP. El proceso de configuración es idéntico para los servidores. AG-UI
### Resolución de problemas
** AG-UI-specific Problemas comunes**
Los siguientes son problemas comunes que pueden surgir:
Conflictos portuarios
AG-UI los servidores deben ejecutarse en el puerto 8080 en el AgentCore entorno de ejecución
El método de autorización no coincide
Asegúrese de que la solicitud utilice el mismo método de autenticación (OAuth o SigV4) con el que se configuró el agente
Errores de formato de evento
Asegúrese de que sus eventos sigan las especificaciones AG-UI del protocolo. Consulte la [documentación de AG-UI eventos](https://docs.ag-ui.com/concepts/events)