Guide de démarrage rapide avec le SDK Vertex AI Agent Engine

Ce tutoriel explique comment effectuer des appels d'API directement vers les sessions et la banque de mémoire Vertex AI Agent Engine à l'aide du SDK Vertex AI Agent Engine. Utilisez le SDK Vertex AI Agent Engine si vous ne souhaitez pas qu'un framework d'agent orchestre les appels pour vous, ou si vous souhaitez intégrer les sessions et la banque de mémoire à des frameworks d'agent autres que l'Agent Development Kit (ADK).

Pour le guide de démarrage rapide avec l'ADK, consultez Démarrage rapide avec l'Agent Development Kit.

Ce tutoriel comprend les étapes suivantes :

  1. Créez des souvenirs à l'aide des options suivantes :
  2. Récupérer des souvenirs
  3. Effectuez un nettoyage.

Avant de commencer

Pour suivre les étapes décrites dans ce tutoriel, vous devez d'abord suivre celles de la section Configurer Memory Bank.

Générer des souvenirs avec les sessions Vertex AI Agent Engine

Après avoir configuré les sessions et la banque de mémoire Vertex AI Agent Engine, vous pouvez créer des sessions et y ajouter des événements. Les souvenirs sont générés sous forme de faits à partir de la conversation de l'utilisateur avec l'agent. Ils sont ainsi disponibles pour les futures interactions de l'utilisateur. Pour en savoir plus, consultez Générer des souvenirs et Récupérer des souvenirs.

  1. Créez une session avec un ID utilisateur opaque. Toutes les mémoires générées à partir de cette session sont automatiquement associées à la portée {"user_id": "USER_ID"}, sauf si vous fournissez explicitement une portée lors de la génération des mémoires.

    import vertexai

client = vertexai.Client(
  project="PROJECT_ID",
  location="LOCATION"
)

session = client.agent_engines.create_session(
  name=AGENT_ENGINE_NAME,
  user_id="USER_ID"
)

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet

    • LOCATION : votre région. Consultez les régions disponibles pour la banque de souvenirs.

    • AGENT_ENGINE_NAME : nom de l'instance Vertex AI Agent Engine que vous avez créée ou d'une instance Vertex AI Agent Engine existante. Le nom doit être au format suivant : projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}.

    • USER_ID : identifiant de votre utilisateur. Toutes les mémoires générées à partir de cette session sont automatiquement associées à la portée {"user_id": "USER_ID"}, sauf si vous fournissez explicitement une portée lors de la génération des mémoires.

  2. Importez des événements de manière itérative dans votre session. Les événements peuvent inclure toutes les interactions entre votre utilisateur, votre agent et vos outils. La liste ordonnée des événements représente l'historique des conversations de votre session. Cet historique des conversations sert de source pour générer des souvenirs pour cet utilisateur spécifique.

    import datetime

client.agent_engines.append_session_event(
  name=session.response.name,
  author="user",  # Required by Sessions.
  invocation_id="1",  # Required by Sessions.
  timestamp=datetime.datetime.now(tz=datetime.timezone.utc),  # Required by Sessions.
  config={
    "content": {
      "role": "user",
      "parts": [{"text": "hello"}]
    }
  }
)

  3. Pour générer des souvenirs à partir de votre historique des conversations, déclenchez une demande de génération de souvenirs pour la session :

    client.agent_engines.generate_memories(
  name=agent_engine.api_resource.name,
  vertex_session_source={
    # `session` should have the format "projects/.../locations/.../reasoningEngines/.../sessions/...".
    "session": session.response.name
  },
  # Optional when using Agent Engine Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE
)

Remplacez les éléments suivants :

  • (Facultatif) SCOPE : dictionnaire représentant le champ d'application des souvenirs générés, avec un maximum de cinq paires clé/valeur et aucun caractère *. Par exemple, {"session_id": "MY_SESSION"}. Seuls les souvenirs ayant la même portée sont pris en compte pour la consolidation. Si aucune valeur n'est spécifiée, {"user_id": session.user_id} est utilisé.

Importer des informations à mémoriser

Au lieu de générer des souvenirs à partir de dialogues bruts, vous pouvez importer des souvenirs ou demander à vos agents de les ajouter directement à l'aide de GenerateMemories avec des faits pré-extraits. Au lieu d'extraire des informations de votre contenu, la Banque de mémoire vous permet de fournir directement les faits à stocker sur votre utilisateur. Nous vous recommandons d'écrire les faits concernant les utilisateurs à la première personne (par exemple, I am a software engineer).

client.agent_engines.generate_memories(
    name=agent_engine.api_resource.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

Remplacez les éléments suivants :

  • FACT : fait préextrait à consolider avec les souvenirs existants. Vous pouvez fournir jusqu'à cinq faits pré-extraits dans une liste comme celle-ci :

    {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}

  • SCOPE : dictionnaire représentant le champ d'application des souvenirs générés. Exemple :{"session_id": "MY_SESSION"} Seuls les souvenirs ayant la même portée sont pris en compte pour la consolidation.

Vous pouvez également utiliser CreateMemory pour importer des souvenirs sans utiliser la banque de souvenirs pour l'extraction ou la consolidation de souvenirs.

memory = client.agent_engines.create_memory(
    name=agent_engine.api_resource.name,
    fact="This is a fact.",
    scope={"user_id": "123"}
)

"""
Returns an AgentEngineMemoryOperation containing the created Memory like:

AgentEngineMemoryOperation(
  done=True,
  metadata={
    "@type': 'type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateMemoryOperationMetadata",
    "genericMetadata": {
      "createTime": '2025-06-26T01:15:29.027360Z',
      "updateTime": '2025-06-26T01:15:29.027360Z'
    }
  },
  name="projects/.../locations/us-central1/reasoningEngines/.../memories/.../operations/...",
  response=Memory(
    create_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC)),
    fact="This is a fact.",
    name="projects/.../locations/us-central1/reasoningEngines/.../memories/...",
    scope={
      "user_id": "123"
    },
    update_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC))
  )
)
"""

Récupérer et utiliser des souvenirs

Vous pouvez récupérer les souvenirs de votre utilisateur et les inclure dans vos instructions système pour donner au LLM accès à votre contexte personnalisé.

Pour en savoir plus sur la récupération de souvenirs à l'aide d'une méthode basée sur le champ d'application, consultez Récupérer des souvenirs.

# Retrieve all memories for User ID 123.
retrieved_memories = list(
    client.agent_engines.retrieve_memories(
        name=agent_engine.api_resource.name,
        scope={"user_id": "123"}
    )
)

Vous pouvez utiliser jinja pour convertir vos souvenirs structurés en requête :


from jinja2 import Template

template = Template("""
<MEMORIES>
Here is some information about the user:
{% for retrieved_memory in data %}* {{ retrieved_memory.memory.fact }}
{% endfor %}</MEMORIES>
""")

prompt = template.render(data=retrieved_memories)

"""
Output:

<MEMORIES>
Here is some information about the user:
* This is a fact
</MEMORIES>
"""

Supprimer des souvenirs

Vous pouvez supprimer un souvenir spécifique à l'aide de son nom de ressource :

client.agent_engines.delete_memory(name=MEMORY_NAME)

Remplacez les éléments suivants :

  • MEMORY_NAME : nom du souvenir à supprimer. Le nom doit être au format suivant : projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory}. Vous pouvez trouver le nom du souvenir en récupérant les souvenirs.

Effectuer un nettoyage

Pour nettoyer toutes les ressources utilisées dans ce projet, vous pouvez supprimer le projet Google Cloud que vous avez utilisé pour ce tutoriel.

Vous pouvez également supprimer les ressources individuelles que vous avez créées, comme suit :

  1. Utilisez l'exemple de code suivant pour supprimer l'instance Vertex AI Agent Engine, ce qui supprime également toutes les sessions ou mémoires associées à l'instance Vertex AI Agent Engine.

    agent_engine.delete(force=True)

  2. Supprimez tous les fichiers créés localement.

Étapes suivantes