Administra sesiones con la consola de Google Cloud o llamadas a la API

En esta sección, se describe cómo usar Agent Platform Sessions para administrar sesiones con la consola de Google Cloud o llamadas directas a la API. Puedes usar la consola de Google Cloud o las llamadas directas a la API si no quieres usar un agente de ADK para administrar las sesiones.

Para administrar sesiones con el agente del ADK, consulta Administra sesiones con el Kit de desarrollo de agentes.

Crea una instancia de Agent Runtime

Para acceder a las sesiones de Agent Platform, primero debes usar una instancia de Agent Runtime. No es necesario que implementes ningún código para comenzar a usar las sesiones. Si ya usaste Agent Engine, la creación de una instancia de Agent Runtime solo lleva unos segundos sin la implementación de código. Puede tardar más si es la primera vez que usas Agent Engine.

Si no tienes una instancia existente de Agent Runtime, crea una con el siguiente código:

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)

Reemplaza lo siguiente:

  • PROJECT_ID: ID del proyecto
  • LOCATION: Tu región. Consulta las regiones admitidas para las Sesiones.

Enumera sesiones

Enumera las sesiones asociadas con tu instancia de Agent Runtime.

Console

En el caso de los agentes implementados, puedes usar la consola Google Cloud para enumerar las sesiones asociadas con tu agente:

  1. En la Google Cloud consola, ve a la página Implementaciones de la Agent Platform.

    Ir a Implementaciones

    Las instancias de Agent Engine que forman parte del proyecto seleccionado aparecen en la lista. Puedes usar el campo Filtro para filtrar la lista según la columna que especifiques.

  2. Haz clic en el nombre de tu instancia de Agent Engine.

  3. Haz clic en la pestaña Sesiones. Se mostrará una lista de sesiones por 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: Elige tu propio ID de usuario con un límite de 128 caracteres. Por ejemplo, user-123

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: ID del proyecto
  • LOCATION: Es la región en la que creaste tu instancia de Agent Engine.
  • AGENT_ENGINE_ID: Es el ID de recurso de tu instancia de Agent Engine.

Método HTTP y URL:

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

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el siguiente comando:

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

Ejecuta el siguiente comando:

$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

Deberías ver una lista de las sesiones devueltas.

De manera opcional, para enumerar las sesiones de un usuario específico, puedes agregar el parámetro de consulta ?filter=user_id=\"USER_ID\", en el que USER_ID es el ID del usuario sobre el que deseas realizar la consulta.

Crea una sesión

Crea una sesión asociada a un ID de usuario.

Console

En el caso de los agentes implementados, puedes usar la consola Google Cloud para crear sesiones:

  1. En la Google Cloud consola, ve a la página Implementaciones de la Agent Platform.

    Ir a Implementaciones

    Las instancias de Agent Engine que forman parte del proyecto seleccionado aparecen en la lista. Puedes usar el campo Filtro para filtrar la lista según la columna que especifiques.

  2. Haz clic en el nombre de tu instancia de Agent Engine.

  3. Haz clic en la pestaña Playground.

  4. Haz clic en Nueva sesión para crear una sesión nueva.

Python

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

donde USER_ID es el ID de usuario que definiste. Por ejemplo, user-123.

En el caso de SESSION_ID, ten en cuenta las siguientes restricciones para evitar colisiones con los IDs generados por el sistema:

  • Si el primer carácter es una letra, el ID puede tener hasta 63 caracteres. Los caracteres válidos son letras minúsculas, números y guiones ([a-z0-9-]). El último carácter debe ser una letra o un número.
  • Si el primer carácter es un número, el ID puede tener hasta 9 caracteres. Los caracteres válidos son números ([0-9]) sin ceros iniciales.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: ID del proyecto
  • LOCATION: Es la región en la que creaste tu instancia de Agent Engine.
  • AGENT_ENGINE_ID: Es el ID de recurso de tu instancia de Agent Engine.
  • USER_ID: Es el ID de usuario que definiste. Por ejemplo, sessions-agent.
  • SESSION_ID: Es el ID de sesión que definiste. Por ejemplo:my-custom-session

    Para evitar conflictos con los IDs generados por el sistema, sigue estas restricciones cuando especifiques un ID de sesión personalizado:

    • Si el primer carácter es una letra, el ID puede tener hasta 63 caracteres. Los caracteres válidos son letras en minúscula, números y guiones (`[a-z0-9-]`). El último carácter debe ser una letra o un número.
    • Si el primer carácter es un número, el ID puede tener hasta 9 caracteres. Los caracteres válidos son números (`[0-9]`) sin ceros iniciales.

    Método HTTP y URL:

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

    Cuerpo JSON de la solicitud:

    {
      "userId": USER_ID
    }
    
    

    Para enviar tu solicitud, elige una de estas opciones:

    curl

    Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

    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

    Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

    $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

    Deberías recibir una operación de larga duración que puedes consultar para verificar el estado de creación de tu sesión.

Configura el tiempo de actividad (TTL) de la sesión

Todas las sesiones deben tener una fecha y hora de vencimiento, que puedes definir cuando creas o actualizas una sesión. La sesión y sus eventos secundarios se borran automáticamente después de que transcurre la fecha y hora de vencimiento. Puedes establecer la fecha y hora de vencimiento (expire_time) directamente o establecer el tiempo de actividad (ttl) en segundos. Si no se especifica ninguno de los dos, el sistema aplica un TTL predeterminado de 365 días.

Tiempo de actividad

Si estableces el tiempo de actividad (TTL), el servidor calcula la fecha de vencimiento como create_time + ttl para las sesiones recién creadas o update_time + ttl para las sesiones actualizadas.

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

Hora de vencimiento

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),
    }
)

Obtén una sesión

Obtén una sesión específica asociada con tu instancia de Agent Platform.

Console

En el caso de los agentes implementados, puedes usar la consola Google Cloud para crear sesiones:

  1. En la Google Cloud consola, ve a la página Implementaciones de la Agent Platform.

    Ir a Implementaciones

    Las instancias de Agent Engine que forman parte del proyecto seleccionado aparecen en la lista. Puedes usar el campo Filtro para filtrar la lista según la columna que especifiques.

  2. Haz clic en el nombre de tu instancia de Agent Engine.

  3. Haz clic en la pestaña Playground.

  4. Haz clic en la pestaña Sesiones. Se mostrará una lista de sesiones por ID.

  5. Haz clic en la sesión que deseas ver con más detalle.

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

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: ID del proyecto
  • LOCATION: Es la región en la que creaste tu instancia de Agent Engine.
  • AGENT_ENGINE_ID: Es el ID de recurso de tu instancia de Agent Engine.
  • SESSION_ID: Es el ID del recurso de la sesión que deseas recuperar. Puedes obtener el ID de sesión de la respuesta que recibiste cuando creaste la sesión.

Método HTTP y URL:

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

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el siguiente comando:

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

Ejecuta el siguiente comando:

$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

En la respuesta, deberías ver información sobre tu sesión.

Cómo borrar una sesión

Borra una sesión asociada a tu instancia de Agent Platform.

Console

En el caso de los agentes implementados, puedes usar la consola de Google Cloud para borrar las sesiones asociadas con tu agente:

  1. En la consola de Google Cloud , ve a la página Implementaciones de la Plataforma de agentes.

    Ir a Implementaciones

    Las instancias de Agent Engine que forman parte del proyecto seleccionado aparecen en la lista. Puedes usar el campo Filtro para filtrar la lista según la columna que especifiques.

  2. Haz clic en el nombre de tu instancia de Agent Engine.

  3. Haz clic en la pestaña Sesiones. Se mostrará una lista de sesiones por ID.

  4. Haz clic en el menú más acciones () de la sesión que deseas borrar.

  5. Haz clic en Borrar.

  6. Haz clic en Borrar sesión.

Python

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

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: ID del proyecto
  • LOCATION: Es la región en la que deseas crear la instancia de Example Store.
  • AGENT_ENGINE_ID: Es el ID de recurso de tu instancia de Agent Engine.
  • SESSION_ID: Es el ID del recurso de la sesión que deseas recuperar.

Método HTTP y URL:

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

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el siguiente comando:

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

Ejecuta el siguiente comando:

$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

Deberías recibir un código de estado exitoso (2xx) y una respuesta vacía.

Enumera los eventos de una sesión

Enumera los eventos de una sesión asociada a tu instancia de Agent Platform.

Console

En el caso de los agentes implementados, puedes usar la consola Google Cloud para crear sesiones:

  1. En la Google Cloud consola, ve a la página Implementaciones de la Agent Platform.

    Ir a Implementaciones

    Las instancias de Agent Engine que forman parte del proyecto seleccionado aparecen en la lista. Puedes usar el campo Filtro para filtrar la lista según la columna que especifiques.

  2. Haz clic en el nombre de tu instancia de Agent Engine.

  3. Haz clic en la pestaña Playground.

  4. Haz clic en la pestaña Sesiones. Se mostrará una lista de sesiones por ID.

  5. Haz clic en la sesión que deseas ver con más detalle.

  6. Haz clic en la pestaña Eventos para ver los eventos asociados a la sesión.

Python

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

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: ID del proyecto
  • LOCATION: Es la región en la que creaste tu instancia de Agent Engine.
  • AGENT_ENGINE_ID: Es el ID de recurso de tu instancia de Agent Engine.
  • SESSION_ID: Es el ID del recurso de la sesión que deseas recuperar.

Método HTTP y URL:

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

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el siguiente comando:

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

Ejecuta el siguiente comando:

$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

En la respuesta, deberías ver una lista de los eventos asociados a tu sesión.

Agrega un evento a una sesión

Agrega un evento a una sesión asociada con una instancia de Agent Platform.

Console

En el caso de los agentes implementados, puedes usar la consola Google Cloud para crear sesiones:

  1. En la Google Cloud consola, ve a la página Implementaciones de la Agent Platform.

    Ir a Implementaciones

    Las instancias de Agent Engine que forman parte del proyecto seleccionado aparecen en la lista. Puedes usar el campo Filtro para filtrar la lista según la columna que especifiques.

  2. Haz clic en el nombre de tu instancia de Agent Engine.

  3. Haz clic en la pestaña Playground.

  4. Haz clic en la pestaña Sesiones. Se mostrará una lista de sesiones por ID.

  5. Haz clic en la sesión que deseas ver con más detalle.

  6. Haz clic en la pestaña Eventos para ver los eventos asociados a la sesión.

  7. Escribe un mensaje y presiona Intro para agregar un evento nuevo a la sesión.

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"}]
        },
    },
)

Como alternativa, puedes usar el campo raw_event para incluir datos arbitrarios en los eventos de sesión. Esto es útil para la interoperabilidad con otros frameworks de agentes o para almacenar datos de eventos personalizados.

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

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: ID del proyecto
  • LOCATION: Es la región en la que creaste tu instancia de Agent Engine.
  • AGENT_ENGINE_ID: Es el ID de recurso de tu instancia de Agent Engine.
  • USER_ID: Es el ID de usuario que definiste. Por ejemplo, sessions-agent.
  • SESSION_ID: Es el ID de sesión que definiste. Por ejemplo:my-custom-session

    Para evitar conflictos con los IDs generados por el sistema, sigue estas restricciones cuando especifiques un ID de sesión personalizado:

    • Si el primer carácter es una letra, el ID puede tener hasta 63 caracteres. Los caracteres válidos son letras en minúscula, números y guiones (`[a-z0-9-]`). El último carácter debe ser una letra o un número.
    • Si el primer carácter es un número, el ID puede tener hasta 9 caracteres. Los caracteres válidos son números (`[0-9]`) sin ceros iniciales.

    Método HTTP y URL:

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

    Cuerpo JSON de la solicitud:

    {
      "userId": USER_ID
    }
    
    

    Para enviar tu solicitud, elige una de estas opciones:

    curl

    Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

    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

    Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

    $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

    Deberías recibir una operación de larga duración que puedes consultar para verificar el estado de creación de tu sesión.

Realiza una limpieza

Para limpiar todos los recursos que se usaron en este proyecto, puedes borrar la instancia de Agent Platform junto con sus recursos secundarios:

agent_engine.delete(force=True)