Nesta seção, descrevemos como usar as sessões do mecanismo de agente da Vertex AI para gerenciar sessões usando chamadas diretas de API. É 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 Agent Development Kit.
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 implantação de código, criar 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 o seguinte 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 Agent Engine.
- AGENT_ENGINE_ID: O ID do recurso da sua instância do Agent 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 vai aparecer.
Criar uma sessão
Crie uma sessão associada a um ID de 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 Agent Engine.
- AGENT_ENGINE_ID: O ID do recurso da sua instância do Agent 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 sua sessão.
Acessar uma sessão
Recebe 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 Agent Engine.
- AGENT_ENGINE_ID: O ID do recurso da sua instância do Agent 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 Example Store.
- AGENT_ENGINE_ID: O ID do recurso da sua instância do Agent 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
Liste os 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 Agent Engine.
- AGENT_ENGINE_ID: O ID do recurso da sua instância do Agent 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
Adiciona 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 Agent Engine.
- AGENT_ENGINE_ID: O ID do recurso da sua instância do Agent Engine.
- SESSION_ID: o ID do recurso da sessão a que você quer adicionar 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.