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

Nesta seção, descrevemos como usar as sessões da Agent Platform para gerenciar sessões usando o console do Google Cloud ou chamadas de API diretas. Você pode usar o console do Google Cloud ou chamadas de API diretas 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 (ADK).

Criar uma instância do Agent Runtime

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

Se você não tiver uma instância do Agent Runtime, crie uma usando o seguinte código:

import agentplatform

client = agentplatform.Client(
  project="PROJECT_ID",
  location="LOCATION"
)
# If you don't have an Agent Runtime instance already, create an instance.
remote_agent = client.runtimes.create()

# Optionally, print out the Agent Runtime resource name. You will need the
# resource name to interact with Sessions later on.
print(remote_agent.api_resource.name)

Substitua:

Opções de segurança multirregionais, globais e corporativas

As sessões são compatíveis com endpoints regionais, multirregionais (us e eu) e globais (global). Lembre-se dos seguintes requisitos de segurança e criptografia ao escolher um local e criar sua instância:

  • Chaves de criptografia gerenciadas pelo cliente (CMEK): não é possível usar CMEK se a instância de sessões estiver configurada para usar o endpoint global (location="global"), porque o Cloud Key Management Service (Cloud KMS) exige que as chaves de criptografia residam em um limite geográfico de residência de dados. Para criptografar dados de sessão com uma chave do Cloud KMS, crie uma instância pai independente (sem implantar o código do ambiente de execução do agente) em um local regional ou multirregional compatível (us com uma chave us ou eu com uma chave europe) e transmita encryption_spec ao criar a instância pai. As instâncias que também implantam um agente no Agent Runtime são compatíveis com CMEK apenas em locais de região única. Para mais detalhes, consulte CMEK para sessões.
  • VPC Service Controls (VPC Service Controls): para proteger seus recursos de sessões dentro de um perímetro de serviço ou rotear o tráfego de sessões pelo Gateway de Agente, consulte VPC Service Controls para sessões.

Listar sessões

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

Console

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

  1. No console do Google Cloud , acesse a página Implantações da plataforma de agentes.

    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 instância do Agent Engine.

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

Python 

for session in client.sessions.list(
    name=remote_agent.api_resource.name,  # Required
):
    print(session)

# To list sessions for a specific user:
for session in client.sessions.list(
    name=remote_agent.api_resource.name,  # Required
    config={"filter": "user_id=USER_ID"},
):
    print(session)
  • USER_ID: escolha seu próprio ID do usuário com um limite de 128 caracteres. Por exemplo, user-123.

Por padrão, client.sessions.list retorna sessões classificadas por horário de criação em ordem decrescente (create_time desc). Essa ordem padrão mantém a paginação estável quando as sessões ativas são atualizadas simultaneamente. O SDK do Python não expõe uma opção order_by. Para classificar por um campo diferente, use a API REST.

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

Você verá uma lista de sessões retornadas.

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.

Para classificar as sessões retornadas, adicione o parâmetro de consulta ?orderBy=ORDER_BY, em que ORDER_BY é create_time, update_time ou display_name. É possível anexar %20desc para ordem decrescente, como ?orderBy=create_time%20desc. Se você omitir orderBy, a API vai retornar sessões classificadas por create_time desc. Use create_time desc ao paginar as sessões durante atualizações simultâneas para que as atualizações não mudem as sessões entre os limites da página.

Criar uma sessão

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

Console

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

  1. No console do Google Cloud , acesse a página Implantações da plataforma de agentes.

    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 instância do Agent Engine.

  3. Clique na guia Playground.

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

Python 

session = client.sessions.create(
    name=remote_agent.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 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é 9 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 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 conflitos 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é 9 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 sessão.

Configurar o time to live (TTL) da sessão

Todas as sessões precisam ter um prazo de validade. É 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 tempo 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 time to live, 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.sessions.create(
    name=remote_agent.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.sessions.create(
    name=remote_agent.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

Acessar 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 console do Google Cloud , acesse a página Implantações da plataforma de agentes.

    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 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.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 instância do Agent Engine.
  • SESSION_ID: o ID do recurso da sessão que você quer recuperar. Você pode encontrar 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ê verá 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 do Google Cloud para excluir sessões associadas ao agente:

  1. No console do Google Cloud , acesse a página Implantações da plataforma de agentes.

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

Console

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

  1. No console do Google Cloud , acesse a página Implantações da plataforma de agentes.

    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 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.sessions.events.list(
    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 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ê verá 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 da Agent Platform.

Console

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

  1. No console do Google Cloud , acesse a página Implantações da plataforma de agentes.

    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 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.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 nos eventos de sessão. Isso é útil para interoperabilidade com outros frameworks de agentes ou para armazenar dados de eventos personalizados.

client.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 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 conflitos 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é 9 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 sessão.

Limpar

Para limpar todos os recursos usados neste projeto, exclua a instância da Plataforma de Agentes e os recursos filhos dela:

remote_agent.delete(force=True)