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:

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)