View a markdown version of this page

Configurer les hooks de cycle de vie pour AgentCore Durée d'exécution - Substrat rocheux d'Amazon AgentCore

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.

Configurer les hooks de cycle de vie pour AgentCore Durée d'exécution

Un hook de cycle de vie est un point final de votre conteneur qui AgentCore Les appels d'exécution surviennent à un moment précis du cycle de vie de l'environnement d'exécution de votre agent. Utilisez des hooks pour exécuter votre propre code à ces moments, par exemple pour préparer votre agent avant le début des sessions. Vous configurez les hooks avec hooksConfiguration domaine de CreateAgentRuntime et UpdateAgentRuntime, regroupés selon la phase du cycle de vie à laquelle ils appartiennent.

Les hooks Lifecycle sont disponibles pour les environnements d'exécution des agents qui utilisent la version V2 de la plate-forme sur des micromachines virtuelles. Pour plus d'informations, voir Versions de la plateforme.

Exigences

  • L'environnement d'exécution de l'agent doit utiliser la version V2 de la plateforme. Sur la V1, la demande échoue avec un ValidationException.

  • L'environnement d'exécution de l'agent doit utiliser le type de calcul MicroVMS. Les hooks Lifecycle ne sont pas pris en charge sur les instances : si vous combinez hooksConfiguration avec capacityProviderConfiguration, la demande échoue avec un ValidationException.

Comment fonctionne un hook call

Lorsque l'exécution de votre agent atteint un point critique dans son cycle de vie, AgentCore Runtime exécute l'action du hook une fois. Il envoie une seule demande à votre conteneur et attend que votre implémentation signale le succès dans les délais impartis par le hook. AgentCore L'environnement d'exécution ne réessaie pas un appel hook.

Si l'appel échoue ou n'aboutit pas dans le délai imparti, l'opération qui a déclenché le hook échoue. Par exemple, lorsqu'un hook de génération échoue, le moteur d'exécution passe à CREATE_FAILED ou UPDATE_FAILED avec un failureReason qui décrit l'échec. Pour plus d'informations, voir Résoudre les problèmes liés au cycle de vie.

La réussite de votre implémentation dépend de l'action du hook.

Actions liées aux crochets

Chaque crochet possède une action, qui définit comment AgentCore Runtime appelle votre conteneur.

Actions HTTP

Une action HTTP envoie une requête HTTP au path et port que vous choisissez, sur un serveur de votre conteneur. Vos rapports de mise en œuvre sont réussis en renvoyant tout 2xx code d'état une fois son travail terminé. Tout autre code d'état ou un échec de connexion entraîne l'échec de l'appel. Chaque demande peut inclure des en-têtes identifiant l'appel. Chaque hook répertorie les en-têtes et les valeurs qu'il envoie.

Les crochets soutiennent le httpPost action, qui envoie un POST demande. Vous le configurez dans le hook action.httpPost champ, qui contient les champs suivants.

Champ Type Obligatoire Description

path

Chaîne

Oui

Le chemin qui AgentCore Runtime envoie la demande à. Le chemin doit respecter les règles suivantes :

  • Il contient 1 à 32 caractères et correspond au modèle ^/[A-Za-z0-9._~/-]*$.

  • C'est sous forme canonique. Cela ne s'arrête pas à / (sauf pour le chemin) / lui-même), et il ne contient pas //, ou . ou .. segments.

  • Cela n'entre pas en conflit avec un itinéraire qui AgentCore Runtime l'utilise déjà sur le même port. Pour plus d'informations, voir Routes de la plateforme.

port

Entier

Non

Le port qui AgentCore Runtime envoie la demande à. La plage prise en charge est 8000—12000, inclus. Choisissez un port autre que ports de plate-forme réservés. Si vous ne spécifiez aucun port, le port par défaut est le port de service de votre agent : protocolConfiguration.port si vous le définissez, sinon le port par défaut du protocole (8080 pour HTTP et AG-UI, 8000 pour MCP, et 9000 pour A2A).

La route d'un hook est sa méthode, son chemin et son port HTTP. Il ne peut pas correspondre à un itinéraire qui AgentCore Runtime utilise déjà le port de service de votre agent. Le tableau suivant répertorie les itinéraires de ces plateformes.

Routes de plateforme qu'un hook ne peut pas utiliser
Protocole Routes qu'un hameçon ne peut pas emprunter

Tous les protocoles

  • POST vers le chemin d'invocation : protocolConfiguration.path si vous le définissez, sinon c'est la valeur par défaut du protocole (/invocations pour HTTP et AG-UI, /mcp pour MCP, et / pour A2A)

  • GET /ws

  • GET /ping

MCP

POST /mcp, même si vous modifiez le chemin d'invocation

A2A

GET /.well-known/agent-card.json

Les conflits comparent la méthode et le chemin. Par exemple, POST /ping est un itinéraire d'accrochage valide, car AgentCore Utilisations du runtime GET /ping. Pour votre port de service et votre chemin d'invocation, voir Configurez le port de service et le chemin d'invocation de votre agent.

Note

Si l'environnement d'exécution de votre agent utilise points de fin de session, AgentCore Runtime protège vos hooks contre les demandes de point de terminaison de session :

  • Une requête qui cible la route d'un hook est rejetée par HTTP 403 et AccessDenied avant qu'il n'atteigne votre conteneur. La correspondance de chemin ignore les majuscules et minuscules et traite les orthographes équivalentes courantes d'un chemin comme étant le même chemin. Il s'agit notamment de barres obliques répétées ou de fin, . et .. segments, caractères codés en pourcentage et ; paramètres.

  • Les en-têtes Hook sont réservés. AgentCore Runtime les supprime des demandes de point de terminaison de session, de sorte que votre application ne reçoit les en-têtes hook que lors des appels hook.

Configurer les hooks du cycle de vie

Spécifiez hooksConfiguration lorsque vous créez ou mettez à jour un environnement d'exécution d'agent. L'exemple suivant crée un environnement d'exécution V2 avec un hook d'échauffement de construction qui appelle POST /warmup sur le port 8080. Pour savoir à quoi sert le crochet, voir Construire un crochet d'échauffement. Remplacez la région, l'URI de l'image de conteneur et l'ARN du rôle d'exécution par vos valeurs.

Exemple
AWS SDK
import boto3 client = boto3.client('bedrock-agentcore-control', region_name='us-west-2') try: response = client.create_agent_runtime( agentRuntimeName='my_agent_runtime', agentRuntimeArtifact={ 'containerConfiguration': { 'containerUri': '123456789012.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest' } }, networkConfiguration={'networkMode': 'PUBLIC'}, roleArn='arn:aws:iam::123456789012:role/AgentRuntimeRole', platformVersion='V2', hooksConfiguration={ 'build': { 'warmup': { 'action': { 'httpPost': { 'path': '/warmup', 'port': 8080 } } } } } ) print(f"Agent runtime created: {response['agentRuntimeArn']}") except client.exceptions.ValidationException as e: print(f"Validation error: {e}")
AWS CLI
aws bedrock-agentcore-control create-agent-runtime \ --agent-runtime-name "my_agent_runtime" \ --role-arn "arn:aws:iam::123456789012:role/AgentRuntimeRole" \ --agent-runtime-artifact '{ "containerConfiguration": { "containerUri": "123456789012.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest" } }' \ --network-configuration '{"networkMode": "PUBLIC"}' \ --platform-version V2 \ --hooks-configuration '{ "build": { "warmup": { "action": { "httpPost": {"path": "/warmup", "port": 8080} } } } }'

UpdateAgentRuntime remplace l'ensemble de la configuration des crochets. Inclure hooksConfiguration dans chaque demande de mise à jour pour laquelle vous souhaitez conserver vos hooks. Pour supprimer vos crochets, appelez UpdateAgentRuntime sans hooksConfiguration.

Crochets pris en charge

Phase Crochet Quand AgentCore Runtime l'appelle Utilisez-le pour

build

warmup

Pendant qu'il prépare votre agent, pendant CreateAgentRuntime et UpdateAgentRuntime

Préparez la mémoire et le disque pour que les sessions démarrent plus rapidement. Pour plus d'informations, voir Construisez un crochet d'échauffement.

Construisez un crochet d'échauffement

AgentCore Runtime appelle le hook d'échauffement de la construction pendant qu'il prépare votre agent, pendant CreateAgentRuntime et UpdateAgentRuntime, avant que le temps d'exécution n'atteigne READY. Il effectue deux appels, dans cet ordre, et indique à votre implémentation de quel appel il s'agit :

Type d'échauffement Ordre Que faire

memory

Tout d'abord, une fois que votre agent a réussi son /ping bilan de santé

Chargez en mémoire ce dont chaque session a besoin, comme les importations, les modèles et les caches. Chaque nouvelle instance commence par ce que vous chargez ici.

disk

Seconde

Lisez les fichiers que votre agent lit lorsqu'une session démarre. AgentCore Runtime utilise ces lectures pour rendre ces fichiers disponibles plus rapidement pour les nouvelles sessions.

Avec une action HTTP, AgentCore Runtime envoie le type d'échauffement dans X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type en-tête, avec la valeur memory ou disk.

La durée des deux appels est limitée à 120 secondes au total. Parce que memory l'appel est lancé en premier, le disk l'appel obtient l'heure à laquelle memory feuilles d'appel. Par exemple, si le memory l'appel dure 50 secondes, le disk L'appel dure 70 secondes. Vous ne pouvez pas modifier cette limite.

Un crochet d'échauffement peut ajouter jusqu'à 120 secondes au temps CreateAgentRuntime et UpdateAgentRuntime prendre pour atteindre READY. Chaque ligne de journal de préchauffage peut apparaître plusieurs fois pour une création ou une mise à jour.

Écrivez le gestionnaire d'échauffement

Votre gestionnaire d'échauffement s'exécute sur le serveur de votre agent, en même temps que /ping et votre gestionnaire d'invocation :

  • Gardez /ping réactif. Votre serveur doit continuer à répondre /ping pendant l'échauffement. Ne bloquez pas le seul thread de votre serveur dans le gestionnaire de préchauffage. Exécutez le travail dans un thread ou un processus distinct, ou utilisez un serveur qui gère les demandes simultanément.

  • Retourner 2xx seulement une fois le travail terminé. Ce que vous avez chargé lorsque vous répondez correspond au début des sessions.

L'application FastAPI suivante sert /ping, /invocations, et un crochet d'échauffement à POST /warmup sur le port 8080. Il exécute le travail d'échauffement dans un thread de travail, afin que le serveur continue de répondre /ping. Remplacer load_shared_state et STARTUP_FILES avec le travail et les dossiers de votre agent.

import asyncio from fastapi import FastAPI, Request, Response app = FastAPI() # Files that each session reads when it starts. STARTUP_FILES = ["/app/models/tokenizer.json", "/app/config/agent.json"] def load_shared_state(): # Load what every session needs into memory, such as heavy imports, # model weights, and caches. ... def read_startup_files(): # Read the files that a session reads when it starts, so that new # sessions can use them faster. for path in STARTUP_FILES: with open(path, "rb") as f: while f.read(1024 * 1024): pass @app.get("/ping") def ping(): return {"status": "Healthy"} @app.post("/warmup") async def warmup(request: Request): # Header lookup in Starlette and FastAPI is case-insensitive. warmup_type = request.headers.get( "X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type", "" ).lower() # Run the work in a worker thread so that /ping keeps answering. if warmup_type == "memory": await asyncio.to_thread(load_shared_state) elif warmup_type == "disk": await asyncio.to_thread(read_startup_files) # Respond only after the work is done. return Response(status_code=200) @app.post("/invocations") async def invoke(request: Request): payload = await request.json() # Per-request work runs here on every session. return {"response": payload.get("prompt", "")}

Si vous enregistrez l'application sous app.py, démarrez-le dans votre conteneur à l'aide de la commande suivante :

uvicorn app:app --host 0.0.0.0 --port 8080

Pour savoir ce qu'il faut inclure dans chaque appel, voir Préparez la mémoire et le disque à l'aide d'un hook de cycle de vie.

Afficher les journaux des crochets

AgentCore Runtime écrit la progression et le résultat de chaque appel de build hook dans le groupe de journaux de votre environnement d'exécution, /aws/bedrock-agentcore/runtimes/<agentRuntimeId>-DEFAULT, dans les flux de journaux dont le nom commence par build-logs-. Chaque ligne commence par [LIFECYCLE-HOOK <epoch-milliseconds>], suivi par [LIFECYCLE] pour progresser ou [ERROR] pour les échecs. Pour connaître les lignes et savoir comment les modifier, voir Résoudre les problèmes liés au cycle de vie.