Créer des agents personnalisés avec ADK, MCP et la banque de mémoire

1. Introduction

Pile d'agents modernes

Pour créer un agent d'IA de qualité professionnelle, il faut plus qu'un grand modèle de langage (LLM). Alors qu'un LLM fournit les capacités de raisonnement, un agent robuste doit interagir avec le monde extérieur, gérer l'état de la conversation et mémoriser les préférences des utilisateurs au fil du temps.

Dans cet atelier, vous apprendrez à concevoir et à créer un système agentique complet à l'aide de trois technologies fondamentales :

1. Connectivité (MCP) : pour donner à votre agent l'accès aux outils et données locaux.
2. Orchestration (ADK) : pour gérer la boucle de raisonnement et l'état de l'agent.
3. Mémoire (banque de mémoire) : pour fournir un contexte personnalisé à long terme.

Concepts fondamentaux

Composant	Fonction
Protocole MCP (Model Context Protocol)	Norme universelle qui connecte les modèles d'IA à des systèmes externes (bases de données, systèmes de fichiers, API) sans intégrations personnalisées.
Agent Development Kit (ADK)	Framework qui fournit l'environnement d'exécution pour les agents, en gérant la boucle d'événements, les transitions d'état et l'exécution des outils.
Service de session	Gère la mémoire à court terme. Il préserve le contexte immédiat de la conversation (par exemple, "Qu'est-ce que l'utilisateur vient de demander ?"), mais elle est effacée à la fin de la session.
Vertex AI Memory Bank	Gère la mémoire à long terme. Il conserve les faits et préférences spécifiques à l'utilisateur (par exemple, "L'utilisateur préfère Python") indéfiniment, ce qui permet à l'agent de personnaliser les futures interactions.
Vertex AI Agent Engine	Service d'infrastructure gérée qui héberge à grande échelle la logique et les composants de mémoire de votre agent.

Ce que vous allez faire

Pour illustrer ces concepts, vous allez créer un assistant de conception pour les fêtes. Cet agent sera capable de traiter les demandes de haut niveau des utilisateurs et d'orchestrer de manière autonome les outils Python locaux pour générer du code et des images personnalisés.

Vous passerez par trois étapes :

1. Couche d'outillage : créez un serveur MCP pour exposer les fonctions Python locales à l'IA.
2. Couche d'agent : utilisez ADK pour créer un agent qui planifie et exécute des workflows en plusieurs étapes.
3. Couche de mémoire : intégrez la banque de mémoire pour permettre à l'agent d'apprendre et de mémoriser les préférences de style des utilisateurs.

2. Configurer

Pour alimenter nos agents d'IA, nous avons besoin de deux éléments : un projet Google Cloud pour fournir les bases.

Première partie : Activer le compte de facturation

• Réclamez votre compte de facturation avec un crédit de 5 $, dont vous aurez besoin pour votre déploiement. Assurez-vous d'utiliser votre compte Gmail.

Aucune carte de crédit ni aucun paiement ne sont nécessaires : vous recevrez 5 € de crédits sans frais. Cela prend moins de deux minutes. Il vous suffit de saisir votre nom et d'accepter les crédits.

Deuxième partie : Environnement ouvert

1. 👉 Cliquez sur ce lien pour accéder directement à l'éditeur Cloud Shell.
2. 👉 Si vous êtes invité à autoriser l'accès à un moment donné aujourd'hui, cliquez sur Autoriser pour continuer.
3. 👉 Si le terminal ne s'affiche pas en bas de l'écran, ouvrez-le :
   • Cliquez sur Afficher.
   • Cliquez sur Terminal.
4. 👉💻 Dans le terminal, vérifiez que vous êtes déjà authentifié et que le projet est défini sur votre ID de projet à l'aide de la commande suivante :

   gcloud auth list
   

5. 👉💻 Clonez le projet bootstrap depuis GitHub :

   git clone https://github.com/cuppibla/holiday_workshop
   

6. 👉💻 Exécutez le script de configuration à partir du répertoire du projet.

   cd ~/holiday_workshop
   ./init.sh
   

   ⚠️ Remarque concernant l'ID du projet : Le script suggère un ID de projet par défaut généré de manière aléatoire. Vous pouvez appuyer sur Entrée pour accepter cette valeur par défaut.

   Toutefois, si vous préférez créer un projet spécifique, vous pouvez saisir l'ID de projet souhaité lorsque le script vous y invite.

   Le script gère automatiquement le reste du processus de configuration.
7. 👉💻 Définissez l'ID de projet requis :

   gcloud config set project $(cat ~/project_id.txt) --quiet
   

Troisième partie : Configurer les autorisations

1. 👉💻 Activez les API requises à l'aide de la commande suivante. L'opération peut prendre quelques minutes.

   gcloud services enable \
       cloudresourcemanager.googleapis.com \
       servicenetworking.googleapis.com \
       run.googleapis.com \
       aiplatform.googleapis.com \
       compute.googleapis.com
   

2. 👉💻 Accordez les autorisations nécessaires en exécutant les commandes suivantes dans le terminal :

   . ~/holiday_workshop/set_env.sh
   

Notez qu'un fichier .env a été créé pour vous. Les informations sur votre projet s'affichent.

3. Optimiser la CLI Gemini avec MCP

Le moment "USB-C" pour l'IA

Imaginez que vous deviez souder chaque nouvelle souris à votre carte mère. C'était l'état des outils d'IA jusqu'à récemment. Les développeurs devaient écrire du "code de colle" personnalisé pour connecter les LLM aux bases de données, aux systèmes de fichiers ou aux API.

Saisissez le protocole MCP (Model Context Protocol). Considérez MCP comme le port USB-C des applications d'IA. Il fournit un moyen standardisé de connecter les modèles d'IA aux sources de données et aux outils.

Si vous créez un serveur MCP pour vos outils une seule fois, vous pouvez le brancher sur la CLI Gemini, un IDE ou tout autre client compatible avec MCP sans modifier une seule ligne de code.

Ce que vous allez faire

Dans cet atelier de programmation, vous allez créer un assistant de conception pour les fêtes qui :

1. Se connecte à votre environnement local (outils Studio) à l'aide de MCP.
2. Gère le contexte de la conversation de manière fiable à l'aide de l'Agent Development Kit (ADK).
3. Mémorise vos préférences (par exemple, "Je préfère le code Python") au cours de différentes sessions à l'aide de Vertex AI Memory Bank.

Avertissement : Assurez-vous d'avoir authentifié votre Google Cloud CLI (gcloud auth login) avant d'exécuter les exemples de code.

Créer la logique du serveur

Nous avons préparé l'environnement, mais la logique du serveur est incomplète. Nous devons implémenter les quatre outils spécifiques que notre agent utilisera pour créer notre carte de vœux.

Première partie : Ouvrez le squelette du serveur

Nous allons travailler dans le répertoire 01-MCP-Files-Testing/01-starter.

1. Dans votre terminal Cloud Shell, assurez-vous d'être dans le bon répertoire :

   cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
   

2. Ouvrez le fichier dans l'éditeur Cloud Shell en exécutant la commande suivante :

   cloudshell edit ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py
   

Vous remarquerez que le code passe-partout (configuration du serveur MCP, gestion des connexions et initialisation du client Vertex AI) est déjà effectué. Toutefois, les quatre fonctions principales sont actuellement des espaces réservés vides.

Partie 2 : Implémenter le générateur de scènes de fêtes

Tout d'abord, nous avons besoin d'un outil qui prend en compte les centres d'intérêt d'un utilisateur (par exemple, "oiseaux") et la transforme en une requête riche et détaillée, optimisée pour la génération d'images.

Localisez le commentaire #REPLACE_GENERATE_HOLIDAY_SCENE dans la fonction generate_holiday_scene.

Remplacez toute cette ligne par le code suivant :

    prompt = (
        f"""
        Create a cozy, high-fidelity 3D render of a winter holiday scene.
        The scene should be warm and inviting with soft cinematic lighting.
        
        Seamlessly integrate the following specific theme/interest into the 
        holiday decor or landscape: {interest}.
        
        The style should be whimsical but detailed.
        Aspect Ratio: 16:9 Landscape.
        """
    )
    generate_image(prompt, "16:9", "static/generated_scene.png")
    return "Done! Saved at generated_scene.png"

Troisième partie : Implémenter le résultat photo final

Enfin, nous voulons nous assurer que l'éclairage et le style sont photoréalistes et festifs.

Recherchez le commentaire #REPLACE_GENERATE_FINAL_PHOTO.

Remplacez toute cette ligne par le code suivant pour effectuer le transfert de style et le rendu finaux :

    prompt = (
        """
        Generate a photorealistic close-up shot of a rustic wooden fireplace mantle.
        
        Lighting: Warm, glowing ambient light from a fire below (out of frame).
        Background: Softly blurred (bokeh) pine garland and twinkling lights.
        
        Foreground Composition:
        1. A wooden picture frame containing the [attached selfie image]. 
           The face in the photo must be clearly visible.
        2. A folded holiday greeting card standing upright next to the frame. 
           The front of the card displays the [attached holiday scene image] as a print.
           
        Ensure the perspective is grounded and realistic, as if taken with a 50mm lens.
        """
    )
    generate_image(prompt, "16:9", "static/generated_final_photo.png", ["static/generated_selfie.png", "static/generated_scene.png"])
    return "Done! Saved at generated_final_photo.png"

Configuration de l'environnement

Maintenant que le code est en place, nous devons nous assurer que nos dépendances sont installées. Nous allons utiliser uv, un gestionnaire de packages et de projets Python rapide.

👉💻 Dans votre terminal, exécutez la commande suivante pour ajouter FastMCP en tant que dépendance de notre projet :

cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
uv add fastmcp

Vous verrez qu'une nouvelle dépendance fastmcp>=2.13.3 a été ajoutée à votre fichier ~/holiday_workshop/01-MCP-Files-Testing/01-starter/pyproject.toml.

4. Tester avec la CLI Gemini pour le serveur MCP

Maintenant que notre code de serveur est complet, comment le tester ?

En règle générale, tester un serveur de backend nécessite de créer une UI de frontend ou d'écrire des requêtes curl complexes. Cependant, nous pouvons utiliser la CLI Gemini.

Qu'est-ce que la CLI Gemini ?

La CLI Gemini est un outil en ligne de commande qui vous permet de discuter directement avec un modèle Gemini dans votre terminal, mais avec un super pouvoir : elle peut découvrir et utiliser automatiquement les outils exécutés sur votre serveur MCP local.

C'est extrêmement utile pour le développement, car cela isole la logique. Vous pouvez vérifier que le modèle comprend vos outils et les appelle correctement avant de vous soucier de créer une interface Web ou un framework d'agent.

Connecter et exécuter

Nous allons demander à Gemini CLI de gérer notre serveur à l'aide de la commande mcp add.

Dans votre terminal, exécutez la commande suivante :

gemini mcp add holidays uv run ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py

• add holidays : nous avons donné un surnom à notre serveur ("vacances").
• uv run ... : nous avons fourni la commande explicite pour démarrer le serveur Python que nous venons de modifier.

C'est parti !

Démarrez maintenant la session de chat :

gemini

Essayez la requête suivante pour vérifier si Gemini peut "voir" vos nouveaux outils. Notez que vous devrez peut-être autoriser la CLI Gemini à utiliser notre outil de jours fériés.

• 👉 Utilisateur :

  "I want to create a festive holiday photo. I like birds a lot."
  

• Gemini :

  *Thinking...*
  *Calling tool: generate_holiday_scene(interest='birds')*
  
  Done! Saved at generated_scene.png
  

• 👉 Utilisateur :

  "Great! Now generate a knitting pattern for a sweater with reindeer on it."
  

• Gemini :

  *Thinking...*
  *Calling tool: generate_sweater_pattern(motif='reindeer')*
  
  Done! Saved at generated_pattern.png
  

  Comme vous avez utilisé MCP, l'IA a compris exactement quelle fonction Python appeler pour répondre à votre demande.

Examiner l'image

• Mettez fin à la CLI Gemini en appuyant sur Control+C.
• Vérifiez l'image générée dans votre dossier : ~/holiday_workshop/01-MCP-Files-Testing/01-starter/static.

Vérifiez votre photo ici :

Conclusion et étapes suivantes

Félicitations ! Vous avez créé un serveur MCP fonctionnel. Vous disposez désormais d'un ensemble fonctionnel d'outils d'IA qui peuvent générer des motifs, composer des images et affiner des scènes.

Cependant, avez-vous remarqué quelque chose dans le test ci-dessus ? Vous deviez mener le processus. Vous deviez demander la scène, puis le motif, puis demander de les combiner.

Bien que Gemini soit intelligent, nous avons besoin de plus de contrôle pour un workflow de production complexe, où nous devons générer un motif avant de pouvoir le placer sur un pull et gérer les erreurs si la génération d'image échoue. Nous voulons un système dédié qui puisse planifier, critiquer son propre travail et gérer l'état de notre carte de vœux sans que nous ayons à le guider à chaque étape.

Dans la section suivante, nous allons mettre de l'ordre dans ce chaos créatif. Nous allons implémenter l'Agent Development Kit (ADK) pour créer un agent structuré qui orchestre ces outils MCP dans un pipeline de production parfait.

5. Vibe-Coding d'un agent ADK

Nous disposons d'un ensemble d'outils fonctionnel (notre serveur MCP), mais pour le moment, c'est nous qui faisons tout le travail en indiquant à Gemini exactement quel outil appeler et quand.

Dans cette section, nous allons créer un agent d'IA, c'est-à-dire un système capable de raisonner, de planifier et d'exécuter des tâches en plusieurs étapes de manière autonome. Pour ce faire, nous allons utiliser l'Agent Development Kit (ADK).

Qu'est-ce qu'un agent ?

Si les outils MCP sont les "mains" (qui font le travail), l'agent est le "cerveau". Un agent utilise un LLM pour comprendre l'intention d'un utilisateur ("Fais-moi une carte de vœux"), la décompose en étapes ("J'ai d'abord besoin d'une scène, puis d'un motif…") et décide des outils à utiliser pour atteindre l'objectif.

Qu'est-ce que l'ADK ?

Agent Development Kit (ADK) est un framework de Google qui facilite la création de ces agents. Il gère les "tuyaux" complexes, comme la gestion de l'historique des discussions, la connexion aux outils et le passage d'un modèle à un autre. Vous pouvez ainsi vous concentrer sur la personnalité et la logique de votre application.

Vibe coding basé sur le contexte

Il est courant d'utiliser une requête unique et massive pour générer du code. Toutefois, lorsque vous créez des applications complexes, il est souvent préférable de considérer l'IA comme un partenaire qui maintient le contexte au fil du temps.

Nous allons utiliser les fonctionnalités de mémoire de la CLI Gemini pour préparer le terrain avant d'écrire la moindre ligne de code.

1. Préparer l'environnement

Ouvrez votre terminal et accédez au répertoire de démarrage :

cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter

Lancez Gemini CLI :

gemini

2. Gérer le contexte et la mémoire

Pour coder l'ambiance, l'IA doit savoir qui elle est et ce qu'elle sait. La CLI Gemini nous permet de gérer cela de manière explicite.

• /memory show : saisissez cette commande pour voir ce que l'IA sait actuellement sur votre projet et votre session.
• /memory add : utilisez cette option pour injecter des connaissances de base que l'IA doit retenir tout au long de la conversation.

Commençons par définir le persona de notre partenaire de programmation. Exécutez la commande suivante dans la Gemini CLI :

/memory add "You are an expert Python developer specialized in the Google Agent Development Kit (ADK). You write clean, modular code and prefer using the latest ADK patterns."

Gemini comprend désormais son rôle. Ce contexte influencera chaque réponse ultérieure, garantissant un code de haute qualité conforme à l'ADK.

3. Étape 1 : Vibe-Coding de l'agent de base

Au lieu d'essayer de générer l'ensemble du système en une seule fois, commençons par le squelette. Nous voulons établir la structure du fichier et la personnalité de base de l'agent.

Saisissez la requête suivante dans la CLI Gemini :

Let's start by building the basic agent structure. 

Please create a file structure for a `root_agent`. 
1. Create `root_agent/__init__.py` that imports `agent`.
2. Create `root_agent/agent.py` by following exactly how this file is doing import and agent creation @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py

In `agent.py`:
- Create an `Agent` named "root_agent" using the model "gemini-2.5-flash".
- The instruction string should define a "Holiday Magic Assistant". 
- The personality should be enthusiastic (`🎄✨`) and prefer "cute, kawaii, cartoon" styles for any visual tasks.

Gemini génère la structure de fichier et le code Python initial. Vérifiez qu'il est correct, puis appliquez/acceptez les modifications.

4. Étape 2 : Ajouter le serveur MCP (les outils)

Maintenant que nous avons un agent de base, nous devons lui donner des "mains". Nous devons connecter l'agent au serveur MCP que nous avons créé dans l'atelier précédent.

Saisissez la requête suivante dans la CLI Gemini :

Now, let's give the agent access to tools. Update `agent.py` to include our local MCP server. By following exactly how this agent is connecting to mcp tool @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py

In `agent.py`:
- Import `McpToolset` to define our STDIO MCP server. as @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
- Connect to the python file located at `../mcp_server.py` relative to agent.py.

Gemini va maintenant refactoriser votre agent.py existant pour inclure les définitions d'outils et la logique de connexion.

Remarque : Si vous souhaitez vérifier votre travail ou si le code généré ne fonctionne pas comme prévu, vous pouvez comparer vos fichiers à la solution de référence située dans : ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/solution

6. Exécuter l'interface Web de l'agent

L'ADK est fourni avec une interface de test intégrée appelée adk web. Cela permet de lancer une interface utilisateur de chat simplifiée pour que nous puissions discuter immédiatement avec notre agent.

1. Si GeminiCLI est toujours ouvert, appuyez sur control+C pour le fermer. Maintenant, dans votre terminal(dans le dossier solution, vous pouvez accéder à starter pour tester votre code en exécutant uv run adk web dans votre dossier starter), exécutez :

   cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/02-solution
   uv run adk web --port 8000
   

2. Cloud Shell vous avertit qu'un service est en cours d'exécution sur le port 8000. Cliquez sur Aperçu sur le Web > Prévisualiser sur le port 8000.

Tester l'agent

Une interface de chat devrait maintenant s'afficher. Voyons si notre agent suit ses nouvelles instructions et accède correctement aux outils MCP.

Essayez ces requêtes :

• "Bonjour ! Qui êtes-vous ?"
  • (Attendez-vous à une réponse festive et enthousiaste.)
• "J'ai besoin d'un arrière-plan pour ma carte de vœux. Crée un village enneigé."
  • (L'agent doit appeler le generate_holiday_scene. Remarquez comment il applique automatiquement le style "mignon/dessin animé" défini dans les instructions système.
• "Génère un motif de pull avec de petites parts de pizza."
  • (L'agent doit appeler le generate_sweater_pattern).

Vous pouvez voir l'image générée ici :

Appuyez sur Control+C pour quitter si vous avez terminé les tests.

Conclusion et étapes suivantes

Vous avez réussi à "coder l'ambiance" d'un agent Google ADK à l'aide d'une approche contextuelle.

• Nous avons établi le contexte : nous avons utilisé /memory add pour définir un persona expert.
• Nous avons créé Iteratively : nous avons d'abord créé le squelette, puis ajouté les connexions aux outils.

La prévisualisation Web de l'ADK intégrée est idéale pour les tests, mais pour notre produit final, nous souhaitons une expérience personnalisée et conforme à notre marque. Dans la section suivante, nous allons intégrer cet agent dans une interface Web personnalisée.

Si vous rencontrez Unexpected response from metadata server: service account info is missing 'email' field à un moment donné de l'atelier, cela signifie que vous devez actualiser votre Cloud Shell et réexécuter gcloud config set project $(cat ~/project_id.txt) --quiet pour définir project id avant de continuer.

7. Connecter ADK à l'UI

Maintenant que nous avons une définition d'agent, nous devons l'exécuter. C'est là que le Runner et le service de session entrent en jeu.

Implémentation

1. 👉 Saisissez ce qui suit dans votre commande :

   cloudshell edit ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py
   

   ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py s'ouvre dans votre éditeur.
2. Remplacez # TODO: Create Session Service par le code suivant :

   from google.adk.sessions import InMemorySessionService
   from google.adk.memory import InMemoryMemoryService
   session_service = InMemorySessionService()
   memory_service = InMemoryMemoryService()
   

   Le service de session correspond à la "mémoire de travail" de votre agent.

   • Rôle : il stocke l'historique immédiat et désordonné de la conversation en cours (par exemple, "Qu'est-ce que je viens de demander ?").
   • Deux saveurs :
   • InMemorySessionService : rapide, facile, mais amnésique. Si vous redémarrez le serveur, l'agent oublie tout. Idéal pour les tests.
   • VertexAiSessionService : robuste, avec une base de données. Il enregistre l'état sur Google Cloud, ce qui permet de poursuivre la conversation des semaines plus tard ou après le redémarrage du serveur.
3. Remplacez # TODO: Initialize Runner par le code suivant :

   runner = Runner(
       app_name="agents",
       agent=christmas_agent,
       session_service=session_service,
       memory_service=memory_service,
   )
   

Runner : si l'agent est le "cerveau", le Runner est le "cœur". Cela permet de faire circuler le sang. Le Runner est responsable :

• Associer l'agent à un utilisateur et à une session.
• Exécution de la boucle d'événements.
• Gérer les transitions d'état.

4. Examinez la ligne 158 de ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py(aucune action requise) : vous vous demandez comment l'application obtient la réponse finale ? Voici la boucle d'événement alimentée par le runner :

   async for event in runner.run_async(
       user_id=user_id,
       session_id=session_id,
       new_message=content
   )
   

Les agents ADK The Event Loop ne se contentent pas de "répondre". Ils pensent en boucle. Lorsque vous appelez runner.run_async() :

1. L'entrée utilisateur entre dans la boucle.
2. Planification : l'agent examine ses outils et ses objectifs.
3. Agir : si nécessaire, il fait appel à un outil (par exemple, list_files).
4. Observer : lit le résultat de l'outil.
5. Réfléchir : l'IA détermine si elle a besoin de plus d'informations ou si elle peut répondre.
6. Boucle : répète les étapes 2 à 5 jusqu'à ce qu'elle soit satisfaite.
7. Répondre : fournit la réponse finale à l'utilisateur.

Présentation détaillée : architecture et déploiement

Nous utilisons FastAPI pour diffuser cet agent.

• Pourquoi FastAPI ? : Les agents sont souvent liés aux E/S (en attente des LLM). La nature asynchrone de FastAPI gère parfaitement cela.
• Absence d'état : notez que notre point de terminaison d'API est sans état. Nous n'enregistrons pas les variables dans le champ d'application global. Nous nous appuyons sur session_id et SessionService pour reconstruire l'état de chaque requête. Cela signifie que vous pouvez déployer cette application sur Cloud Run (sans serveur) et la mettre à l'échelle à zéro.

8. Tester l'application avec la fonctionnalité magique de l'agent

1. 👉 💻 Saisissez la commande suivante :

   cd ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter
   ./start_app.sh
   

   ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py s'ouvre dans votre éditeur.
2. Le résultat suivant s'affiche :👉👉 Assurez-vous de cliquer sur http://localhost:5173/ ou d'ouvrir une nouvelle fenêtre et de saisir http://localhost:5173/.

   Notez qu'il NE S'AGIT PAS du lien du serveur de backend : Uvicorn running on http://0.0.0.0:8000

3. Vous serez ensuite redirigé vers le site Web avec l'interface de chat :
4. Testez en important une image(de vous ou de votre animal de compagnie, par exemple).
5. 👉 Posez ensuite

   Can you generate a picture my cat wearing snowflake pattern sweater?
   

   L'image générée s'affichera ici :
6. 👉💻 Une fois les tests terminés, appuyez sur control+C dans le terminal pour mettre fin au processus.

Si vous constatez que les choses ne fonctionnent pas comme prévu, vous pouvez accéder à ~/holiday_workshop/03-Connect-ADK-MCP-UI/02-solution, exécuter ./start_app.sh, puis suivre les mêmes étapes que ci-dessus.

9. Vertex AI Memory Bank

Mémoire à court terme et mémoire à long terme

• Contexte à court terme : "Qu'est-ce que je viens de dire ?" (historique des sessions). Ces informations sont perdues lorsque la fenêtre de chat se ferme.
• Mémoire à long terme : "Quel est mon langage de programmation préféré ?" (préférences utilisateur) Cela devrait persister indéfiniment.

Vertex AI Memory Bank fournit ce stockage à long terme. Il permet à l'agent de stocker et de récupérer des informations personnalisées sur l'utilisateur.

Sessions et Banque de mémoire

• Sessions (VertexAiSessionService) : il s'agit du journal. Il stocke la séquence brute et chronologique de chaque message, appel d'outil et événement (AppendEvent, ListEvents). Il fournit la vérité terrain pour ce qui s'est passé.
• Banque de données (VertexAiMemoryBankService) : il s'agit de la connaissance. Il stocke des faits synthétisés à long terme (GenerateMemories, RetrieveMemories). Il est limité à un user_id spécifique, ce qui garantit la confidentialité et l'isolement.

1. 👉 💻 Saisissez la commande suivante :

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py
   

   ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py s'ouvre dans votre éditeur.
2. Recherchez # TODO: Create Vertex AI Session Service & Memory Bank Service et remplacez toute la ligne par ce qui suit :

       session_service = VertexAiSessionService(
           project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID
       )
       memory_service = VertexAiMemoryBankService(
           project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID
       )
   
   

3. 👉 💻 Saisissez la commande suivante :

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py
   

   ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py s'ouvre dans votre éditeur.
4. Remplacez # TODO: Set Up Configuration par le code suivant :

   # Basic configuration types
   MemoryBankConfig = types.ReasoningEngineContextSpecMemoryBankConfig
   SimilaritySearchConfig = (
       types.ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig
   )
   GenerationConfig = types.ReasoningEngineContextSpecMemoryBankConfigGenerationConfig
   
   # Advanced configuration types
   CustomizationConfig = types.MemoryBankCustomizationConfig
   MemoryTopic = types.MemoryBankCustomizationConfigMemoryTopic
   CustomMemoryTopic = types.MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic
   GenerateMemoriesExample = types.MemoryBankCustomizationConfigGenerateMemoriesExample
   ConversationSource = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource
   )
   ConversationSourceEvent = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent
   )
   ExampleGeneratedMemory = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleGeneratedMemory
   )
   

Principales fonctionnalités

Vertex AI Memory Bank n'est pas qu'une simple base de données, mais un service cognitif actif.

• Extraction de la mémoire : le système utilise un LLM pour lire la conversation et extraire des faits pertinents en fonction des schémas CustomMemoryTopic que nous avons définis (par exemple, "Sweater Preferences"). Il ignore les bavardages et enregistre le signal.
• Consolidation de la mémoire : elle fusionne automatiquement les nouvelles informations avec les anciennes. Si un utilisateur dit "J'aime le rouge", puis "En fait, je préfère le bleu", la Banque de mémoire fait évoluer l'enregistrement de la mémoire au lieu de créer des doublons conflictuels.
• Génération asynchrone : les souvenirs sont générés en arrière-plan. Votre agent ne s'arrête pas pendant que la banque de mémoire "réfléchit" à la conversation.

5. 👉 Dans le même fichier : 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. Recherchez # TODO: Set up topic et remplacez l'intégralité de la ligne par ce qui suit :

       custom_topics = [
           # Topic 1: Sweater Preference
           MemoryTopic(
               custom_memory_topic=CustomMemoryTopic(
                   label="sweater_preference",
                   description="""Extract the user's preferences for sweater styles, patterns, and designs. Include:
                   - Specific patterns (snowflake, reindeer, geometric, fair isle, solid, etc.)
                   - Style preferences (chunky knit, cardigan, pullover, turtleneck, oversized, fitted)
                   - Color preferences (red, green, navy, pastel, etc.)
                   - Material preferences if mentioned (wool, cotton, cashmere, itchy/soft)
                   - Themes (retro, modern, ugly christmas sweater, elegant)
   
                   Example: "User wants a retro style sweater with a pixelated reindeer pattern."
                   Example: "User prefers dark blue colors and hates itchy wool."
                   """,
               )
           ),
           # Topic 2: Personal Context
           MemoryTopic(
               custom_memory_topic=CustomMemoryTopic(
                   label="personal_context",
                   description="""Extract the user's personal context including hobbies, pets, interests, job, and preferred scenes. Include:
                   - Hobbies and activities (skiing, reading, gaming, cooking, etc.)
                   - Pets (type, breed, name, color)
                   - Job or profession if relevant to their style
                   - General interests (sci-fi, nature, vintage, tech)
                   - Preferred scenes or vibes (cozy fireplace, snowy mountain, cyberpunk city, beach)
   
                   Example: "User has a golden retriever named Max."
                   Example: "User loves skiing and wants a snowy mountain background."
                   Example: "User is a software engineer who likes cyberpunk aesthetics."
                   """,
               )
           )
       ]
   

6. 👉 Dans le même fichier : 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. Recherchez # TODO: Create Agent Engine et remplacez l'intégralité de la ligne par ce qui suit :

       agent_engine = client.agent_engines.create(
           config={
               "display_name": AGENT_DISPLAY_NAME,
               "context_spec": {
                   "memory_bank_config": {
                       "generation_config": {
                           "model": f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash"
                       },
                       "customization_configs": [customization_config]
                   }
               },
           }
       )
   

Agent Engine

Le moteur d'agent est le "matériel cérébral" dans le cloud. Il gère :

• Base de données vectorielle : pour stocker les souvenirs.
• Indexation : pour que les souvenirs puissent être recherchés.
• API : pour permettre à l'agent de l'interroger. Lorsque vous exécutez deploy_agent.py, vous provisionnez essentiellement ce matériel.

Pourquoi ne pas utiliser simplement la requête ?

Vous vous demandez peut-être : "Pourquoi ne pas simplement coller l'historique de l'utilisateur dans la requête ?"

• Limites de taille : les fenêtres de contexte sont grandes, mais pas infinies. Vous ne pouvez pas insérer cinq ans d'historique.
• Coût : le traitement d'un million de jetons pour chaque "Bonjour" est prohibitif.
• Cibler : la banque de mémoire sert de moteur de recherche pour votre agent. Il ne récupère que les faits pertinents.

7. 👉 💻 Saisissez la commande suivante :

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py
   

   ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py s'ouvre dans votre éditeur.
8. Dans le fichier ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py, remplacez # TODO: Add PreloadMemoryTool par ce qui suit :

   if USE_MEMORY_BANK:
       agent_tools.append(PreloadMemoryTool())
   

PreloadMemoryTool et add_session_to_memory

Dans agent.py, vous trouverez deux composants clés :

• PreloadMemoryTool : il s'agit d'un outil qui permet à l'agent de se "googler" lui-même. Si l'utilisateur pose une question vague comme "Prépare-moi mon café habituel", l'agent peut utiliser cet outil pour interroger la banque de mémoire sur les "préférences de café" avant de répondre.
• add_session_to_memory : il s'agit d'un rappel d'arrière-plan.
  • Pourquoi utiliser Async ? L'enregistrement de la mémoire prend du temps (résumé de la discussion, extraction des faits). Nous ne voulons pas que l'utilisateur attende. Nous l'exécutons en arrière-plan (add_session_to_memory) à l'aide de after_agent_callback.

10. La banque de mémoire en action

1. 👉 💻 Saisissez la commande suivante :

   cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter
   ./use_memory_bank.sh
   

   Le résultat s'affiche comme suit :

   Ce script use_memory_bank.sh utilise d'abord le fichier 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py pour associer le moteur d'agent à votre agent afin qu'il puisse utiliser la banque de mémoire Vertex AI. Il mettra ensuite à jour le fichier .env pour que agent engine ID soit enregistré en tant que environmental variable.

   Vérifiez votre fichier ~/holiday_workshop/.env, vous verrez (aucune action requise).

   USE_MEMORY_BANK=TRUE
   AGENT_ENGINE_ID={agent_engine_id}
   

2. 👉 💻 Testez la mémoire avec l'UI de l'application. Saisissez ce qui suit dans votre commande :

   cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter
   ./start_app.sh
   

   Assurez-vous de cliquer sur http://localhost:5173/ ou d'ouvrir une nouvelle fenêtre et de saisir http://localhost:5173/.Notez que Uvicorn running on http://0.0.0.0:8000 n'est qu'un serveur backend, et non le lien sur lequel nous voulons cliquer.L'interface de chat du site Web est désormais votre agent personnalisé !
3. 👉 Testez la mémoire. Si vous saisissez dans l'UI :

   I want a sweater that matches my dog. He's a golden retriever.
   

   I'm a programmer, so I want something geeky. Maybe a matrix style?
   

   I like snowflake sweater pattern
   

L'agent l'identifiera comme une préférence et la stockera dans la Memory Bank.

La semaine prochaine(ou à chaque fois que vous redémarrez l'application en appuyant sur Control+C et ./start_app.sh), si vous demandez :

what is my preference on sweater pattern?

L'agent interrogera la mémoire, consultera votre préférence et générera un motif de pull sans que vous le lui demandiez.

Personnalisation : elle est essentielle pour créer des agents utiles. En mémorisant les préférences des utilisateurs (motif du pull, contexte personnel), l'agent devient plus efficace et plus utile au fil du temps.

4. Vérifiez dans Vertex AI Agent Engine en accédant à la console Google Cloud Agent Engine
   .
   • Assurez-vous de sélectionner le projet dans le sélecteur de projets en haut à gauche :
   • Vérifiez le moteur d'agent que vous venez de déployer à partir de la commande précédente use_memory_bank.shCliquez sur le moteur d'agent que vous venez de créer.
5. Cliquez sur l'onglet Memories de cet agent déployé pour afficher tous les souvenirs.

Félicitations ! Vous venez d'associer la banque de mémoire à votre agent.

11. Conclusion

Résumé

Vous avez réussi à concevoir et à créer un système agentique complet.

• Connectivité : vous avez utilisé MCP pour standardiser la façon dont votre agent accède aux outils locaux.
• Orchestration : vous avez utilisé l'ADK pour gérer la boucle de raisonnement complexe requise pour les tâches en plusieurs étapes.
• Personnalisation : vous avez utilisé Memory Bank pour créer une couche d'apprentissage persistante qui mémorise le contexte utilisateur.

Étapes suivantes

• Créer votre propre serveur MCP : créez un serveur pour votre API ou base de données interne.
• Explorer les modèles ADK : découvrez les "boucles de raisonnement" et l'"orchestration" dans la documentation ADK.
• Déployer : transformez votre agent, qui était un script local, en service de production sur Cloud Run.

Continuez à développer : la combinaison de MCP pour la connectivité et de Memory Bank pour la personnalisation constitue la base de la prochaine génération d'applications intelligentes.