Gestisci le sessioni utilizzando la console Google Cloud o le chiamate API

Questa sezione descrive come utilizzare le sessioni di Agent Platform per gestire le sessioni utilizzando la console Google Cloud o le chiamate API dirette. Puoi utilizzare la console Google Cloud o chiamate API dirette se non vuoi utilizzare un agente ADK per gestire le sessioni.

Per gestire le sessioni utilizzando l'agente ADK, consulta Gestire le sessioni con Agent Development Kit.

Crea un'istanza di Agent Runtime

Per accedere alle sessioni di Agent Platform, devi prima utilizzare un'istanza di Agent Runtime. Non è necessario fare il deployment di alcun codice per iniziare a utilizzare le sessioni. Se hai già utilizzato Agent Engine, la creazione di un'istanza di Agent Runtime richiede solo pochi secondi senza il deployment del codice. Potrebbe richiedere più tempo se è la prima volta che utilizzi Agent Engine.

Se non hai un'istanza Agent Runtime esistente, creane una utilizzando il seguente codice:

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)

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto.
  • LOCATION: la tua regione. Consulta le regioni supportate per Sessioni.

Elenco sessioni

Elenca le sessioni associate alla tua istanza di Agent Runtime.

Console

Per gli agenti di cui è stato eseguito il deployment, puoi utilizzare la console Google Cloud per elencare le sessioni associate al tuo agente:

  1. Nella console Google Cloud , vai alla pagina Deployment di Agent Platform.

    Vai a Deployment

    Nell'elenco vengono visualizzate le istanze di Agent Engine che fanno parte del progetto selezionato. Puoi utilizzare il campo Filtra per filtrare l'elenco in base alla colonna specificata.

  2. Fai clic sul nome dell'istanza Agent Engine.

  3. Fai clic sulla scheda Sessioni. Viene visualizzato un elenco di sessioni per 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: scegli il tuo ID utente con un limite di 128 caratteri. Ad esempio, user-123.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto.
  • LOCATION: La regione in cui hai creato l'istanza di Agent Engine.
  • AGENT_ENGINE_ID: L'ID risorsa dell'istanza di Agent Engine.

Metodo HTTP e URL: 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions

Per inviare la richiesta, scegli una di queste opzioni:

curl

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

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

Dovresti visualizzare un elenco delle sessioni restituite.

Se vuoi elencare le sessioni per un utente specifico, puoi aggiungere il parametro di query ?filter=user_id=\"USER_ID\", dove USER_ID è l'ID dell'utente per cui vuoi eseguire la query.

Creare una sessione

Crea una sessione associata a un ID utente.

Console

Per gli agenti di cui è stato eseguito il deployment, puoi utilizzare la console Google Cloud per creare sessioni:

  1. Nella console Google Cloud , vai alla pagina Deployment di Agent Platform.

    Vai a Deployment

    Nell'elenco vengono visualizzate le istanze di Agent Engine che fanno parte del progetto selezionato. Puoi utilizzare il campo Filtra per filtrare l'elenco in base alla colonna specificata.

  2. Fai clic sul nome dell'istanza Agent Engine.

  3. Fai clic sulla scheda Playground.

  4. Fai clic su Nuova sessione per creare una nuova sessione.

Python 

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

dove USER_ID è l'ID utente che hai definito. Ad esempio, user-123.

Per SESSION_ID, tieni presenti le seguenti limitazioni per evitare collisioni con gli ID generati dal sistema:

  • Se il primo carattere è una lettera, l'ID può contenere fino a 63 caratteri. I caratteri validi sono lettere minuscole, numeri e trattini ([a-z0-9-]). L'ultimo carattere deve essere una lettera o un numero
  • Se il primo carattere è un numero, l'ID può contenere fino a 9 caratteri. I caratteri validi sono numeri ([0-9]) senza zeri iniziali.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto.
  • LOCATION: La regione in cui hai creato l'istanza di Agent Engine.
  • AGENT_ENGINE_ID: L'ID risorsa dell'istanza di Agent Engine.
  • USER_ID: l'ID utente che hai definito. Ad esempio, sessions-agent.
  • SESSION_ID: l'ID sessione che hai definito. Ad esempio, my-custom-session.

    Per evitare conflitti con gli ID generati dal sistema, rispetta queste limitazioni quando specifichi un ID sessione personalizzato:

    • Se il primo carattere è una lettera, l'ID può contenere fino a 63 caratteri. I caratteri validi sono lettere minuscole, numeri e trattini (`[a-z0-9-]`). L'ultimo carattere deve essere una lettera o un numero.
    • Se il primo carattere è un numero, l'ID può contenere fino a 9 caratteri. I caratteri validi sono numeri (`[0-9]`) senza zeri iniziali.

    Metodo HTTP e URL: 

    POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions

    Corpo JSON della richiesta: 

    {
  "userId": USER_ID
}

    Per inviare la richiesta, scegli una di queste opzioni:

    curl

    Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

    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

    Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

    $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

    Dovresti ricevere un'operazione a lunga esecuzione che puoi interrogare per controllare lo stato di creazione della sessione.

Configurare la durata (TTL) della sessione

Tutte le sessioni devono avere un tempo di scadenza. Puoi definire questa scadenza quando crei o aggiorni una sessione. La sessione e i relativi eventi secondari vengono eliminati automaticamente dopo la scadenza del periodo di tempo. Puoi impostare direttamente l'ora di scadenza (expire_time) o impostare la durata (ttl) in secondi. Se non viene specificato nessuno dei due, il sistema applica un TTL predefinito di 365 giorni.

Durata

Se imposti il tempo di permanenza, il server calcola la data di scadenza come create_time + ttl per le sessioni appena create o update_time + ttl per le sessioni aggiornate.

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

Scadenza 

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

Recuperare una sessione

Recupera una sessione specifica associata alla tua istanza di Agent Platform.

Console

Per gli agenti di cui è stato eseguito il deployment, puoi utilizzare la console Google Cloud per creare sessioni:

  1. Nella console Google Cloud , vai alla pagina Deployment di Agent Platform.

    Vai a Deployment

    Nell'elenco vengono visualizzate le istanze di Agent Engine che fanno parte del progetto selezionato. Puoi utilizzare il campo Filtra per filtrare l'elenco in base alla colonna specificata.

  2. Fai clic sul nome dell'istanza Agent Engine.

  3. Fai clic sulla scheda Playground.

  4. Fai clic sulla scheda Sessioni. Viene visualizzato un elenco di sessioni per ID.

  5. Fai clic sulla sessione che vuoi visualizzare in modo più dettagliato.

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

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto.
  • LOCATION: La regione in cui hai creato l'istanza di Agent Engine.
  • AGENT_ENGINE_ID: L'ID risorsa dell'istanza di Agent Engine.
  • SESSION_ID: l'ID risorsa della sessione che vuoi recuperare. Puoi ottenere l'ID sessione dalla risposta che hai ricevuto al momento della creazione della sessione.

Metodo HTTP e URL: 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID

Per inviare la richiesta, scegli una di queste opzioni:

curl

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

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

Nella risposta, dovresti visualizzare informazioni sulla tua sessione.

Eliminare una sessione

Elimina una sessione associata alla tua istanza di Agent Platform.

Console

Per gli agenti di cui è stato eseguito il deployment, puoi utilizzare la console Google Cloud per eliminare le sessioni associate al tuo agente:

  1. Nella console Google Cloud , vai alla pagina Deployment di Agent Platform.

    Vai a Deployment

    Nell'elenco vengono visualizzate le istanze di Agent Engine che fanno parte del progetto selezionato. Puoi utilizzare il campo Filtra per filtrare l'elenco in base alla colonna specificata.

  2. Fai clic sul nome dell'istanza Agent Engine.

  3. Fai clic sulla scheda Sessioni. Viene visualizzato un elenco di sessioni per ID.

  4. Fai clic sul menu Altre azioni () della sessione che vuoi eliminare.

  5. Fai clic su Elimina.

  6. Fai clic su Elimina sessione.

Python 

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

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto.
  • LOCATION: la regione in cui vuoi creare l'istanza di Example Store.
  • AGENT_ENGINE_ID: L'ID risorsa dell'istanza di Agent Engine.
  • SESSION_ID: L'ID risorsa della sessione che vuoi recuperare.

Metodo HTTP e URL: 

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID

Per inviare la richiesta, scegli una di queste opzioni:

curl

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

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

Dovresti ricevere un codice di stato riuscito (2xx) e una risposta vuota.

Elencare gli eventi in una sessione

Elenca gli eventi in una sessione associata alla tua istanza di Agent Platform.

Console

Per gli agenti di cui è stato eseguito il deployment, puoi utilizzare la console Google Cloud per creare sessioni:

  1. Nella console Google Cloud , vai alla pagina Deployment di Agent Platform.

    Vai a Deployment

    Nell'elenco vengono visualizzate le istanze di Agent Engine che fanno parte del progetto selezionato. Puoi utilizzare il campo Filtra per filtrare l'elenco in base alla colonna specificata.

  2. Fai clic sul nome dell'istanza Agent Engine.

  3. Fai clic sulla scheda Playground.

  4. Fai clic sulla scheda Sessioni. Viene visualizzato un elenco di sessioni per ID.

  5. Fai clic sulla sessione che vuoi visualizzare in modo più dettagliato.

  6. Fai clic sulla scheda Eventi per visualizzare gli eventi associati alla sessione.

Python 

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

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto.
  • LOCATION: La regione in cui hai creato l'istanza di Agent Engine.
  • AGENT_ENGINE_ID: L'ID risorsa dell'istanza di Agent Engine.
  • SESSION_ID: L'ID risorsa della sessione che vuoi recuperare.

Metodo HTTP e URL: 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID/events

Per inviare la richiesta, scegli una di queste opzioni:

curl

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

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

Nella risposta dovresti visualizzare un elenco di eventi associati alla tua sessione.

Aggiungere un evento a una sessione

Aggiungi un evento a una sessione associata a un'istanza di Agent Platform.

Console

Per gli agenti di cui è stato eseguito il deployment, puoi utilizzare la console Google Cloud per creare sessioni:

  1. Nella console Google Cloud , vai alla pagina Deployment di Agent Platform.

    Vai a Deployment

    Nell'elenco vengono visualizzate le istanze di Agent Engine che fanno parte del progetto selezionato. Puoi utilizzare il campo Filtra per filtrare l'elenco in base alla colonna specificata.

  2. Fai clic sul nome dell'istanza Agent Engine.

  3. Fai clic sulla scheda Playground.

  4. Fai clic sulla scheda Sessioni. Viene visualizzato un elenco di sessioni per ID.

  5. Fai clic sulla sessione che vuoi visualizzare in modo più dettagliato.

  6. Fai clic sulla scheda Eventi per visualizzare gli eventi associati alla sessione.

  7. Digita un messaggio e premi Invio per aggiungere un nuovo evento alla sessione.

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

In alternativa, puoi utilizzare il campo raw_event per includere dati arbitrari negli eventi di sessione. Questa opzione è utile per l'interoperabilità con altri framework di agenti o per archiviare dati sugli eventi personalizzati.

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

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto.
  • LOCATION: La regione in cui hai creato l'istanza di Agent Engine.
  • AGENT_ENGINE_ID: L'ID risorsa dell'istanza di Agent Engine.
  • USER_ID: l'ID utente che hai definito. Ad esempio, sessions-agent.
  • SESSION_ID: l'ID sessione che hai definito. Ad esempio, my-custom-session.

    Per evitare conflitti con gli ID generati dal sistema, rispetta queste limitazioni quando specifichi un ID sessione personalizzato:

    • Se il primo carattere è una lettera, l'ID può contenere fino a 63 caratteri. I caratteri validi sono lettere minuscole, numeri e trattini (`[a-z0-9-]`). L'ultimo carattere deve essere una lettera o un numero.
    • Se il primo carattere è un numero, l'ID può contenere fino a 9 caratteri. I caratteri validi sono numeri (`[0-9]`) senza zeri iniziali.

    Metodo HTTP e URL: 

    POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions

    Corpo JSON della richiesta: 

    {
  "userId": USER_ID
}

    Per inviare la richiesta, scegli una di queste opzioni:

    curl

    Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

    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

    Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

    $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

    Dovresti ricevere un'operazione a lunga esecuzione che puoi interrogare per controllare lo stato di creazione della sessione.

Esegui la pulizia

Per eliminare tutte le risorse utilizzate in questo progetto, puoi eliminare l'istanza di Agent Platform insieme alle relative risorse secondarie:

agent_engine.delete(force=True)