Cette page a été traduite par l'API Cloud Translation.

Démarrage rapide avec l'API REST

Ce tutoriel explique comment effectuer des appels d'API REST directement vers les sessions et la Memory Bank de Vertex AI Agent Engine pour créer et utiliser des sessions et des mémoires à long terme. Utilisez l'API REST si vous ne souhaitez pas qu'un framework d'agent orchestre les appels pour vous, ou si vous souhaitez intégrer Sessions et Memory Bank à 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 :

Créez votre instance Vertex AI Agent Engine pour accéder aux sessions et à la banque de mémoire Vertex AI Agent Engine.
Créez des souvenirs à l'aide des options suivantes :
- Générez des souvenirs à l'aide de la banque de mémoire Vertex AI Agent Engine : écrivez des sessions et des événements dans les sessions Vertex AI Agent Engine en tant que sources pour la banque de mémoire Vertex AI Agent Engine afin de générer des souvenirs.
- Importer des souvenirs directement : rédigez vos propres souvenirs ou demandez à votre agent de les créer si vous souhaitez contrôler entièrement les informations conservées.
Récupérer des souvenirs
Effectuez un nettoyage.

Avant de commencer

Pour suivre les étapes décrites dans ce tutoriel, vous devez d'abord configurer votre projet et votre environnement.

Configurer votre projet

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Enable the API

Si vous avez sélectionné un projet, assurez-vous de disposer du rôle IAM Utilisateur Vertex AI (roles/aiplatform.user) sur le projet.

S'authentifier sur Vertex AI

Pour utiliser les exemples Python de cette page dans un environnement de développement local, installez et initialisez gcloud CLI, puis configurez le service Identifiants par défaut de l'application à l'aide de vos identifiants utilisateur.

Install the Google Cloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
To initialize the gcloud CLI, run the following command:
```
gcloud init
```
If you're using a local shell, then create local authentication credentials for your user account:
```
gcloud auth application-default login
```
You don't need to do this if you're using Cloud Shell.

If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

Pour en savoir plus, consultez Configurer les ADC pour un environnement de développement local dans la documentation sur l'authentification Google Cloud .

Importer des bibliothèques

Installez le SDK Vertex AI :

pip install google-cloud-aiplatform>=1.100.0

Créer votre instance Vertex AI Agent Engine

Pour accéder aux sessions Vertex AI Agent Engine et à la banque de mémoire Vertex AI Agent Engine, vous devez d'abord créer une instance Vertex AI Agent Engine. Vous n'avez pas besoin de déployer un agent pour commencer à utiliser les sessions et la banque de mémoire. Sans déploiement d'agent, la création d'une instance Vertex AI Agent Engine devrait prendre quelques secondes.

import vertexai

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

agent_engine = client.agent_engines.create()

Remplacez les éléments suivants :

PROJECT_ID : ID de votre projet
LOCATION : votre région. Seule la région us-central1 est acceptée pour la banque de mémoire Vertex AI Agent Engine.

Générer des souvenirs à partir de 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 et récupérer des souvenirs.

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.
```
from google.cloud import aiplatform_v1beta1

sessions_client = aiplatform_v1beta1.SessionServiceClient(
  client_options={
    "api_endpoint": "https://LOCATION-aiplatform.googleapis.com"
  },
  transport="rest"
)

session_lro = sessions_client.create_session(
  parent=AGENT_ENGINE_NAME,
  session={"user_id": "USER_ID"}
)
session_name = "/".join(session_lro.operation.name.split("/")[0:-2])
```
Remplacez les éléments suivants :
- LOCATION : votre région. Seule la région us-central1 est acceptée pour la banque de mémoire Vertex AI Agent Engine.
- 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.

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.

event = aiplatform_v1beta1.SessionEvent(
    author="user",  # Required by Sessions.
    invocation_id="1",  # Required by Sessions.
    timestamp=datetime.now().strftime('%Y-%m-%dT%H:%M:%SZ'),  # Required by Sessions.
    content = aiplatform_v1beta1.Content(
        role="user",
        parts=[aiplatform_v1beta1.Part(text="Hello")]
    )
)

sessions_client.append_event(name=session_name, event=event)

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": session_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 souvenirs

Au lieu de générer des souvenirs à partir de dialogues bruts, vous pouvez les importer ou demander à vos agents de les ajouter directement à l'aide de CreateMemory. 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).

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>
"""

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 :

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)
```
Supprimez tous les fichiers créés localement.

Étapes suivantes

Guide de démarrage rapide avec Agent Development Kit