Faça a gestão de sessões através de chamadas diretas à API

Esta secção descreve como usar as sessões do Vertex AI Agent Engine para gerir sessões através de chamadas diretas à API. Pode fazer chamadas diretas à API se não quiser usar um agente ADK para gerir sessões.

Para gerir sessões através do agente ADK, consulte o artigo Gerir sessões com o Agent Development Kit.

Crie uma instância do Vertex AI Agent Engine

Para aceder às sessões do Vertex AI Agent Engine, tem de usar uma instância do Vertex AI Agent Engine. Não precisa de implementar nenhum código para começar a usar as sessões. Sem a implementação de código, a criação de uma instância do Agent Engine do Vertex AI demora apenas alguns segundos.

Se não tiver uma instância do Agent Engine do Vertex AI, crie uma com o seguinte código:

import vertexai

client = vertexai.Client(project=PROJECT, location=LOCATION)
agent_engine = client.agent_engines.create()

Apresentar sessões

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

SDK 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)

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu projeto.
  • LOCATION: a região onde criou a instância do motor do agente.
  • 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 o seu pedido, 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

É apresentada uma lista de sessões devolvidas.

Opcionalmente, para listar sessões de um utilizador específico, pode adicionar o parâmetro de consulta ?filter=user_id=\"USER_ID\", em que USER_ID é o ID do utilizador que quer consultar.

  • USER_ID: escolha o seu próprio ID do utilizador com um limite de 128 carateres. Por exemplo, user-123.

Crie uma sessão

Crie uma sessão associada a um ID do utilizador.

SDK 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 utilizador que definiu. Por exemplo, user-123.

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu projeto.
  • LOCATION: a região onde criou a instância do motor do agente.
  • AGENT_ENGINE_ID: O ID do recurso da sua instância do Agent Engine.
  • USER_ID: o ID do utilizador que 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 do pedido: 

{
  "userId": USER_ID
}

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Deve receber uma operação de longa duração que pode consultar para verificar o estado de criação da sua sessão.

Receba uma sessão

Obtenha uma sessão específica associada à sua instância do Vertex AI Agent Engine.

SDK 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 qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu projeto.
  • LOCATION: a região onde criou a instância do motor do agente.
  • AGENT_ENGINE_ID: O ID do recurso da sua instância do Agent Engine.
  • SESSION_ID: o ID do recurso da sessão que quer obter. Pode obter o ID da sessão a partir da resposta que recebeu quando criou 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 o seu pedido, 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, deve ver informações sobre a sua sessão.

Elimine uma sessão

Elimine uma sessão associada à sua instância do Vertex AI Agent Engine.

SDK Vertex AI para Python 

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

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu projeto.
  • LOCATION: a região onde quer criar a instância da loja de exemplo.
  • AGENT_ENGINE_ID: O ID do recurso da sua instância do Agent Engine.
  • SESSION_ID: o ID do recurso da sessão que quer obter.

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 o seu pedido, 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

Deve receber um código de estado de êxito (2xx) e uma resposta vazia.

Liste eventos numa sessão

Liste eventos numa sessão associada à sua instância do Vertex AI Agent Engine.

SDK Vertex AI para Python 

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

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu projeto.
  • LOCATION: a região onde criou a instância do motor do agente.
  • AGENT_ENGINE_ID: O ID do recurso da sua instância do Agent Engine.
  • SESSION_ID: o ID do recurso da sessão que quer obter.

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 o seu pedido, 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, deve ver uma lista de eventos associados à sua sessão.

Anexe um evento a uma sessão

Anexe um evento a uma sessão associada a uma instância do Vertex AI Agent Engine.

SDK 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 qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu projeto.
  • LOCATION: a região onde criou a instância do motor do agente.
  • AGENT_ENGINE_ID: O ID do recurso da sua instância do Agent Engine.
  • SESSION_ID: o ID de recurso da sessão à qual quer anexar eventos.
  • AUTHOR: o autor do evento. Pode ser 'user' ou o nome de um agente.
  • INVOCATION_ID: um identificador de uma invocação.
  • TIMESTAMP: a 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 do pedido: 

{
  "author": AUTHOR,
  "invocationId": INVOCATION_ID,
  "timestamp": TIMESTAMP,
}

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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"

PowerShell

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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" | Select-Object -Expand Content

Deve receber um código de estado de êxito (2xx) e uma resposta vazia.