Fonctionnement de la mémoire des agents IA et test via API

TL;DR

Les agents IA échouent non pas par manque d'intelligence, mais parce qu'ils oublient. Comprendre les quatre types de mémoire des agents, comment elles sont stockées et comment elles affectent le comportement de l'API vous permet de construire des agents plus fiables et de détecter les bugs avant qu'ils n'atteignent la production.

Essayez Apidog dès aujourd'hui

Introduction

Voici le vilain secret de la plupart des échecs des agents IA : le modèle va bien. C'est la couche de mémoire qui est défectueuse.

Un agent qui ne se souvient pas de ce qui s'est passé il y a trois tours, qui perd le contexte utilisateur entre les sessions, ou qui se contredit en pleine tâche n'est pas en train d'halluciner à cause de la qualité du modèle. Il échoue parce que l'architecture de la mémoire n'a pas été conçue avec soin ou n'a pas été testée du tout.

Hippo, un système de mémoire d'agent open-source qui a récemment fait le buzz, adopte une approche biologiquement inspirée : il modélise la mémoire à court terme, à long terme et épisodique séparément, de la même manière que la mémoire humaine fonctionne. Ce projet a mis en lumière une lacune réelle : la plupart des développeurs construisent la mémoire des agents comme une réflexion après coup et ne découvrent qu'elle est défectueuse qu'en production.

💡 Les scénarios de test d'Apidog vous permettent de tester des conversations d'agents avec état et à plusieurs tours avant leur mise en ligne. Vous pouvez vérifier que l'état de la session est transféré entre les appels d'API, affirmer la structure du contexte et simuler des défaillances de mémoire avec Smart Mock. Cette couche de test est le sujet de la seconde moitié de cet article. Pour l'instant, commençons par ce qui se passe réellement à l'intérieur de la mémoire de l'agent. Consultez [internal: api-testing-tutorial] pour une introduction à l'approche de test plus large.

Qu'est-ce que la mémoire d'un agent IA ?

La mémoire d'agent est tout mécanisme permettant à un système d'IA d'accéder ou de conserver des informations au-delà de l'entrée actuelle. Sans elle, chaque appel d'API est sans état : le modèle reçoit une invite, renvoie une réponse et ne se souvient de rien.

Quatre types de mémoire distincts servent des objectifs différents.

Les quatre types de mémoire d'agent

Mémoire de travail

La mémoire de travail est le contexte actif de l'agent : tout ce qui se trouve dans l'invite actuelle. Pour la plupart des agents basés sur des LLM, il s'agit de la fenêtre contextuelle. GPT-4o a une fenêtre contextuelle de 128K jetons. Claude 3.5 Sonnet supporte 200K. Gemini 1.5 Pro supporte 1M.

La mémoire de travail est rapide et précise, mais coûteuse (vous payez par jeton) et limitée. Une fois la limite atteinte, le contexte le plus ancien est discrètement supprimé. C'est la source la plus courante de bugs d'agent dans les tâches de longue durée.

Mémoire épisodique

La mémoire épisodique stocke ce qui s'est passé : un journal des interactions, des décisions et des observations passées. Considérez-la comme le journal de l'agent.

En pratique, il s'agit généralement d'une base de données vectorielle (Chroma, Pinecone, Qdrant) ou d'un journal d'événements structuré. L'agent récupère les épisodes passés pertinents via une recherche sémantique avant de générer une réponse. L'approche d'Hippo stocke les séquences d'interaction avec des horodatages et des poids de dégradation, de sorte que les interactions récentes bénéficient d'une priorité de récupération plus élevée.

Mémoire sémantique

La mémoire sémantique stocke ce que l'agent sait : des faits, des connaissances spécifiques au domaine, les préférences de l'utilisateur et des connaissances stables sur le monde. Contrairement à la mémoire épisodique, elle n'est pas ordonnée dans le temps.

Celle-ci peut être préchargée (une invite système avec des données de profil utilisateur), construite dynamiquement (faits extraits de conversations passées et stockés dans un graphe de connaissances) ou obtenue de sources externes (RAG contre un magasin de documents).

Mémoire procédurale

La mémoire procédurale stocke comment faire les choses : des séquences d'actions, des modèles d'utilisation d'outils et des compétences que l'agent a apprises. C'est la plus difficile à construire et elle est souvent ignorée dans les systèmes de production.

En pratique, elle apparaît sous forme d'exemples "few-shot" intégrés dans l'invite système, ou comme une bibliothèque de plans d'action stockés que l'agent peut récupérer et adapter.

Comment la mémoire est stockée dans les systèmes réels

Les quatre types correspondent rarement proprement à quatre magasins distincts. Les configurations réelles ressemblent davantage à ceci :

• Fenêtre contextuelle (de travail) : tout ce qui se trouve dans l'invite active. Gérée par le framework de l'agent. Expire à la fin de la conversation.
• Magasin de vecteurs externe (épisodique + sémantique) : Chroma, Pinecone ou Qdrant stocke les embeddings des interactions passées et des blocs de connaissances. L'agent interroge cela à chaque tour et injecte les blocs pertinents dans l'invite.
• Base de données structurée (sémantique + procédurale) : PostgreSQL ou SQLite pour les préférences utilisateur, l'état du compte ou les modèles d'actions appris. Interrogée via des appels d'outils.
• Cache en mémoire (débordement de travail) : Redis ou un simple dict pour un accès rapide au contexte récent qui n'a pas besoin de recherche d'embedding.

Hippo modélise spécifiquement son système de mémoire à trois niveaux avec une logique de transfert explicite : les entrées de mémoire de travail qui n'ont pas été accédées récemment sont consolidées en mémoire épisodique, qui est finalement résumée en mémoire sémantique. Cela reflète la façon dont la consolidation de la mémoire humaine fonctionne pendant le sommeil (le projet dispose même d'une commande "sleep" pour déclencher la consolidation).

Comment la mémoire d'agent affecte le comportement de l'API

Si vous construisez ou consommez une API d'agent, la mémoire façonne directement l'apparence de vos appels d'API et ce qui peut mal tourner.

• ID de session : la plupart des API d'agents utilisent un ID de session ou de thread pour corréler la mémoire entre les appels. L'API OpenAI Assistants utilise thread_id. Un ID de thread abandonné ou réutilisé entraîne la perte de contexte par l'agent ou le mélange des sessions de deux utilisateurs.
• Taille du contexte dans les charges utiles des requêtes : les agents qui injectent de la mémoire dans les invites produisent des corps de requête plus volumineux au fil du temps. Une conversation d'agent qui commence à 2 Ko peut atteindre 40 Ko après 20 tours. Si votre client HTTP a une limite de taille de charge utile, les requêtes échouent silencieusement.
• Latence de récupération : les recherches dans les magasins de vecteurs ajoutent 50 à 200 ms par tour. Si vous effectuez des assertions sur le temps de réponse de l'API, la récupération de la mémoire est un véritable contributeur.
• État incohérent après les échecs : si l'appel d'outil d'un agent échoue en cours de tâche, le journal épisodique peut enregistrer une action partielle. Le tour suivant démarre à partir d'un état corrompu. Les bons agents sauvegardent l'état avant et après l'utilisation d'un outil.

Comment tester la mémoire d'un agent via API avec Apidog

Testez les API d'agents avec état nécessite plus qu'une simple assertion de requête unique. Vous devez vérifier que le contexte est transféré sur plusieurs appels, que les réponses basées sur la mémoire changent comme prévu, et que le système se dégrade gracieusement lorsque la mémoire est indisponible.

Les scénarios de test d'Apidog gèrent précisément cela. Voici comment en configurer un pour une API d'agent.

Test 1 : Transfert de contexte

Créez un scénario avec trois étapes séquentielles :

1. POST /agent/chat avec un message introduisant un fait ("Mon projet utilise PostgreSQL 16")
2. POST /agent/chat avec un suivi qui nécessite de rappeler ce fait ("Pour quelle base de données devrais-je optimiser ?")
3. Affirmez sur la réponse de l'étape 2 : response.message.content devrait contenir "PostgreSQL"

Si la couche de mémoire de l'agent fonctionne, l'étape 2 récupère le fait de la mémoire épisodique ou sémantique et l'utilise dans la réponse. Sinon, vous obtenez une réponse générique.

Test 2 : Isolation de session

Exécutez la même séquence en deux étapes deux fois avec des valeurs de session_id différentes. Affirmez que la réponse de la deuxième session ne contient aucun contexte de la première session. Cela détecte les bugs de mémoire partagée, fréquents dans les déploiements d'agents multi-locataires.

Test 3 : Dégradation en cas de défaillance de la mémoire

Utilisez Smart Mock d'Apidog pour simuler une défaillance du backend de mémoire. Configurez le mock pour qu'il renvoie un 503 sur le point de terminaison de recherche du magasin de vecteurs. Exécutez ensuite votre conversation d'agent et affirmez que :

• L'agent répond sans planter
• La réponse inclut une solution de repli gracieuse ("Je n'ai pas assez de contexte pour répondre à cela")
• La session peut reprendre une fois le mock supprimé

Test 4 : Débordement de la fenêtre contextuelle

Envoyez plus de 30 messages rapides en séquence pour pousser la mémoire de travail au-delà de la limite de contexte. Affirmez que :

• L'agent ne génère pas d'erreur context_length_exceeded (il devrait tronquer gracieusement)
• La réponse au 30e tour répond toujours correctement en utilisant la récupération épisodique
• Le nombre de jetons dans response.usage reste dans la plage attendue

Vous pouvez exécuter ces quatre tests en un seul scénario de test dans Apidog, en les chaînant séquentiellement avec des variables partagées pour les ID de session et les données de réponse. Consultez [internal: how-to-build-tiny-llm-from-scratch] pour des informations sur la raison pour laquelle les fenêtres contextuelles fonctionnent comme elles le font au niveau du modèle.

Modes de défaillance courants de la mémoire

• Troncation silencieuse du contexte : la fenêtre contextuelle se remplit et les messages plus anciens disparaissent sans avertissement. L'agent répond sur la base d'un historique incomplet. Détectez cela en affirmant sur response.usage.prompt_tokens et en vérifiant qu'il reste en dessous de la limite de contexte de votre modèle.
• Fuite de session : les sessions de deux utilisateurs partagent un espace de noms de mémoire. Détectez cela avec des tests d'isolation de session.
• Mémoire sémantique obsolète : des connaissances stockées il y a des semaines contredisent des faits actuels. L'agent donne avec confiance des informations erronées. Détectez cela en incluant une assertion de "date actuelle" dans votre test : si l'agent cite un prix ou un numéro de version, affirmez qu'il correspond à la valeur que vous avez chargée dans le contexte de test.
• Dérive d'embedding : les magasins de vecteurs construits avec un modèle d'embedding se cassent lorsque vous passez à un autre. Tous les documents récupérés deviennent sémantiquement erronés. Non directement testable via l'API, mais vous pouvez ajouter une assertion qui vérifie si le contexte récupéré est sémantiquement lié à la requête.
• Injection de mémoire / injection d'invite : une entrée utilisateur malveillante qui manipule ce qui est stocké et récupéré. Incluez des entrées adverses dans votre suite de tests : stockez une "préférence utilisateur" qui contient une surcharge d'invite système et vérifiez que l'agent l'ignore. Consultez [internal: rest-api-best-practices] pour des conseils plus larges sur les tests de sécurité API.

Conclusion

La mémoire d'agent est la différence entre un assistant qui semble intelligent et un qui semble amnésique. Les quatre types, de travail, épisodique, sémantique et procédurale, ont chacun un rôle distinct. Comprendre comment elles sont stockées et récupérées dans les systèmes réels vous indique exactement où les bugs peuvent se cacher et ce qu'il faut affirmer dans vos tests d'API.

Des outils comme Hippo montrent que le domaine s'oriente vers une architecture de mémoire basée sur des principes. Quel que soit le système de mémoire sur lequel vous construisez, les scénarios de test d'Apidog vous offrent la couche de test pour vérifier qu'il se comporte comme vous l'attendez, en particulier les cas de défaillance qui n'apparaissent qu'à grande échelle.

FAQ

Quelle est la manière la plus simple d'ajouter de la mémoire à un agent ?

L'approche la plus simple est une fenêtre glissante sur l'historique des conversations : conserver les N derniers tours dans l'invite. Ce n'est pas une mémoire épisodique, mais cela fonctionne pour des tâches courtes. Pour les agents de plus longue durée, ajoutez un magasin de vecteurs et une récupération sémantique.

Comment l'API OpenAI Assistants gère-t-elle la mémoire ?

L'API Assistants gère un objet thread qui stocke l'historique de la conversation côté serveur. Vous pouvez également attacher des outils de recherche de fichiers et d'interprétation de code qui donnent à l'agent accès à des connaissances externes. La gestion de la mémoire est abstraite, ce qui est pratique mais rend le débogage plus difficile.

Quelle est la meilleure base de données vectorielles pour la mémoire d'agent ?

Pour le développement local : Chroma (aucune infrastructure nécessaire). Pour la production : Qdrant ou Pinecone selon que vous ayez besoin d'une solution auto-hébergée ou gérée. La bibliothèque Hippo prend en charge les backends de stockage enfichables. Consultez [internal: claude-code] pour voir comment Claude Code utilise sa propre couche de mémoire.

Comment empêcher les agents d'halluciner sur des interactions passées ?

Stockez les journaux d'interaction dans un format structuré avec des métadonnées (horodatage, confiance, source). Lors de la récupération du contexte passé, incluez les métadonnées dans l'invite : "Selon notre conversation du [date], vous avez mentionné X." La citation explicite réduit les hallucinations confiantes.

Puis-je tester la mémoire d'un agent sans agent en cours d'exécution ?

Oui. Utilisez Smart Mock d'Apidog pour simuler les réponses de l'API de l'agent, y compris celles basées sur la mémoire. Définissez des réponses simulées qui changent en fonction de l'ID de session ou du contenu du corps de la requête. Cela vous permet de tester la gestion du comportement de la mémoire par votre couche frontend ou d'intégration sans avoir d'agent en direct.

Combien coûte le stockage vectoriel en production ?

Le niveau gratuit de Pinecone prend en charge 1 index avec 100K vecteurs. À grande échelle, Pinecone facture environ 0,096 $/heure pour un pod p1.x1 (1M de vecteurs à 768 dimensions). Qdrant auto-hébergé est gratuit. Pour la plupart des agents, le coût le plus important est la génération d'embeddings, pas le stockage. Consultez [internal: what-is-mcp-server] pour savoir comment les intégrations de serveurs MCP interagissent avec les systèmes de mémoire d'agent.

Quelle est la différence entre RAG et la mémoire d'agent ?

RAG (génération augmentée par récupération) récupère des documents pertinents au moment de la requête à partir d'une base de connaissances fixe. La mémoire d'agent est dynamique : elle grandit et change au fur et à mesure que l'agent interagit. Un système RAG répond "que disent les documents à propos de X ?" Un système de mémoire d'agent répond "que sais-je de cet utilisateur et qu'ai-je fait avec lui ?"