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 le code de votre agent. Le travail effectué par votre agent au démarrage est capturé dans le snapshot et partagé par chaque instance restaurée. Produisez plutôt toute valeur qui doit différer entre les demandes, ou qui peut expirer, dans votre gestionnaire de demandes. Cette rubrique explique comment structurer votre agent en fonction du travail de démarrage et du travail par demande 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 seule fois au démarrage de votre processus, avant que AgentCore Runtime ne prenne le snapshot. AgentCore Runtime capture ce code dans le snapshot, et chaque instance hérite de ses résultats. Traitement 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éterminer 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 en fonction de la demande 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ébut de votre processus, avant la capture instantanée. Par exemple, importez des dépendances, chargez les pondérations des modèles ou lisez la configuration statique depuis votre bundle de déploiement. Avec le AgentCore SDK, effectuez ce travail à 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é. Il est donc `/ping` impossible de réussir et aucun instantané ne peut être pris avant la fin de votre travail de démarrage. L'instantané capture un agent entièrement initialisé par construction, et il n'est pas nécessaire de le fermer. `/ping` Terminez l'initialisation dans les 120 secondes suivant le démarrage. Si l'état de santé de votre agent n'est pas rétabli à temps, le test de santé du moteur d'exécution échoue. Pour plus d'informations sur les `/invocations` points de terminaison `/ping` et, voir [Comprendre le contrat de service AgentCore Runtime](runtime-service-contract.md). ``` 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 sain `/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 les mêmes pour chaque instance et qui n'expirent pas. Gérez les valeurs sensibles au temps, telles que les informations d'identification de courte durée, dans votre gestionnaire. **Note** Au démarrage, ne calculez aucun élément que vous modifiez sans le redéployer. Par exemple, un catalogue d'outils extrait de 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 bloque l'inventaire des outils de votre agent au moment de la capture instantanée. ## Maintenir à jour l'état de chaque demande L'instantané est capturé une 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 fixée au moment de la capture instantanée. Gérez les valeurs que l'instantané ne peut pas contenir 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()` à 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 le snapshot et est identique sur chaque instance, quelle que soit la qualité de la source d'entropie au moment de la lecture. Le `random` module est également prédéfini 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 fixé au moment de la capture instantanée. | | Mesurer le temps écoulé | Prenez l'horodatage de référence dans votre gestionnaire | `time.monotonic()`n'avance pas au cours d'une restauration. Par conséquent, une durée mesurée à partir d'une référence de démarrage est erronée sans donner une fausse apparence. | | 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. | | Identifiez 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 permet de réduire 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 des 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. ``` ## Utiliser des bibliothèques cryptographiques sécurisées pour les snapshots Lorsque AgentCore Runtime restaure des instances à partir d'un instantané, chaque instance créée à partir de cet instantané commence par une copie identique de la mémoire capturée au moment de l'instantané. Cela inclut l'état interne des générateurs de nombres aléatoires dans les bibliothèques cryptographiques, ainsi que les clés, jetons ou identifiants créés par votre agent lors de l'initialisation. À moins que cet état ne soit actualisé après la restauration, les instances peuvent produire les mêmes valeurs « aléatoires ». **Limitation actuelle** Lors de l' AgentCore exécution, les versions de bibliothèques cryptographiques sécurisées pour les snapshots ne sont actuellement pas réinitialisées après une restauration. Cela s'applique à la fois aux déploiements directs de code et aux déploiements de conteneurs. **Solutions de contournement** + Générez des secrets, des clés, des jetons et des identifiants de session lors du traitement d'une demande, et non au démarrage de votre agent. Cela évite d'utiliser les valeurs créées avant que AgentCore Runtime ne prenne l'instantané dans chaque instance restaurée à partir de cet instantané. + Même lors du traitement d'une requête, obtenez des valeurs aléatoires directement à partir du système d'exploitation, par exemple celles de `secrets` Python `os.urandom``crypto/rand`, de Go ou de lecture`/dev/urandom`. N'utilisez pas de valeurs aléatoires issues d'une bibliothèque cryptographique telle qu'OpenSSL, car elles peuvent se répéter d'une instance à l'autre. ## Mise en réseau Créez 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 celui-ci (analyse du modèle de service, résolution des points de terminaison, résolution des identifiants et pool de connexions) le fait. Construisez et entraînez 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 identifiant 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 du snapshot 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 microVM distinctes dotées de leurs propres espaces de noms réseau, de sorte que le conflit se situe au sein d'une instance et non entre elles. ## Cross-account métriques et quotas Dans le cas d'un appel entre comptes, où le principal d'un compte invoque un environnement d'exécution d'agent appartenant à un autre compte par le biais d'une politique basée sur les ressources, les CloudWatch métriques et le quota d'utilisation du quota limite pour l'invocation sont attribués au compte du propriétaire de la ressource. Le propriétaire de la ressource est le compte propriétaire de l'environnement d'exécution de l'agent. Vous pouvez également consulter les indicateurs pris en compte dans votre quota dans la console [Service Quotas](https://console.aws.amazon.com/servicequotas/home/services/bedrock-agentcore/quotas).