Gérer les sessions à l'aide de la console Google Cloud ou des appels d'API

Cette section explique comment utiliser les sessions de la plate-forme d'agent pour gérer les sessions à l'aide de la console Google Cloud ou des appels d'API directs. Vous pouvez utiliser la console Google Cloud ou des appels d'API directs si vous ne souhaitez pas utiliser d'agent ADK pour gérer les sessions.

Pour gérer les sessions à l'aide de l'agent ADK, consultez Gérer les sessions avec Agent Development Kit.

Créer une instance Agent Runtime

Pour accéder aux sessions Agent Platform, vous devez d'abord utiliser une instance Agent Runtime. Vous n'avez pas besoin de déployer de code pour commencer à utiliser Sessions. Si vous avez déjà utilisé Agent Engine, la création d'une instance Agent Runtime ne prend que quelques secondes, sans déploiement de code. Cela peut prendre plus de temps si vous utilisez Agent Engine pour la première fois.

Si vous ne disposez pas d'une instance Agent Runtime, créez-en une à l'aide du code suivant :

import vertexai

client = vertexai.Client(
  project="PROJECT_ID",
  location="LOCATION"
)
# If you don't have an Agent Engine instance already, create an instance.
agent_engine = client.agent_engines.create()

# Optionally, print out the Agent Engine resource name. You will need the
# resource name to interact with Sessions later on.
print(agent_engine.api_resource.name)

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet
  • LOCATION : votre région. Consultez les régions disponibles pour les sessions.

Répertorier les sessions

Lister les sessions associées à votre instance Agent Runtime

Console

Pour les agents déployés, vous pouvez utiliser la console Google Cloud pour lister les sessions associées à votre agent :

  1. Dans la console Google Cloud , accédez à la page Déploiements de la plate-forme d'agent.

    Accéder à la page "Déploiements"

    Les instances Agent Engine qui font partie du projet sélectionné apparaissent dans la liste. Vous pouvez utiliser le champ Filtrer pour filtrer la liste par la colonne de votre choix.

  2. Cliquez sur le nom de votre instance Agent Engine.

  3. Cliquez sur l'onglet Sessions. Une liste des sessions s'affiche par ID.

Python 

for session in client.agent_engines.sessions.list(
    name=agent_engine.api_resource.name,  # Required
):
    print(session)

# To list sessions for a specific user:
for session in client.agent_engines.sessions.list(
    name=agent_engine.api_resource.name,  # Required
    config={"filter": "user_id=USER_ID"},
):
    print(session)
  • USER_ID : choisissez votre propre ID utilisateur (128 caractères maximum). Exemple :user-123

REST

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet
  • LOCATION : région dans laquelle vous avez créé votre instance Agent Engine.
  • AGENT_ENGINE_ID : ID de ressource de votre instance Agent Engine.

Méthode HTTP et URL : 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Exécutez la commande suivante :

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions"

PowerShell

Exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions" | Select-Object -Expand Content

Une liste de sessions devrait s'afficher.

Si vous le souhaitez, vous pouvez ajouter le paramètre de requête ?filter=user_id=\"USER_ID\" pour lister les sessions d'un utilisateur spécifique, où USER_ID correspond à l'ID de l'utilisateur pour lequel vous souhaitez interroger les sessions.

Créer une session

Créez une session associée à un ID utilisateur.

Console

Pour les agents déployés, vous pouvez utiliser la console Google Cloud pour créer des sessions :

  1. Dans la console Google Cloud , accédez à la page Déploiements de la plate-forme d'agent.

    Accéder à la page "Déploiements"

    Les instances Agent Engine qui font partie du projet sélectionné apparaissent dans la liste. Vous pouvez utiliser le champ Filtrer pour filtrer la liste par la colonne de votre choix.

  2. Cliquez sur le nom de votre instance Agent Engine.

  3. Cliquez sur l'onglet Playground.

  4. Cliquez sur Nouvelle session pour créer une session.

Python 

session = client.agent_engines.sessions.create(
    name=agent_engine.api_resource.name,  # Required
    user_id=USER_ID, # Required
    session_id=SESSION_ID,
)

où USER_ID correspond à l'ID utilisateur que vous avez défini. Exemple : user-123.

Pour SESSION_ID, tenez compte des restrictions suivantes afin d'éviter les conflits avec les ID générés par le système :

  • Si le premier caractère est une lettre, l'ID peut comporter jusqu'à 63 caractères. Les caractères valides sont les lettres minuscules, les chiffres et les traits d'union ([a-z0-9-]). Le dernier caractère doit être une lettre ou un chiffre.
  • Si le premier caractère est un chiffre, l'ID peut comporter jusqu'à neuf caractères. Les caractères valides sont des chiffres ([0-9]) sans zéros au début.

REST

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet
  • LOCATION : région dans laquelle vous avez créé votre instance Agent Engine.
  • AGENT_ENGINE_ID : ID de ressource de votre instance Agent Engine.
  • USER_ID : ID utilisateur que vous avez défini. Exemple : sessions-agent.
  • SESSION_ID : ID de session que vous avez défini. Par exemple : my-custom-session.

    Pour éviter les collisions avec les ID générés par le système, respectez les restrictions suivantes lorsque vous spécifiez un ID de session personnalisé :

    • Si le premier caractère est une lettre, l'ID peut comporter jusqu'à 63 caractères. Les caractères valides sont les lettres minuscules, les chiffres et les traits d'union (`[a-z0-9-]`). Le dernier caractère doit être une lettre ou un chiffre.
    • Si le premier caractère est un chiffre, l'ID peut comporter jusqu'à neuf caractères. Les caractères valides sont des chiffres (`[0-9]`) sans zéros au début.

    Méthode HTTP et URL : 

    POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions

    Corps JSON de la requête : 

    {
  "userId": USER_ID
}

    Pour envoyer votre requête, choisissez l'une des options suivantes :

    curl

    Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

    curl -X POST \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
         "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions"

    PowerShell

    Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method POST `
        -Headers $headers `
        -ContentType: "application/json; charset=utf-8" `
        -InFile request.json `
        -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions" | Select-Object -Expand Content

    Vous devriez recevoir une opération de longue durée que vous pouvez interroger pour vérifier l'état de la création de votre session.

Configurer la valeur TTL (Time To Live) de la session

Toutes les sessions doivent avoir une heure d'expiration. Vous pouvez définir ce délai d'expiration lorsque vous créez ou mettez à jour une session. La session et ses événements enfants sont automatiquement supprimés une fois le délai d'expiration écoulé. Vous pouvez définir directement le délai d'expiration (expire_time) ou la durée de vie (ttl) en secondes. Si aucune valeur n'est spécifiée, le système applique une TTL par défaut de 365 jours.

Valeur TTL

Si vous définissez la durée de vie, le serveur calcule le délai d'expiration comme suit : create_time + ttl pour les sessions nouvellement créées ou update_time + ttl pour les sessions mises à jour.

client.agent_engines.sessions.create(
    name=agent_engine.api_resource.name,  # Required
    user_id=USER_ID, # Required
    config={
        # Session will be deleted 10 days after creation time.
        "ttl": f"{24 * 60 * 60 * 10}s"
    }
)

Date/Heure d'expiration 

import datetime

client.agent_engines.sessions.create(
    name=agent_engine.api_resource.name,  # Required
    user_id=USER_ID, # Required
    config={
        # Session will be deleted at the provided time (10 days after current time).
        "expire_time": datetime.datetime.now(tz=datetime.timezone.utc) + datetime.timedelta(seconds=24 * 60 * 60 * 10),
    }
)

Obtenir une session

Obtenez une session spécifique associée à votre instance Agent Platform.

Console

Pour les agents déployés, vous pouvez utiliser la console Google Cloud pour créer des sessions :

  1. Dans la console Google Cloud , accédez à la page Déploiements de la plate-forme d'agent.

    Accéder à la page "Déploiements"

    Les instances Agent Engine qui font partie du projet sélectionné apparaissent dans la liste. Vous pouvez utiliser le champ Filtrer pour filtrer la liste par la colonne de votre choix.

  2. Cliquez sur le nom de votre instance Agent Engine.

  3. Cliquez sur l'onglet Playground.

  4. Cliquez sur l'onglet Sessions. Une liste des sessions s'affiche par ID.

  5. Cliquez sur la session que vous souhaitez afficher plus en détail.

Python 

session = client.agent_engines.sessions.get(
    name='projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID',  # Required
    user_id=USER_ID, # Required
)
# session.name will correspond to
#   'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID'

REST

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet
  • LOCATION : région dans laquelle vous avez créé votre instance Agent Engine.
  • AGENT_ENGINE_ID : ID de ressource de votre instance Agent Engine.
  • SESSION_ID : ID de ressource de la session que vous souhaitez récupérer. Vous pouvez obtenir l'ID de session à partir de la réponse que vous avez reçue lorsque vous avez créé la session.

Méthode HTTP et URL : 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Exécutez la commande suivante :

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID"

PowerShell

Exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID" | Select-Object -Expand Content

Dans la réponse, vous devriez obtenir des informations sur votre session.

Supprimer une session

Supprimez une session associée à votre instance Agent Platform.

Console

Pour les agents déployés, vous pouvez utiliser la console Google Cloud pour supprimer les sessions associées à votre agent :

  1. Dans la console Google Cloud , accédez à la page Déploiements de la plate-forme d'agent.

    Accéder à la page "Déploiements"

    Les instances Agent Engine qui font partie du projet sélectionné apparaissent dans la liste. Vous pouvez utiliser le champ Filtrer pour filtrer la liste par la colonne de votre choix.

  2. Cliquez sur le nom de votre instance Agent Engine.

  3. Cliquez sur l'onglet Sessions. Une liste des sessions s'affiche par ID.

  4. Cliquez sur le menu Plus d'actions () de la session que vous souhaitez supprimer.

  5. Cliquez sur Supprimer.

  6. Cliquez sur Supprimer la session.

Python 

client.agent_engines.sessions.delete(name=session.name)

REST

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet
  • LOCATION : région dans laquelle vous souhaitez créer l'instance Example Store.
  • AGENT_ENGINE_ID : ID de ressource de votre instance Agent Engine.
  • SESSION_ID : ID de ressource de la session que vous souhaitez récupérer.

Méthode HTTP et URL : 

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Exécutez la commande suivante :

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID"

PowerShell

Exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID" | Select-Object -Expand Content

Vous devriez recevoir un code d'état indiquant le succès de l'opération (2xx), ainsi qu'une réponse vide.

Lister les événements d'une session

Lister les événements d'une session associée à votre instance Agent Platform.

Console

Pour les agents déployés, vous pouvez utiliser la console Google Cloud pour créer des sessions :

  1. Dans la console Google Cloud , accédez à la page Déploiements de la plate-forme d'agent.

    Accéder à la page "Déploiements"

    Les instances Agent Engine qui font partie du projet sélectionné apparaissent dans la liste. Vous pouvez utiliser le champ Filtrer pour filtrer la liste par la colonne de votre choix.

  2. Cliquez sur le nom de votre instance Agent Engine.

  3. Cliquez sur l'onglet Playground.

  4. Cliquez sur l'onglet Sessions. Une liste des sessions s'affiche par ID.

  5. Cliquez sur la session que vous souhaitez afficher plus en détail.

  6. Cliquez sur l'onglet Événements pour afficher les événements associés à la session.

Python 

for session_event in client.agent_engines.list_session_events(
    name=session.name,
):
    print(session_event)

REST

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet
  • LOCATION : région dans laquelle vous avez créé votre instance Agent Engine.
  • AGENT_ENGINE_ID : ID de ressource de votre instance Agent Engine.
  • SESSION_ID : ID de ressource de la session que vous souhaitez récupérer.

Méthode HTTP et URL : 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID/events

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Exécutez la commande suivante :

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID/events"

PowerShell

Exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID/events" | Select-Object -Expand Content

Dans la réponse, vous devriez voir une liste d'événements associés à votre session.

Ajouter un événement à une session

Ajoutez un événement à une session associée à une instance de plate-forme d'agent.

Console

Pour les agents déployés, vous pouvez utiliser la console Google Cloud pour créer des sessions :

  1. Dans la console Google Cloud , accédez à la page Déploiements de la plate-forme d'agent.

    Accéder à la page "Déploiements"

    Les instances Agent Engine qui font partie du projet sélectionné apparaissent dans la liste. Vous pouvez utiliser le champ Filtrer pour filtrer la liste par la colonne de votre choix.

  2. Cliquez sur le nom de votre instance Agent Engine.

  3. Cliquez sur l'onglet Playground.

  4. Cliquez sur l'onglet Sessions. Une liste des sessions s'affiche par ID.

  5. Cliquez sur la session que vous souhaitez afficher plus en détail.

  6. Cliquez sur l'onglet Événements pour afficher les événements associés à la session.

  7. Saisissez un message et appuyez sur Entrée pour ajouter un événement à la session.

Python 

import datetime

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

Vous pouvez également utiliser le champ raw_event pour inclure des données arbitraires dans les événements de session. Cela est utile pour l'interopérabilité avec d'autres frameworks d'agents ou pour stocker des données d'événements personnalisées.

client.agent_engines.sessions.events.append(
    name=session.name,
    author="user",                                              # Required.
    invocation_id="1",                                          # Required.
    timestamp=datetime.datetime.now(tz=datetime.timezone.utc),  # Required.
    config={
        "raw_event": {
            "content": "hello",
            "custom_field": "custom_value"
        },
    },
)

REST

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet
  • LOCATION : région dans laquelle vous avez créé votre instance Agent Engine.
  • AGENT_ENGINE_ID : ID de ressource de votre instance Agent Engine.
  • USER_ID : ID utilisateur que vous avez défini. Exemple : sessions-agent.
  • SESSION_ID : ID de session que vous avez défini. Par exemple : my-custom-session.

    Pour éviter les collisions avec les ID générés par le système, respectez les restrictions suivantes lorsque vous spécifiez un ID de session personnalisé :

    • Si le premier caractère est une lettre, l'ID peut comporter jusqu'à 63 caractères. Les caractères valides sont les lettres minuscules, les chiffres et les traits d'union (`[a-z0-9-]`). Le dernier caractère doit être une lettre ou un chiffre.
    • Si le premier caractère est un chiffre, l'ID peut comporter jusqu'à neuf caractères. Les caractères valides sont des chiffres (`[0-9]`) sans zéros au début.

    Méthode HTTP et URL : 

    POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions

    Corps JSON de la requête : 

    {
  "userId": USER_ID
}

    Pour envoyer votre requête, choisissez l'une des options suivantes :

    curl

    Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

    curl -X POST \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
         "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions"

    PowerShell

    Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method POST `
        -Headers $headers `
        -ContentType: "application/json; charset=utf-8" `
        -InFile request.json `
        -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions" | Select-Object -Expand Content

    Vous devriez recevoir une opération de longue durée que vous pouvez interroger pour vérifier l'état de la création de votre session.

Effectuer un nettoyage

Pour nettoyer toutes les ressources utilisées dans ce projet, vous pouvez supprimer l'instance Agent Platform ainsi que ses ressources enfants :

agent_engine.delete(force=True)