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

Nesta seção, descrevemos como usar as sessões do Agent Platform para gerenciar sessões usando o console Google Cloud ou chamadas diretas da 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 Agent Runtime

Para acessar as sessões da plataforma de agentes, primeiro use uma instância do ambiente de execução de agentes. 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 Agent Runtime 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 Agent Runtime, 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

Lista as sessões associadas à sua instância do Agent Runtime.

Console

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

  1. No Google Cloud console, acesse a página Implantações do Agent Platform.

    Acessar "Implantações"

    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.

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

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

  1. No Google Cloud console, acesse a página Implantações do Agent Platform.

    Acessar "Implantações"

    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.

Python 

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

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

Para SESSION_ID, considere as seguintes restrições para evitar colisões com IDs gerados pelo sistema:

  • Se o primeiro caractere for uma letra, o ID poderá ter até 63 caracteres. Os caracteres válidos são letras minúsculas, números e hífens ([a-z0-9-]). O último caractere precisa ser uma letra ou um número.
  • Se o primeiro caractere for um número, o ID poderá ter até nove caracteres. Os caracteres válidos são números ([0-9]) sem zeros à esquerda.

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.
  • SESSION_ID: o ID da sessão que você definiu. Por exemplo, my-custom-session.

    Para evitar colisões com IDs gerados pelo sistema, siga estas restrições ao especificar um ID de sessão personalizado:

    • Se o primeiro caractere for uma letra, o ID poderá ter até 63 caracteres. Os caracteres válidos são letras minúsculas, números e hifens (`[a-z0-9-]`). O último caractere precisa ser uma letra ou um número.
    • Se o primeiro caractere for um número, o ID poderá ter até nove caracteres. Os caracteres válidos são números (`[0-9]`) sem zeros à esquerda.

    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.

Configurar time to live (TTL) da sessão

Todas as sessões precisam ter um tempo de expiração. É possível definir esse prazo de validade ao criar ou atualizar uma sessão. A sessão e os eventos filhos são excluídos automaticamente após o período de expiração. É possível definir o prazo de validade (expire_time) diretamente ou definir o tempo de vida (ttl) em segundos. Se nenhum for especificado, o sistema vai aplicar um TTL padrão de 365 dias.

Time to live (TTL)

Se você definir o tempo de vida, o servidor vai calcular o prazo de validade como create_time + ttl para sessões recém-criadas ou update_time + ttl para sessões atualizadas.

client.agent_engines.sessions.create(
    name=agent_engine.api_resource.name,  # Required
    user_id=USER_ID, # Required
    config={
        # Session will be deleted 10 days after creation time.
        "ttl": f"{24 * 60 * 60 * 10}s"
    }
)

Tempo de expiração 

import datetime

client.agent_engines.sessions.create(
    name=agent_engine.api_resource.name,  # Required
    user_id=USER_ID, # Required
    config={
        # Session will be deleted at the provided time (10 days after current time).
        "expire_time": datetime.datetime.now(tz=datetime.timezone.utc) + datetime.timedelta(seconds=24 * 60 * 60 * 10),
    }
)

Acessar uma sessão

Receba uma sessão específica associada à sua instância da Agent Platform.

Console

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

  1. No Google Cloud console, acesse a página Implantações do Agent Platform.

    Acessar "Implantações"

    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.

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 da Agent Platform.

Console

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

  1. No console Google Cloud , acesse a página Implantações do Agent Platform.

    Acessar "Implantações"

    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.

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 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 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 Agent Platform.

Console

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

  1. No console Google Cloud , acesse a página Implantações do Agent Platform.

    Acessar "Implantações"

    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.

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 da plataforma do agente.

Console

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

  1. No Google Cloud console, acesse a página Implantações do Agent Platform.

    Acessar "Implantações"

    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.

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"}]
        },
    },
)

Como alternativa, use o campo raw_event para incluir dados arbitrários em eventos de sessão. Isso é útil para interoperabilidade com outras estruturas de agentes ou para armazenar dados de eventos personalizados.

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={
        "raw_event": {
            "content": "hello",
            "custom_field": "custom_value"
        },
    },
)

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.
  • SESSION_ID: o ID da sessão que você definiu. Por exemplo, my-custom-session.

    Para evitar colisões com IDs gerados pelo sistema, siga estas restrições ao especificar um ID de sessão personalizado:

    • Se o primeiro caractere for uma letra, o ID poderá ter até 63 caracteres. Os caracteres válidos são letras minúsculas, números e hifens (`[a-z0-9-]`). O último caractere precisa ser uma letra ou um número.
    • Se o primeiro caractere for um número, o ID poderá ter até nove caracteres. Os caracteres válidos são números (`[0-9]`) sem zeros à esquerda.

    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.

Limpar

Para limpar todos os recursos usados neste projeto, exclua a instância da Agent Platform e os recursos filhos dela:

agent_engine.delete(force=True)