Gerenciar sessões usando o console do Google Cloud ou chamadas de API

Nesta seção, descrevemos como usar as sessões do Vertex AI Agent Engine para gerenciar sessões usando o console Google Cloud ou chamadas diretas de API. É possível usar o console Google Cloud ou chamadas diretas de API se 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 Agente.

Criar uma instância do Vertex AI Agent Engine

Para acessar as sessões do Vertex AI Agent Engine, primeiro você precisa usar uma instância do Vertex AI Agent Engine. Não é necessário implantar nenhum código para começar a usar as sessões. Se você já usou o Agent Engine, criar uma instância do Vertex AI Agent Engine leva apenas alguns segundos sem implantação de código. Isso pode levar mais tempo se for a primeira vez que você usa o Agent Engine.

Se você não tiver uma instância do Vertex AI Agent Engine, crie uma usando o seguinte 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)

Substitua:

Listar sessões

Liste as sessões associadas à sua instância do Vertex AI Agent Engine.

Console do Google Cloud

Para agentes implantados, use o console Google Cloud para listar as sessões associadas ao seu agente:

  1. No console do Google Cloud , acesse a página Vertex AI Agent Engine.

    Acessar o Agent Engine

    As instâncias do Agent Engine que fazem parte do projeto selecionado aparecem na lista. Use o campo Filtro para filtrar a lista pela coluna especificada.

  2. Clique no nome da sua instância do Agent Engine.

  3. Clique na guia Sessões. Uma lista de sessões é exibida por ID.

SDK da 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: escolha seu próprio ID de usuário com um limite de 128 caracteres. Por exemplo, user-123.

REST

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.

Se quiser listar as sessões de um usuário específico, adicione o parâmetro de consulta ?filter=user_id=\"USER_ID\", em que USER_ID é o ID do usuário que você quer consultar.

Criar uma sessão

Crie uma sessão associada a um ID de usuário.

Console do Google Cloud

Para agentes implantados, use o console do Google Cloud para criar sessões:

  1. No console do Google Cloud , acesse a página Vertex AI Agent Engine.

    Acessar o Agent Engine

    As instâncias do Agent Engine que fazem parte do projeto selecionado aparecem na lista. Use o campo Filtro para filtrar a lista pela coluna especificada.

  2. Clique no nome da sua instância do Agent Engine.

  3. Clique na guia Playground.

  4. Clique em Nova sessão para criar uma sessão.

SDK da Vertex AI para Python 

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

em que USER_ID é o ID do usuário que você definiu. Por exemplo, user-123.

REST

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: o ID do usuário que você definiu. Por exemplo, sessions-agent.

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 abaixo: 

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 abaixo: 

$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.

Console do Google Cloud

Para agentes implantados, use o console do Google Cloud para criar sessões:

  1. No console do Google Cloud , acesse a página Vertex AI Agent Engine.

    Acessar o Agent Engine

    As instâncias do Agent Engine que fazem parte do projeto selecionado aparecem na lista. Use o campo Filtro para filtrar a lista pela coluna especificada.

  2. Clique no nome da sua instância do Agent Engine.

  3. Clique na guia Playground.

  4. Clique na guia Sessões. Uma lista de sessões é exibida por ID.

  5. Clique na sessão que você quer ver em mais detalhes.

SDK da 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 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.

Console do Google Cloud

Para agentes implantados, use o console Google Cloud para excluir sessões associadas ao seu agente:

  1. No console do Google Cloud , acesse a página Vertex AI Agent Engine.

    Acessar o Agent Engine

    As instâncias do Agent Engine que fazem parte do projeto selecionado aparecem na lista. Use o campo Filtro para filtrar a lista pela coluna especificada.

  2. Clique no nome da sua instância do Agent Engine.

  3. Clique na guia Sessões. Uma lista de sessões é exibida por ID.

  4. Clique no menu Mais ações () da sessão que você quer excluir.

  5. Clique em Excluir.

  6. Clique em Excluir sessão.

SDK da Vertex AI para Python 

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

REST

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/reasoningEngines/AGENT_ENGINE_ID/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/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 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

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.

Console do Google Cloud

Para agentes implantados, use o console do Google Cloud para criar sessões:

  1. No console do Google Cloud , acesse a página Vertex AI Agent Engine.

    Acessar o Agent Engine

    As instâncias do Agent Engine que fazem parte do projeto selecionado aparecem na lista. Use o campo Filtro para filtrar a lista pela coluna especificada.

  2. Clique no nome da sua instância do Agent Engine.

  3. Clique na guia Playground.

  4. Clique na guia Sessões. Uma lista de sessões é exibida por ID.

  5. Clique na sessão que você quer ver em mais detalhes.

  6. Clique na guia Eventos para ver os eventos associados à sessão.

SDK da Vertex AI para Python 

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

REST

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.

Console do Google Cloud

Para agentes implantados, use o console do Google Cloud para criar sessões:

  1. No console do Google Cloud , acesse a página Vertex AI Agent Engine.

    Acessar o Agent Engine

    As instâncias do Agent Engine que fazem parte do projeto selecionado aparecem na lista. Use o campo Filtro para filtrar a lista pela coluna especificada.

  2. Clique no nome da sua instância do Agent Engine.

  3. Clique na guia Playground.

  4. Clique na guia Sessões. Uma lista de sessões é exibida por ID.

  5. Clique na sessão que você quer ver em mais detalhes.

  6. Clique na guia Eventos para ver os eventos associados à sessão.

  7. Digite uma mensagem e pressione Enter para adicionar um novo evento à sessão.

SDK da 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 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:appendEvent

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 abaixo: 

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

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:appendEvent" | Select-Object -Expand Content

Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.

Limpar

Para limpar todos os recursos usados neste projeto, exclua a instância do mecanismo de agente da Vertex AI e os recursos filhos dela:

agent_engine.delete(force=True)