Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Implemente AG-UI servidores en AgentCore tiempo de ejecución

Amazon Bedrock AgentCore Runtime le permite implementar y ejecutar servidores de interfaz de usuario de agentes (AG-UI) en AgentCore tiempo de ejecución. Esta guía le explica cómo crear, probar e implementar su primer AG-UI servidor.

En esta sección, aprenderá lo siguiente:

Para obtener más información al respecto AG-UI, consulte el contrato AG-UI de protocolo.

Cómo apoya Amazon Bedrock AgentCore AG-UI

La compatibilidad con los AG-UI protocolos AgentCore de Amazon Bedrock permite la integración con los servidores de la interfaz de usuario de los agentes al actuar como una capa de proxy. Cuando se configura para AG-UI, Amazon Bedrock AgentCore espera que los contenedores ejecuten los servidores en el puerto de la /invocations ruta de 8080 entrada HTTP/SSE o destino de /ws las WebSocket conexiones. Aunque AG-UI utiliza los mismos puertos y 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 un proxy entre los clientes y su AG-UI contenedor. Las solicitudes de la InvokeAgentRuntime API se transfieren a su contenedor sin modificaciones. Amazon Bedrock AgentCore gestiona la autenticación (SigV4/OAuth 2.0), el aislamiento de las sesiones y el escalado.

Diferencias clave con respecto a otros protocolos:

Para obtener más información, consulte 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 un marco, consulte la documentación de inicio AG-UI rápido y Dojo. AG-UI

Requisitos previos

Paso 1: Crea tu servidor AG-UI

AG-UI es compatible con varios marcos de agentes. Este tutorial usa AWS Strands para Python.

Instalación de los paquetes obligatorios

Instala paquetes para AWS Strands AG-UI compatibles:

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

Para ver otros marcos, consulte las integraciones de AG-UI marcos.

Crea tu primer servidor AG-UI

Cree un archivo denominado my_agui_server.py. En este ejemplo se usa AWS Strands with AG-UI. El servidor escucha en el puerto8080, lo expone /invocations para detectar el AG-UI tráfico y lo expone /ping para comprobar su estado. AgentCore Runtime requiere este contrato para los contenedores. 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)

Para ver ejemplos completos y específicos de un marco, consulte:

Comprender el código

Paso 2: Pruebe el AG-UI servidor localmente

Ejecute y pruebe el AG-UI servidor en un entorno de desarrollo local.

Inicie su AG-UI servidor

Ejecute el AG-UI servidor localmente:

python my_agui_server.py

Debería ver un resultado que indica que el servidor se está ejecutando en el puerto8080.

Prueba del punto de conexión

Pruebe el punto final del 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ías ver los flujos de AG-UI eventos devueltos en formato SSE RUN_STARTEDTEXT_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 usar la AgentCore CLI.

Instale las herramientas de implementación

Instale la AgentCore CLI:

npm install -g @aws/agentcore

Comience por crear una carpeta de proyecto con la siguiente estructura:

## 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

Configure el grupo de usuarios de Cognito para la autenticación

Configure la autenticación para un acceso seguro a su servidor implementado. Para obtener instrucciones de configuración detalladas de Cognito, consulte Configurar el grupo de usuarios de Cognito para la autenticación. Esto proporciona los tokens de OAuth necesarios para un acceso seguro al servidor implementado.

Tras completar la configuración de Cognito, exporte los valores que utiliza el comando de implementación:

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

Configure su AG-UI servidor para la implementación

Crea un AgentCore proyecto vacío. A continuación, registre el servidor que creó en Cree su primer AG-UI servidor como agente de BYO con la configuración de Cognito del paso anterior:

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

Los comandos registran la implementación existente con el AG-UI protocolo y la configuración de OAuth de Cognito del paso anterior.

Implemente en AWS

Despliegue su agente:

agentcore deploy

Tras la implementación, recibirá un ARN en 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 tu 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

Invoca el servidor AG-UI

Para invocar el AG-UI servidor mediante programación, elija el idioma que coincida con su cliente:

Para crear aplicaciones de interfaz de usuario completas, consulte CopilotKit el SDK del AG-UI TypeScript cliente.

Apéndice

Configure 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 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: