Esta seção descreve como usar as sessões do mecanismo do agente da Vertex AI para gerenciar sessões usando chamadas de API diretas. É possível fazer chamadas de API diretas se você não quiser usar um agente do ADK para gerenciar sessões.
Para gerenciar sessões usando o agente do ADK, consulte Gerenciar sessões com o Kit de desenvolvimento de agentes.
Criar uma instância do Vertex AI Agent Engine
Para acessar as sessões do Vertex AI Agent Engine, use uma instância do Vertex AI Agent Engine. Não é necessário implantar nenhum código para começar a usar as Sessões. Sem a implantação de código, a criação de uma instância do Vertex AI Agent Engine leva apenas alguns segundos.
Se você não tiver uma instância do Vertex AI Agent Engine, crie uma usando este código:
import vertexai
from vertexai import agent_engines
# Create an agent engine instance
agent_engine = agent_engines.create()
Listar sessões
Liste todas as sessões associadas à sua instância do Vertex AI Agent Engine.
API REST
Use o método sessions.list.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto.
- LOCATION: a região em que você criou a instância do mecanismo do agente. A única região com suporte é
us-central1. - AGENT_ENGINE_ID: o ID do recurso da instância do Agente Engine.
Método HTTP e URL:
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions
Para enviar a solicitação, escolha uma destas opções:
curl
execute o seguinte 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
Execute o seguinte 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
Uma lista de sessões será retornada.
Criar uma sessão
Crie uma sessão associada a um ID do usuário.
API REST
Use o método sessions.create.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto.
- LOCATION: a região em que você criou a instância do mecanismo do agente. A única região com suporte é
us-central1. - AGENT_ENGINE_ID: o ID do recurso da instância do Agente Engine.
- USER_ID: um ID de usuário
Método HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions
Corpo JSON da solicitação:
{
"userId": USER_ID
}
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:
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
Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:
$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
Você vai receber uma operação de longa duração que pode ser consultada para verificar o status de criação da sessão.
Acessar uma sessão
Receba uma sessão específica associada à sua instância do Vertex AI Agent Engine.
API REST
Use o método sessions.get.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto.
- LOCATION: a região em que você criou a instância do mecanismo do agente. A única região com suporte é
us-central1. - AGENT_ENGINE_ID: o ID do recurso da instância do Agente Engine.
- SESSION_ID: o ID do recurso da sessão que você quer recuperar. Você pode receber o ID da sessão na resposta que recebeu ao criar a sessão.
Método HTTP e URL:
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID
Para enviar a solicitação, escolha uma destas opções:
curl
execute o seguinte 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
Execute o seguinte 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
Na resposta, você vai encontrar informações sobre sua sessão.
Excluir uma sessão
Exclua uma sessão associada à sua instância do Vertex AI Agent Engine.
API REST
Use o método sessions.delete.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto.
- LOCATION: a região em que você quer criar a instância da loja
de exemplo. A única região com suporte é
us-central1. - AGENT_ENGINE_ID: o ID do recurso da instância do Agente Engine.
- SESSION_ID: o ID do recurso da sessão que você quer recuperar.
Método HTTP e URL:
DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/sessions/SESSION_ID
Para enviar a solicitação, escolha uma destas opções:
curl
execute o seguinte comando:
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/sessions/SESSION_ID"
PowerShell
execute o seguinte 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/sessions/SESSION_ID" | Select-Object -Expand Content
Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.
Listar eventos em uma sessão
Listar eventos em uma sessão associada à sua instância do Vertex AI Agent Engine.
API REST
Use o método events.list.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto.
- LOCATION: a região em que você criou a instância do mecanismo do agente. A única região com suporte é
us-central1. - AGENT_ENGINE_ID: o ID do recurso da instância do Agente Engine.
- SESSION_ID: o ID do recurso da sessão que você quer recuperar.
Método HTTP e URL:
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID/events
Para enviar a solicitação, escolha uma destas opções:
curl
execute o seguinte 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
Execute o seguinte 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
Na resposta, você vai encontrar uma lista de eventos associados à sua sessão.
Anexar um evento a uma sessão
Anexe um evento a uma sessão associada a uma instância do Vertex AI Agent Engine.
API REST
Use o método sessions.appendEvent.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto.
- LOCATION: a região em que você criou a instância do mecanismo do agente. A única região com suporte é
us-central1. - AGENT_ENGINE_ID: o ID do recurso da instância do Agente Engine.
- SESSION_ID: o ID do recurso da sessão a que você quer anexar eventos.
- AUTHOR: o autor do evento. Pode ser
'user'ou um nome de agente. - INVOCATION_ID: um identificador de uma invocação.
- TIMESTAMP: o carimbo de data/hora do evento.
Método HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID
Corpo JSON da solicitação:
{
"author": AUTHOR,
"invocationId": INVOCATION_ID,
"timestamp": TIMESTAMP,
}
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:
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"
PowerShell
Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:
$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" | Select-Object -Expand Content
Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.