Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Déploiement de AG-UI serveurs dans AgentCore Runtime

Amazon Bedrock AgentCore Runtime vous permet de déployer et d'exécuter des serveurs d'interface utilisateur d'agent (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 :

Pour plus d'informations à ce sujet AG-UI, consultez le contrat de AG-UI protocole.

Comment Amazon Bedrock soutient AgentCore AG-UI

La prise en charge AgentCore du AG-UI protocole d'Amazon Bedrock permet l'intégration avec les serveurs d'interface utilisateur des agents en agissant comme une couche proxy. Une fois configuré pour AG-UI, Amazon Bedrock AgentCore s'attend à ce que les conteneurs exécutent des 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'--protocolindicateur spécifié lors de la configuration du déploiement.

Amazon Bedrock AgentCore fait office de proxy entre les clients et votre AG-UI conteneur. Les demandes de l'InvokeAgentRuntimeAPI sont transmises à votre conteneur sans modification. Amazon Bedrock AgentCore gère l'authentification (SigV4/OAuth 2.0), l'isolation des sessions et la mise à l'échelle.

Principales différences par rapport aux autres protocoles :

Pour de plus amples informations, veuillez consulter 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 et Dojo. AG-UI

Conditions préalables

Étape 1 : Créez votre AG-UI serveur

AG-UI est pris en charge par plusieurs frameworks d'agents. Ce didacticiel utilise AWS Strands pour Python.

Installation des packages obligatoires

Installez les packages pour AWS Strands avec le AG-UI support suivant :

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

Pour les autres frameworks, consultez les intégrations des AG-UI frameworks.

Créez votre premier AG-UI serveur

Créez un fichier nommé my_agui_server.py. Cet exemple utilise AWS Strands with AG-UI. Le serveur écoute sur le port8080, expose le AG-UI trafic et /invocations l'expose pour des contrôles de santé/ping. AgentCore Runtime nécessite ce contrat pour les AG-UI conteneurs.

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

Pour des exemples complets et spécifiques au framework, voir :

Comprendre le code

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

python my_agui_server.py

Vous devriez voir une sortie indiquant que le serveur fonctionne sur le port8080.

Tester le point de terminaison

Testez le point de terminaison SSE avec une AG-UI requête 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_STARTEDTEXT_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 de la AgentCore CLI.

Installation des outils de déploiement

Installez la AgentCore CLI :

npm install -g @aws/agentcore

Commencez par créer un dossier de projet avec la structure suivante :

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

Configurer le groupe d'utilisateurs Cognito pour l'authentification

Configurez l'authentification pour sécuriser l'accès à votre serveur déployé. Pour obtenir des instructions détaillées sur la configuration de Cognito, voir Configurer le groupe d'utilisateurs Cognito pour l'authentification. Cela fournit les jetons OAuth nécessaires pour un accès sécurisé à votre serveur déployé.

Une fois la configuration de Cognito terminée, exportez les valeurs utilisées par la commande de déploiement :

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

Configurez votre AG-UI serveur pour le déploiement

Créez un AgentCore projet vide. Enregistrez ensuite le serveur que vous avez créé dans Créer votre premier AG-UI serveur en tant qu'agent BYO avec la configuration Cognito de l'étape précédente :

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

Les commandes enregistrent l'implémentation existante avec le AG-UI protocole et la configuration Cognito OAuth de l'étape précédente.

Déployez 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 à :

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

Étape 4 : Invoquez votre serveur déployé AG-UI

Invoquez 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

Invoquer le serveur AG-UI

Pour appeler le AG-UI serveur par programmation, choisissez la langue qui correspond à votre client :

Pour créer des applications d'interface utilisateur complètes, consultez CopilotKit le SDK AG-UI TypeScript client.

Annexe

Configurer le groupe d'utilisateurs Cognito pour l'authentification

Pour obtenir des instructions détaillées sur la configuration de Cognito, consultez la section Configuration du groupe d'utilisateurs Cognito pour l'authentification 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 :