Bedrock AgentCore en pratique : Terraform, LangGraph et les pièges rencontrés

Héberger un agent IA sur AWS manuellement signifie devoir résoudre soi-même les problèmes d’isolation des sessions, d’accès aux outils, de mémoire et d’authentification. Amazon Bedrock AgentCore est la version gérée de ce même système, disponible depuis octobre 2025. Une façon pratique d’évaluer une telle plateforme consiste à cesser de lire à son sujet pour créer quelque chose de concret ; un petit agent de tri DevOps en lecture seule a servi à cette fin ici. Il a été déployé à l’aide de Terraform plutôt que du wizard CLI d’AWS, et écrit avec LangGraph plutôt que le SDK Strands d’AWS. Ces choix étaient intentionnels, car l’objectif était de découvrir ce qui fonctionne en dehors des solutions préconisées.

Qu’est-ce que AgentCore ?

AgentCore est un ensemble d’éléments gérés qui couvrent les aspects complexes et essentiels au fonctionnement d’un agent en production, tout en permettant à n’importe quel framework d’agent existant de rester en place. La promesse de compatibilité avec n’importe quel framework est la principale caractéristique, et elle est pour l’essentiel tenue : LangGraph, LangChain, CrewAI, Strands ainsi que des appels API classiques sont tous acceptés.

Ces éléments et leur fonction respective :

• Runtime héberge le code de l’agent et fournit à chaque session sa propre microVM isolée. Il passe à zéro lorsqu’il n’y a pas d’activité et est facturé par seconde en temps de fonctionnement.
• Gateway transforme les fonctions Lambda ou API existantes en outils compatibles avec MCP que l’agent peut appeler, ce qui évite la nécessité d’un serveur MCP écrit manuellement.
• Memory stocke l’historique des conversations sous forme d’événements à court terme et peut, si nécessaire, extraire des connaissances sémantiques à long terme entre les sessions.

L’identité couvre deux directions d’authentification : qui peut appeler l’agent, et ce que l’agent peut faire au nom d’un utilisateur, y compris des services tiers tels que Slack ou GitHub.

L’observabilité envoie des traces OpenTelemetry à CloudWatch afin de conserver un historique de ce que l’agent a fait et pourquoi.

Un outil de navigateur et un outil d’interpréteur de code servent les agents qui doivent agir sur le web ou exécuter du code arbitraire.

Une annonce lors du AWS Summit de juin 2026 a ajouté une couche Harness ainsi qu’une recherche web native. Ces fonctionnalités sont encore trop récentes pour que les infrastructures critiques s’y fient pour l’instant.

L’onboarding a déjà été réimaginé une fois. L’outil CLI Starter Toolkit original est désormais obsolète, remplacé par un package npm basé sur CDK nommé @aws/agentcore. Un tutoriel qui montre comment configurer et lancer agentcore en étapes distinctes décrit l’ancien processus. Ces détails sont importants car ils indiquent le rythme des changements : neuf mois après la disponibilité générale, le parcours d’introduction a déjà été modifié, ce qui signifie que tout ce qui est écrit sur le produit a une durée de validité limitée.

Le projet de test

L’agent répond à des questions telles que savoir s’il y a des alertes CloudWatch activées ou quel est l’état d’une instance EC2 spécifique. Il dispose de deux outils réels en lecture seule, de sorte que rien de ce qu’il peut utiliser ne permet de modifier l’infrastructure, mais uniquement de l’observer. Il se souvient des conversations au fil des échanges, et chaque transition entre composants est authentifiée.

LangGraph a été choisi plutôt que Strands parce que Strands est le framework propriétaire d’AWS et permet de suivre le parcours le plus fluide à travers tous les exemples officiels. Utiliser un autre outil constituait la véritable épreuve de l’affirmation selon laquelle n’importe quel framework conviendrait, et cela correspondait aux outils déjà disponibles. Terraform a été choisi plutôt que la CLI pour une raison similaire : l’assistant est conçu pour démarrer rapidement une démonstration, et l’objectif ici était de voir chaque relation de confiance IAM ainsi que chaque connexion entre composants, plutôt que de les générer de manière invisible. Cette visibilité s’est avérée plus importante que prévu.

L’architecture repose sur un conteneur en temps de exécution qui lance l’agent LangGraph, lequel communique avec une passerelle exposant deux outils basés sur Lambda via MCP. AgentCore Memory stocke la conversation, tandis que Cognito délivre des tokens machine-à-machine pour chaque étape du processus.

Cliquez avant d’écrire des scripts

Avant même que du Terraform ne soit écrit, la version console de la configuration avait été testée une fois, principalement pour voir ce qui était automatisé. Cette habitude vaut la peine d’être conservée, même lorsque c’est Terraform qui gère le déploiement réel, car il est bien plus facile de lire les fichiers d’infrastructure après avoir vu les formulaires qu’ils remplissent.

Le registre de conteneurs mérite une étape manuelle, quel que soit l’outil utilisé pour le reste, car c’est la seule étape que Terraform ne peut pas effectuer. Créer le répertoire se fait en une seule étape depuis l’interface de console. Cependant, l’image doit être transférée d’une autre manière, puisque la console ne dispose d’aucun bouton permettant de créer un Dockerfile. Cela s’effectue dans une terminal à l’aide de la commande docker buildx build pour la plateforme linux/arm64, suivie d’une action de push. Nommer manuellement la plateforme est essentiel ; si l’on omet cette étape, l’image se compile sans problème, mais est rejetée silencieusement lorsque Runtime tente de la lancer, car Runtime ne fonctionne que sur Graviton.

Lorsque l’image est transférée, la console affiche son URI exact. Cette chaîne de caractères constitue l’unique élément d’état qui doit être transmis de la manipulation manuelle à ce que Terraform connaît, que ce soit dans un fichier tfvars ou dans le champ d’image de conteneur de Runtime pour ceux qui restent sur la console.

Les onglets Memory, Gateway et Runtime de AgentCore se trouvent dans leur propre section de la console Bedrock. Chacun correspond à un formulaire avec les mêmes champs définis par Terraform, ce qui est logique car Terraform utilise la même API en sous-jacent.

• Memory demande un nom ainsi que la durée pendant laquelle les événements à court terme sont conservés.
• Gateway demande un protocole, un rôle d’exécution et une méthode d’authentification des appels. Le problème lié aux identifiants Cognito audience-versus-client-id décrit ci-dessous apparaît ici sous forme d’un menu déroulant qui impose un choix.
• Runtime demande l’URI du registre, un rôle ainsi que la même configuration d’autorisation que Gateway.

Rien de tout cela n’est difficile une fois que les formulaires sont devant vous. Terraform reste néanmoins le meilleur choix pour tout projet destiné à durer, car parcourir sept formulaires répartis sur trois sections de console n’est pas un processus de déploiement que quiconque souhaite répéter ou confier à un collègue.

Where it bit

Images must be ARM64

Runtime is Graviton-only, with no exceptions. A plain docker build on most laptops yields an amd64 image that is silently refused at deploy time. Every build needs the buildx command with the arm64 platform flag. A comment directly above the FROM line in the Dockerfile is a cheap safeguard, because it will be forgotten otherwise.

The Gateway's Lambda contract

Divers articles de blog montrent un événement Lambda enveloppé dans une enveloppe contenant un toolName et des paramètres. L’événement réel correspond aux propriétés d’entrée de l’outil sous forme de dictionnaire plat. Le vrai nom de l’outil est indiqué via context.client_context.custom, sous la clé bedrockAgentCoreToolName, précédé du nom de la cible du gateway et séparé par trois underscores. Cette disparité n’a été révélée qu’en consultant directement la documentation officielle de Lambda d’AWS plutôt que de se fier à des résumés indirects. Une grande partie des informations circulant sur ce produit provient de la période de bêta ou est simplement fausse.

Les tokens Cognito ne contiennent pas de champ aud

Celui-ci a nécessité beaucoup de temps pour être compris. Lorsque Cognito est utilisé pour l’authentification machine à machine, via un accord client_credentials sans connexion humaine, Cognito délivre un jeton d’accès et non un jeton d’identité. Les jetons d’accès ne contiennent jamais de champ aud. Seuls les jetons d’identité le font, or un flux M2M ne dispose pas de jeton d’identité car il n’y a pas d’utilisateur à qui en délivrer un. Il faut configurer l’autoriseur JWT d’AgentCore pour vérifier allowed_audience contre un tel jeton, ce qui entraîne une réponse 403 sans raison évidente. La solution réside dans l’option allowed_clients, qui vérifie le champ client_id que les jetons d’accès Cognito contiennent bien.

boto3 ne peut pas appeler un Runtime protégé par JWT

C’était la plus grande surprise : il ne s’agit pas d’une solution de contournement, mais bien d’une mention dans la référence API d’AWS elle-même. Si l’agent utilise une authentification entrante de type OAuth, InvokeAgentRuntime ne peut absolument pas être appelé via le SDK AWS. La requête est plutôt une demande HTTPS brute contenant un jeton porteur dans l’en-tête Authorization, envoyée vers une URL construite manuellement, avec l’ARN du runtime encodé en pourcentage dans le chemin. Chaque exemple boto3 part du principe que les chemins IAM et SigV4 par défaut sont utilisés. Une fois qu’un custom_jwt_authorizer a été configuré, ce qui est nécessaire pour tout élément ne relevant pas exclusivement de l’environnement interne, toute cette catégorie d’exemples cesse d’être applicable.

Conflit de package Python

Le paquet Python mcp a publié une version majeure 2.0.0 qui renomme les modules internes, tandis que langchain-mcp-adapters n’a pas suivi. Il déclare une compatibilité avec mcp à partir de la version 1.24.0 sans limite supérieure, ce qui fait que l’instruction pip install seule entraîne désormais une association défectueuse. Au moins, cela provoque une erreur d’import clairement visible, et non un bug subtil. Le projet de test fixe la version mcp à 1.29.0. Vérifiez si cette fixation reste nécessaire, car des correctifs discrets peuvent transformer une solution en surcharge inutile.

Le déploiement va au-delà d’une simple application

Le resource Runtime a besoin d’une image de conteneur déjà présente dans le registre, et Terraform ne peut pas construire et publier une image lors de son propre processus d’application. La vraie séquence consiste à créer uniquement le répertoire du registre, à construire et publier l’image en dehors de Terraform, puis à appliquer le reste. Les ingénieurs travaillant sur des stacks AgentCore bien plus volumineuses ont intégré CodeBuild dans le graphe Terraform à l’aide de null_resource pour combler cette lacune. C’est une étape logique suivante, et cela montre que ce problème est répandu et non le fruit d’une erreur personnelle.

L’état de la conversation doit se trouver en un seul endroit

Ce n’est pas une erreur mais un choix structurel : l’agent refuse délibérément d’utiliser le checkpointer propre à LangGraph pour gérer l’état de la conversation, bien que la plupart des tutoriels de LangGraph le préfèrent par défaut. Les sessions en temps réel peuvent être réduites à zéro et transmettre une nouvelle microVM entre les appels, ce qui fait disparaître tout ce qui n’est stocké que dans la mémoire du processus. AgentCore Memory constitue donc la partie persistante de cette frontière. L’exécution d’un checkpointer local en parallèle de Memory crée deux enregistrements concurrents de la même conversation, qui finiront tôt ou tard par être en désaccord quant à ce qui a été dit. Il faut donc en choisir un. Memory est le choix le plus judicieux, car il survit à un démarrage à froid.

Quel en est le coût ?

Le tarif est basé sur la consommation, sans minimum, ce qui convient bien à un système qui passe la majeure partie de son temps à attendre une réponse d’un LLM. En conséquence, la facture correspond à la somme de plusieurs éléments de petite taille, mesurés séparément, et non à un seul montant. À l’heure où cet texte est écrit :

• Les frais de fonctionnement s’élèvent à environ 9 cents par vCPU-heure et à peu près 1 cent par GB-heure, mesurés au second avec un minimum d’une seconde ; ainsi, une question de trois secondes coûte trois secondes et non une minute arrondie.
• Les frais liés au gateway sont d’environ 0,5 cent par mille appels MCP.
• La mémoire est facturée à 0,25 cent pour 1 000 événements stockés et à 0,5 cent pour 1 000 événements récupérés.
• L’utilisation de l’identité via Runtime ou Gateway, plutôt que par une appel direct, n’entraîne aucun frais, ce qui s’applique à presque toute la configuration.

Rien de tout cela ne prend en compte les appels au modèle, qui représentent, pour toute utilisation allant au-delà d’un test simple, la plus grande part des coûts et sur lesquels AgentCore n’a aucun impact. Il s’agit simplement du tarif que Bedrock facture pour le modèle choisi. Les nouveaux comptes reçoivent deux cents dollars en crédits AgentCore, suffisants pour développer et modifier un projet de ce type à plusieurs reprises. Il convient de consulter la page des prix officielle avant de se fier à quelque chiffre que ce soit, car les tarifs ont déjà changé à plusieurs reprises depuis la mise à disposition générale et risquent de le faire à nouveau.

Plateforme gérée ou hébergement personnalisé

Une pile d’hébergement d’agent construite manuellement offre une comparaison utile, et la conclusion honnête a deux aspects. AgentCore assure l’isolation des sessions, un gateway MCP géré, une mémoire fiable ainsi qu’un modèle d’authentification conçus pour fonctionner ensemble, ce qui est plus rapide que de concevoir manuellement les politiques de confiance IAM ; des heures ont été consacrées précisément à ces politiques ici. Cela représente une grande quantité de travail d’infrastructure non différencié qui est ainsi allégé. Pour toute personne dont le travail consiste à créer l’agent et non la plateforme d’hébergement qui le soutient, cet échange en vaut probablement la peine.

Ce que la plateforme ne fournit pas, c’est un jugement sur ce qu’un agent devrait être autorisé à faire, combien cela coûterait à grande échelle, ou si un cadre quelconque signifie nécessairement que c’est le chemin le mieux documenté fourni par AWS lui-même. La stabilité fait également défaut. L’interface en ligne de commande a été reconstruite une fois, et au moins trois cas ont été identifiés où la documentation d’AWS était en désaccord avec l’API réelle, de manière mineure mais significative. Rien de tout cela ne rend le produit mauvais. Cela décrit simplement un service géré encore jeune qui évolue rapidement, ce dont il vaut mieux être conscient avant de commencer plutôt que de l découvrir au milieu d’un déploiement.

Tout a été réellement construit, et non seulement décrit. Chaque ressource est gérée par Terraform, l’agent est complet, les outils Lambda existent, et le jeu de tests ne nécessite pas de identifiants AWS ; par conséquent, tout ce qui pouvait être vérifié l’a été en premier. Pour une configuration similaire, les deux points les plus susceptibles de poser des problèmes sont le paramètre de plateforme ARM64 pour l’image, ainsi que la valeur allowed_clients dans la configuration de l’autoriseur Cognito.