MicroVM AWS Lambda

Utilisez les MicroVM AWS Lambda pour exécuter les outils de votre agent dans votre compte AWS. OpenAI exécute le harnais de l’agent. Chaque MicroVM exécute codex exec-server et héberge les fichiers de l’espace de travail de la session.

Par défaut, les exemples utilisent une MicroVM pour un seul tour. Préparez une image réutilisable, puis lancez une MicroVM à partir de cette image depuis votre application ou via un webhook OpenAI. Les deux méthodes utilisent la même image et les mêmes identifiants. Pour chaque session, confiez le provisionnement à un seul responsable.

Essayez les exemples AWS du Cookbook pour les bacs à sable gérés par l’application ou par webhook.

Fonctionnement

Avec la méthode par webhook, votre application crée une session auto-hébergée et lui envoie une entrée. Lorsque la session a besoin d’un exécuteur, OpenAI envoie l’événement agent.session.action_required avec une action environment_connection. API Gateway transmet le webhook à une fonction Lambda qui sert de lanceur. Cette fonction vérifie la signature, contrôle la session en cours, puis lance ou réactive une MicroVM.

Le hook /run de la MicroVM récupère une clé d’environnement auprès de Secrets Manager et démarre l’exécuteur. L’exécuteur ouvre une connexion sortante vers OpenAI, ce qui permet de traiter l’entrée en attente. Votre application suit le flux d’événements de la session, télécharge les fichiers de sortie et met fin à la MicroVM après le dernier tour.

Avant de commencer

Préparez les ressources suivantes :

• Accès à AWS : prévoyez un compte ayant accès aux MicroVM Lambda, une version de l’AWS CLI qui inclut lambda-microvms et les autorisations nécessaires pour créer des images et exécuter des MicroVM. Suivez le guide de démarrage d’AWS pour créer le compartiment S3 destiné aux artefacts et le rôle IAM de création d’images.
• Clé d’application : utilisez OPENAI_API_KEY pour créer des sessions et envoyer des entrées.
• Clé d’environnement (OPENAI_EXECUTOR_API_KEY) : créez une clé d’environnement distincte, rattachée à la même organisation, au même projet et au même utilisateur ou compte de service que la clé d’application. Stockez sa valeur dans Secrets Manager, par exemple dans un secret nommé codex/agents-api/executor. Le hook /run la transmet à Codex dans la variable CODEX_API_KEY.
• Rôle d’exécution de la MicroVM : autorisez ce rôle à lire uniquement le secret contenant la clé d’environnement. Ajoutez l’autorisation de déchiffrement si vous utilisez une clé KMS gérée par le client. Pour configurer le rôle, consultez la documentation AWS sur la sécurité et les autorisations.

Conservez la clé d’application et le secret de signature du webhook en dehors de la MicroVM. Le lanceur du webhook a besoin de ces identifiants dans son propre secret Secrets Manager. La VM reçoit uniquement l’ARN du secret contenant sa clé d’environnement.

Préparation d’une image réutilisable

Créez une image qui contient la CLI de Codex, les dépendances des outils, un répertoire de travail tel que /workspace et un serveur HTTP pour les hooks de cycle de vie AWS.

Dans les exemples, les hooks suivants sont accessibles sous /aws/lambda-microvms/runtime/v1 :

Regroupez le Dockerfile et le serveur de hooks dans un artefact S3, puis créez une image versionnée, par exemple codex-executor. Dans la configuration de l’image, activez les six hooks et indiquez le port d’écoute de votre serveur comme port des hooks. Excluez de l’instantané de l’image les identifiants de session, les informations d’authentification et les connexions actives de l’exécuteur. Pour créer l’image et configurer les hooks, consultez la documentation AWS sur les images de MicroVM.

Au lancement, votre application ou votre lanceur sérialise les valeurs suivantes au format JSON dans runHookPayload :

Le hook /run analyse cette chaîne dans le corps de la requête AWS, récupère la clé, définit CODEX_API_KEY dans l’environnement du processus enfant et démarre l’exécuteur. Faites en sorte que le hook rende la main dès le démarrage du processus. Si vous attendez la fin du tour de l’agent, le délai d’exécution du hook risque d’expirer.

Autorisez les connexions sortantes nécessaires à l’exécuteur ainsi que l’accès à Secrets Manager. Configurez un connecteur de sortie AWS si vous utilisez des ressources privées ou si le réseau est soumis à des restrictions. Pour télécharger des fichiers, ajoutez une route à votre serveur et appelez-la via le point de terminaison HTTP de la MicroVM avec un jeton d’authentification AWS dont la portée se limite au port du serveur.

Lancement de la MicroVM

Choisissez de gérer le provisionnement depuis l’application ou par webhook. Dans les deux cas, gardez le flux d’événements de la session ouvert pendant la connexion et l’envoi de l’entrée, puis jusqu’à la fin du tour.

Provisionnement géré par l’application

1. Créez une session auto-hébergée dont le répertoire de travail correspond à celui de l’image, puis ouvrez son flux d’événements.
2. Appelez l’opération AWS RunMicrovm avec l’ARN et la version de l’image, le rôle d’exécution, les connecteurs réseau et runHookPayload. Enregistrez le microvmId renvoyé avec l’identifiant de session.
3. Attendez l’événement agent.session.environment.connected, puis envoyez l’entrée et suivez le tour jusqu’à son résultat.
4. Récupérez les fichiers de sortie et arrêtez la MicroVM.

Provisionnement géré par webhook

Utilisez une API HTTP d’API Gateway et une fonction Lambda comme lanceur. Votre application crée la session, ouvre son flux et envoie l’entrée. Lorsque la session a besoin d’une connexion, le webhook déclenche le lancement ou la réactivation de la MicroVM.

1. Déployez une route POST /webhook qui appelle le lanceur. Accordez au lanceur les autorisations lambda:RunMicrovm, lambda:GetMicrovm, lambda:ResumeMicrovm et lambda:TerminateMicrovm pour l’image sélectionnée. Le lanceur doit également pouvoir lire ses identifiants, transmettre le rôle d’exécution de la MicroVM et utiliser les connecteurs réseau configurés.
2. Enregistrez le point de terminaison pour les événements agent.session.action_required et agent.session.failed. Stockez le secret de signature du point de terminaison avec la clé d’application du lanceur.
3. Vérifiez la signature du webhook à partir du corps brut de la requête avant d’accéder aux sessions ou de lancer des ressources de calcul. Récupérez la session en cours et vérifiez qu’elle relève de ce gestionnaire, par exemple en comparant l’agent de la session à l’agent dédié enregistré.
4. Si l’action environment_connection est toujours en attente, vérifiez l’état de la VM enregistrée avec GetMicrovm. Réactivez une VM à l’état SUSPENDED avec ResumeMicrovm. Si elle est à l’état PENDING ou RUNNING, attendez qu’elle se connecte. Appelez RunMicrovm uniquement si aucune VM n’est enregistrée. Enregistrez son identifiant dans les métadonnées de la session. Si l’enregistrement échoue, mettez fin à la VM que vous venez de lancer.
5. Si la session est toujours à l’état failed, mettez fin à la MicroVM enregistrée pour cette session. Ignorez les sessions supprimées, les actions résolues et les événements qui relèvent d’un autre gestionnaire.

Si l’exécuteur se connecte avant l’expiration du délai de connexion, l’entrée en attente est traitée sans que vous ayez à la renvoyer.

Dans un prototype, vous pouvez lancer la MicroVM de manière synchrone et stocker son identifiant dans les métadonnées de la session. Avant la mise en production, enregistrez de manière persistante quel gestionnaire est responsable du lancement, rendez l’opération idempotente et placez les tâches de provisionnement dans une file d’attente. Les métadonnées seules n’empêchent pas les lancements en double. Un lancement lent peut dépasser le délai de réponse du webhook.

Arrêt de la MicroVM

Dans le flux d’événements de la session, attendez l’événement agent.session.turn.completed, agent.session.turn.failed ou agent.session.turn.cancelled de l’agent principal (event.turn.subagent_id vaut null). Les sous-agents partagent la MicroVM : leurs événements de fin de tour ne doivent pas déclencher le nettoyage. Après le dernier tour, récupérez les fichiers nécessaires, appelez TerminateMicrovm et vérifiez que la VM passe à l’état TERMINATED. Effectuez également le nettoyage en cas d’erreur de l’application.

Les résultats des tours sont transmis dans le flux d’événements. Vous ne pouvez pas vous y abonner par webhook. Le webhook agent.session.failed traite les échecs de session, mais ne couvre pas tous les échecs de tour. Ne mettez pas fin à la MicroVM sur la seule base de l’événement agent.session.idle : il peut arriver avant le début du traitement de l’entrée en attente.

Configurez les limites AWS suivantes pour le cas où le nettoyage n’aurait pas lieu :

Pour configurer la durée de vie et le délai d’inactivité, consultez le guide AWS sur l’exécution et l’utilisation des MicroVM.

Supprimez la session séparément. La suppression d’une session ne met pas fin aux ressources de calcul AWS et ne déclenche pas de webhook de suppression. Conservez l’image et le secret contenant la clé d’environnement pour pouvoir les réutiliser. Pour les tours suivants, coordonnez la réutilisation ou le remplacement des ressources de calcul ainsi que la persistance des fichiers en suivant le guide sur le cycle de vie des bacs à sable.

Suspension et reprise entre les tours

Utilisez les fonctions AWS de suspension et de reprise pour conserver le contenu de la mémoire et du disque entre les tours. Attribuez une valeur non nulle à suspendedDurationSeconds. Le stockage de l’instantané est facturé pendant la suspension. maximumDurationInSeconds limite à huit heures la durée cumulée d’exécution et de suspension.

Exécutez l’un ou l’autre des exemples avec --suspend-resume pour écrire dans /workspace/hello.txt, suspendre la VM, puis lire le fichier lors d’un deuxième tour. Dans l’exemple géré par l’application, celle-ci réactive directement la VM. Dans l’exemple géré par webhook, l’application envoie une nouvelle entrée, ce qui amène le lanceur à réactiver la VM enregistrée. Les deux exemples vérifient le contenu du fichier et effectuent le nettoyage après le dernier tour.

Le hook /suspend arrête l’exécuteur. Le hook /resume recharge sa clé et le reconnecte. Ne suspendez la VM qu’une fois l’exécution des outils et des sous-agents terminée. La reprise automatique d’AWS nécessite du trafic entrant sur la VM. Une entrée envoyée à l’API Agents ne suffit pas à la réactiver.

Vérification et surveillance

Testez l’intégration avec un prompt qui demande de créer un petit fichier dans /workspace. Vérifiez que l’exécuteur se connecte, que le tour se termine, que le fichier téléchargé contient le résultat attendu et que la MicroVM passe à l’état TERMINATED après le nettoyage. Un lancement réussi ne suffit pas à valider l’intégration.

Depuis le répertoire de l’exemple AWS, utilisez jq pour lire l’ARN de l’image et la région dans le fichier d’état enregistré lors de la création de l’image. Adaptez le chemin si vous avez utilisé un chemin personnalisé avec --state. Si vous avez renommé le lanceur, remplacez le nom du groupe de journaux :

123456789image_state=application_managed/.local/image.json
region=$(jq -r '.region' "$image_state")
image_arn=$(jq -r '.image_arn' "$image_state")

aws logs tail /aws/lambda/codex-agents-api-webhook --since 10m --region "$region"

aws lambda-microvms list-microvms \
  --image-identifier "$image_arn" --region "$region" \
  --query 'items[].{id:microvmId,state:state}' --output table

Consignez ensemble les identifiants de la session et de la MicroVM pour retracer une exécution. Ne consignez ni les informations d’authentification ni le corps brut des requêtes du webhook.

Dépannage

En cas d’échec de connexion, examinez l’événement agent.session.environment.failed et les journaux de l’exécuteur. Consultez le guide des bacs à sable auto-hébergés pour connaître le contrat commun des exécuteurs.

Références

• Cycle de vie : le guide sur l’exécution et l’utilisation des MicroVM décrit le lancement, la suspension, la reprise et l’arrêt définitif.
• Sécurité : le guide sur la sécurité et les autorisations décrit les rôles IAM, les jetons d’authentification et les contrôles d’accès.