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.
# Optimisez votre agent pour Amazon Bedrock AgentCore Runtime V2
Amazon Bedrock AgentCore Runtime V2 démarre votre agent en restaurant un instantané. Cela change la façon dont vous structurez votre code d'agent. Le travail effectué par votre agent au démarrage est capturé dans l'instantané et partagé par chaque instance restaurée. Produisez plutôt toute valeur qui doit différer d'une demande à l'autre, ou qui peut expirer, dans votre gestionnaire de requêtes. Cette rubrique explique comment structurer votre agent en fonction du travail de démarrage et du travail par requête afin qu'il reste correct après chaque restauration. Pour un aperçu de la version V2 de la plateforme, voir Versions de [ la plateforme](runtime-how-it-works.md#runtime-platform-versions).
Votre agent dispose de deux contextes d'exécution :
Startup
Code qui s'exécute une fois au démarrage de votre processus, avant que AgentCore Runtime ne prenne l'instantané. AgentCore Runtime capture ce code dans l'instantané, et chaque instance hérite de ses résultats.
Gestion des demandes
Le code de votre `/invocations` gestionnaire. Ce code s'exécute sur chaque requête sur chaque instance.
Utilisez une règle pour décider de la place du code. Calculez une valeur au démarrage si elle reste la même pendant toute la durée de vie de l'instantané. Calculez-le dans votre gestionnaire s'il varie d'une demande à l'autre ou s'il peut expirer. AgentCore Runtime prend un instantané par version d'agent et l'utilise jusqu'à ce que vous créiez ou mettiez à jour l'agent. La durée de vie de l'instantané correspond donc à la durée de vie de cette version.
## Initialiser une fois au démarrage
Effectuez des tâches coûteuses et réutilisables dès le démarrage de votre processus, avant la capture instantanée. Par exemple, importez des dépendances, chargez les poids des modèles ou lisez la configuration statique à partir de votre bundle de déploiement. Avec le AgentCore SDK, effectuez ce travail dans la portée du module, avant d'appeler`app.run()`. Votre agent n'écoute pas sur le port 8080 tant qu'il n'est pas `app.run()` exécuté. Par conséquent, aucun résultat ne `/ping` peut réussir et aucun instantané ne peut être pris tant que votre travail de démarrage n'est pas terminé. L'instantané capture un agent entièrement initialisé par construction, et vous n'avez pas besoin de gate`/ping`. Initialisation complète dans les 120 secondes suivant le démarrage. Si l'état de santé de votre agent n'est pas rétabli à temps, le moteur d'exécution échoue à son contrôle de santé. Pour plus d'informations sur les `/invocations` points de terminaison `/ping` et, voir [ Comprendre le contrat ](runtime-service-contract.md) de service AgentCore Runtime.
```
import json, pathlib
from bedrock_agentcore.runtime import BedrockAgentCoreApp
# Runs once at import, before app.run() starts the server and before the
# snapshot. Every restored instance inherits these objects.
MODEL = load_model_weights()
SETTINGS = json.loads((pathlib.Path(__file__).parent / "agent.json").read_text())
app = BedrockAgentCoreApp()
@app.entrypoint
def invoke(payload):
# Per-request work runs here on every instance.
...
app.run() # starts listening on 8080; the snapshot is taken after this
```
Si votre agent exécute son propre serveur HTTP au lieu du AgentCore SDK, signalez un état de santé `/ping` uniquement une fois l'initialisation terminée, afin que le snapshot capture un agent entièrement initialisé.
Données en lecture seule au démarrage qui sont identiques pour chaque instance et qui n'expirent pas. Gérez les valeurs sensibles au facteur temps, telles que les informations d'identification éphémères, dans votre gestionnaire.
**Note**
Ne calculez rien au démarrage que vous modifiez sans redéployer. Par exemple, un catalogue d'outils extrait depuis AgentCore Gateway semble être une valeur de démarrage idéale car son chargement est lent et coûteux, mais sa mise en cache au démarrage gèle l'inventaire des outils de votre agent au moment de la capture d'écran.
## Maintenir à jour l'état de chaque demande
L'instantané est capturé une seule fois et partagé par chaque instance restaurée, de sorte que toute valeur générée par votre agent au démarrage est identique d'une instance à l'autre et corrigée au moment de l'instantané. Gérez les valeurs que le snapshot ne peut pas prendre en charge dans votre `/invocations` gestionnaire. Le tableau suivant décrit les valeurs à calculer dans votre gestionnaire plutôt qu'au démarrage.
| Pour | Faites-le dans le gestionnaire | Raison |
| --- | --- | --- |
| Générez des valeurs, des identifiants ou des jetons aléatoires | Appelez `os.urandom()``secrets`, ou `uuid.uuid4()` sur chaque demande | `os.urandom()`renvoie une nouvelle entropie uniquement chaque fois que vous l'appelez après une restauration. Une valeur lue au démarrage est copiée dans l'instantané et est identique sur chaque instance, quelle que soit la qualité de la source d'entropie lors de sa lecture. Le `random` module est également lancé au démarrage, de sorte que les instances restaurées répètent la même séquence. |
| Lire l'heure actuelle | Calculez-le pour chaque demande | Un horodatage capturé au démarrage est corrigé au moment de la capture d'écran. |
| Mesurer le temps écoulé | Prenez l'horodatage de référence dans votre gestionnaire | `time.monotonic()`n'avance pas au cours d'une restauration, de sorte qu'une durée mesurée à partir d'une référence de démarrage est fausse sans être fausse. |
| Utiliser des informations d'identification ou des jetons | Actualisez-les lorsqu'ils expirent | Les informations d'identification chargées au démarrage peuvent expirer avant le démarrage d'une instance. |
| Identifier l'instance ou le travailleur | Générez un identifiant par demande ; ne le dérivez pas de l'hôte | Chaque instance restaurée indique le même nom d'hôte (`localhost`) et le même PID (`1`). L'utilisation de l'un ou l'autre comme identifiant réduit les métriques, les flux de journaux et les propriétaires de verrous au sein de la flotte. |
Créez des clients réutilisables au démarrage et calculez les valeurs par demande à chaque appel.
```
import os, time
# Build reusable clients at startup, before the snapshot. Exercise them here too
# (for example, with a warm-up call) so the setup the client caches — endpoint and
# credential resolution, connection pool — is captured in the snapshot.
client = build_client()
warm_up(client)
@app.entrypoint
def invoke(payload):
creds = get_credentials() # refreshed when expired, not read at startup
request_id = os.urandom(16).hex() # unique per request
now = time.time() # current time, not snapshot time
# Handle the request.
```
## Utilisez des bibliothèques cryptographiques sécurisées pour les snapshots
Lorsque AgentCore Runtime restaure une instance à partir d'un instantané, une bibliothèque cryptographique qui a mis en cache un état aléatoire au démarrage peut réutiliser cet état sur plusieurs instances. Vos bibliothèques cryptographiques doivent utiliser une version sécurisée contre les snapshots (snapsafe) qui se réensemence après une restauration.
Déploiements directs de code
L'image de base gérée par les services inclut déjà une version sécurisée de ses bibliothèques cryptographiques, de sorte que vous n'avez aucune action à effectuer pour celles-ci.
Bring-your-own bibliothèques cryptographiques
Si vous apportez vos propres bibliothèques cryptographiques, par exemple dans un agent de conteneur, utilisez des versions sécurisées pour les snapshot-safe afin qu'elles soient réensemencées après une restauration. Sur Amazon Linux 2023, utilisez`openssl-snapsafe-libs`.
## Mise en réseau
Développez des clients dès le démarrage et attendez-vous à une reconnexion transparente
Le socket que vous ouvrez au démarrage ne survit pas à une restauration, mais la configuration que votre bibliothèque cliente met en cache autour de lui (analyse du modèle de service, résolution des points de terminaison, résolution des informations d'identification et pool de connexions) survit. Créez et exercez vos clients au démarrage, et attendez-vous à ce que le premier appel après une restauration rétablisse la connexion de manière transparente.
N'utilisez pas le nom d'hôte ou le PID comme identifiant d'instance unique
Chaque instance restaurée part du même instantané et indique le même nom d'hôte et le même ID de processus. Générez un identifiant unique pour chaque demande.
Évitez de vous lier à un port source fixe
Après une restauration, la connexion maintenue au moment de la capture d'écran est rétablie et un port source fixe peut entrer en collision avec ce port de remplacement au sein de l'instance. Les instances restaurées sont des micromachines virtuelles distinctes dotées de leurs propres espaces de noms réseau. Le conflit se situe donc au sein d'une instance, et non entre elles.