En esta sección, se describe cómo usar las sesiones de Vertex AI Agent Engine 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 Vertex AI Agent Engine
Para acceder a las sesiones de Vertex AI Agent Engine, primero debes usar una instancia de Vertex AI Agent Engine. No es necesario que implementes ningún código para comenzar a usar Sessions. Si ya usaste Agent Engine, crear una instancia de Vertex AI Agent Engine solo lleva unos segundos sin necesidad de implementar código. El proceso puede tardar más si es la primera vez que usas Agent Engine.
Si no tienes una instancia existente de Vertex AI Agent Engine, 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 Vertex AI Agent Engine.
Consola de Google Cloud
En el caso de los agentes implementados, puedes usar la consola de Google Cloud para enumerar las sesiones asociadas con tu agente:
- En la consola de Google Cloud , ve a la página Vertex AI Agent Engine.
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.
SDK de Vertex AI para 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.
Consola de Google Cloud
En el caso de los agentes implementados, puedes usar la Google Cloud consola para crear sesiones:
- En la consola de Google Cloud , ve a la página Vertex AI Agent Engine.
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.
SDK de Vertex AI para Python
session = client.agent_engines.sessions.create(
name=agent_engine.api_resource.name, # Required
user_id=USER_ID, # Required
)
donde USER_ID es el ID de usuario que definiste. 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.
- USER_ID: Es el ID de usuario que definiste. Por ejemplo,
sessions-agent
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.
Obtén una sesión
Obtén una sesión específica asociada a tu instancia de Vertex AI Agent Engine.
Consola de Google Cloud
En el caso de los agentes implementados, puedes usar la Google Cloud consola para crear sesiones:
- En la consola de Google Cloud , ve a la página Vertex AI Agent Engine.
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.
SDK de Vertex AI para 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 Vertex AI Agent Engine.
Consola de Google Cloud
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 Vertex AI Agent Engine.
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.
SDK de Vertex AI para 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 con tu instancia de Vertex AI Agent Engine.
Consola de Google Cloud
En el caso de los agentes implementados, puedes usar la consola Google Cloud para crear sesiones:
- En la consola de Google Cloud , ve a la página Vertex AI Agent Engine.
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.
SDK de Vertex AI para 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.
Cómo agregar un evento a una sesión
Agrega un evento a una sesión asociada con una instancia de Vertex AI Agent Engine.
Consola de Google Cloud
En el caso de los agentes implementados, puedes usar la Google Cloud consola para crear sesiones:
- En la consola de Google Cloud , ve a la página Vertex AI Agent Engine.
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.
SDK de Vertex AI para 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"}]
},
},
)
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 a la que deseas agregar eventos.
- AUTHOR: Es el autor del evento. Puede ser
'user'o el nombre de un agente. - INVOCATION_ID: Es el identificador de una invocación.
- TIMESTAMP: Es la marca de tiempo del evento.
Método HTTP y URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID:appendEvent
Cuerpo JSON de la solicitud:
{
"author": AUTHOR,
"invocationId": INVOCATION_ID,
"timestamp": TIMESTAMP,
}
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/SESSION_ID:appendEvent"
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/SESSION_ID:appendEvent" | Select-Object -Expand Content
Deberías recibir un código de estado exitoso (2xx) y una respuesta vacía.
Realiza una limpieza
Para limpiar todos los recursos que se usan en este proyecto, puedes borrar la instancia de Vertex AI Agent Engine junto con sus recursos secundarios:
agent_engine.delete(force=True)