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

Cette section explique comment utiliser les sessions Agent Platform pour gérer les sessions à l'aide de la console Google Cloud ou d'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 (ADK).

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 les sessions. Si vous avez déjà utilisé Agent Runtime, 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 Runtime pour la première fois.

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

import agentplatform

client = agentplatform.Client(
  project="PROJECT_ID",
  location="LOCATION"
)
# If you don't have an Agent Runtime instance already, create an instance.
remote_agent = client.runtimes.create()

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

Remplacez les éléments suivants :

Répertorier les sessions

Répertoriez 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 d'Agent Platform.

    Accéder à la page "Déploiements"

    Les instances Agent Engine faisant partie du projet sélectionné apparaissent dans la liste. Vous pouvez utiliser le champ Filtrer pour filtrer la liste en fonction de la colonne spécifiée.

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

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

Python 

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

# To list sessions for a specific user:
for session in client.sessions.list(
    name=remote_agent.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

Par défaut, client.sessions.list renvoie les sessions triées par heure de création dans l'ordre décroissant (create_time desc). Cet ordre par défaut maintient la pagination stable lorsque les sessions actives sont mises à jour simultanément. Le SDK Python n'expose pas d'option order_by. Pour trier les résultats selon un autre champ, utilisez l'API REST.

REST

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

  • PROJECT_ID : ID du 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.

Vous pouvez également lister les sessions d'un utilisateur spécifique en ajoutant le paramètre de requête ?filter=user_id=\"USER_ID\", où USER_ID est l'ID de l'utilisateur que vous souhaitez interroger.

Pour trier les sessions renvoyées, ajoutez le paramètre de requête ?orderBy=ORDER_BY, où ORDER_BY correspond à create_time, update_time ou display_name. Vous pouvez ajouter %20desc pour l'ordre décroissant, par exemple ?orderBy=create_time%20desc. Si vous omettez orderBy, l'API renvoie les sessions triées par create_time desc. Utilisez create_time desc lorsque vous parcourez les sessions lors de mises à jour simultanées afin que les mises à jour ne déplacent pas les sessions au-delà des limites de la page.

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 d'Agent Platform.

    Accéder à la page "Déploiements"

    Les instances Agent Engine faisant partie du projet sélectionné apparaissent dans la liste. Vous pouvez utiliser le champ Filtrer pour filtrer la liste en fonction de la colonne spécifiée.

  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.sessions.create(
    name=remote_agent.api_resource.name,  # Required
    user_id=USER_ID, # Required
    session_id=SESSION_ID,
)

où USER_ID est 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'à 9 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 du 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 conflits 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'à 9 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 création de votre session.

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

Toutes les sessions doivent avoir un délai d'expiration. Vous pouvez définir ce délai d'expiration lors de la création ou de la mise à jour d'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 définir la durée de vie (ttl) en secondes. Si aucune de ces valeurs n'est spécifiée, le système applique une valeur TTL par défaut de 365 jours.

Valeur TTL

Si vous définissez la valeur TTL, 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.sessions.create(
    name=remote_agent.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.sessions.create(
    name=remote_agent.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

Récupérez 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 d'Agent Platform.

    Accéder à la page "Déploiements"

    Les instances Agent Engine faisant partie du projet sélectionné apparaissent dans la liste. Vous pouvez utiliser le champ Filtrer pour filtrer la liste en fonction de la colonne spécifiée.

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

  3. Cliquez sur l'onglet Playground.

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

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

Python 

session = client.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 du 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

La réponse doit contenir 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 d'Agent Platform.

    Accéder à la page "Déploiements"

    Les instances Agent Engine faisant partie du projet sélectionné apparaissent dans la liste. Vous pouvez utiliser le champ Filtrer pour filtrer la liste en fonction de la colonne spécifiée.

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

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

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

  5. Cliquez sur Supprimer.

  6. Cliquez sur Supprimer la session.

Python 

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

REST

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

  • PROJECT_ID : ID du 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

Répertoriez 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 d'Agent Platform.

    Accéder à la page "Déploiements"

    Les instances Agent Engine faisant partie du projet sélectionné apparaissent dans la liste. Vous pouvez utiliser le champ Filtrer pour filtrer la liste en fonction de la colonne spécifiée.

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

  3. Cliquez sur l'onglet Playground.

  4. Cliquez sur l'onglet Sessions. La 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.sessions.events.list(
    name=session.name,
):
    print(session_event)

REST

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

  • PROJECT_ID : ID du 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 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 d'Agent Platform.

    Accéder à la page "Déploiements"

    Les instances Agent Engine faisant partie du projet sélectionné apparaissent dans la liste. Vous pouvez utiliser le champ Filtrer pour filtrer la liste en fonction de la colonne spécifiée.

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

  3. Cliquez sur l'onglet Playground.

  4. Cliquez sur l'onglet Sessions. La 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.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'agent ou pour stocker des données d'événement personnalisées.

client.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 du 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 conflits 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'à 9 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 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 :

remote_agent.delete(force=True)