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:
- En la Google Cloud consola, ve a la página Implementaciones de la Agent Platform.
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.
Haz clic en el nombre de tu instancia de Agent Engine.
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:
- En la Google Cloud consola, ve a la página Implementaciones de la Agent Platform.
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.
Haz clic en el nombre de tu instancia de Agent Engine.
Haz clic en la pestaña Playground.
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-sessionPara 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.jsony 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.jsony 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 ContentDeberí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:
- En la Google Cloud consola, ve a la página Implementaciones de la Agent Platform.
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.
Haz clic en el nombre de tu instancia de Agent Engine.
Haz clic en la pestaña Playground.
Haz clic en la pestaña Sesiones. Se mostrará una lista de sesiones por ID.
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:
- En la consola de Google Cloud , ve a la página Implementaciones de la Plataforma de agentes.
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.
Haz clic en el nombre de tu instancia de Agent Engine.
Haz clic en la pestaña Sesiones. Se mostrará una lista de sesiones por ID.
Haz clic en el menú más acciones () de la sesión que deseas borrar.
Haz clic en Borrar.
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:
- En la Google Cloud consola, ve a la página Implementaciones de la Agent Platform.
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.
Haz clic en el nombre de tu instancia de Agent Engine.
Haz clic en la pestaña Playground.
Haz clic en la pestaña Sesiones. Se mostrará una lista de sesiones por ID.
Haz clic en la sesión que deseas ver con más detalle.
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:
- En la Google Cloud consola, ve a la página Implementaciones de la Agent Platform.
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.
Haz clic en el nombre de tu instancia de Agent Engine.
Haz clic en la pestaña Playground.
Haz clic en la pestaña Sesiones. Se mostrará una lista de sesiones por ID.
Haz clic en la sesión que deseas ver con más detalle.
Haz clic en la pestaña Eventos para ver los eventos asociados a la sesión.
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-sessionPara 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.jsony 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.jsony 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 ContentDeberí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)