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 le chiamate API dirette se non vuoi utilizzare un agente ADK per gestire le sessioni.

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

Crea un'istanza di Agent Runtime

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

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

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)

Sostituisci quanto segue:

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

Elenca 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 della piattaforma agente.

    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 di Agent Engine.

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

Per impostazione predefinita, client.sessions.list restituisce le sessioni ordinate in base all'ora di creazione in ordine decrescente (create_time desc). Questo ordine predefinito mantiene stabile l'impaginazione quando le sessioni attive vengono aggiornate contemporaneamente. L'SDK Python non espone un'opzione order_by. Per ordinare in base a un campo diverso, utilizza l'API REST.

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 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 vedere un elenco di sessioni restituite.

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

Per ordinare le sessioni restituite, aggiungi il parametro di query ?orderBy=ORDER_BY, dove ORDER_BY è create_time, update_time o display_name. Puoi aggiungere %20desc per l'ordine decrescente, ad esempio ?orderBy=create_time%20desc. Se ometti orderBy, l'API restituisce le sessioni ordinate per create_time desc. Utilizza create_time desc quando pagini le sessioni durante gli aggiornamenti simultanei, in modo che gli aggiornamenti non spostino le sessioni oltre i limiti della pagina.

Crea 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 della piattaforma agente.

    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 di Agent Engine.

  3. Fai clic sulla scheda Playground.

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

Python 

session = client.sessions.create(
    name=remote_agent.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 presente 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 i 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 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, segui 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 i 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 su cui puoi eseguire query per controllare lo stato di creazione della sessione.

Configura la durata (TTL) della sessione

Tutte le sessioni devono avere una scadenza. Puoi definire questa scadenza durante la creazione o l'aggiornamento di una sessione. La sessione e i relativi eventi figlio vengono eliminati automaticamente al termine del periodo di scadenza. Puoi impostare direttamente la data e 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 la durata, il server calcola la data e l'ora di scadenza come create_time + ttl per le sessioni appena create o update_time + ttl per le sessioni aggiornate.

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

Scadenza 

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

Recupera 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 della piattaforma agente.

    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 di 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 maggiore dettaglio.

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

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 Agent Engine.
  • SESSION_ID: l'ID risorsa della sessione che vuoi recuperare. Puoi ottenere l'ID sessione dalla risposta che hai ricevuto quando hai creato la 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 vedere le informazioni sulla tua sessione.

Elimina 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 della piattaforma agente.

    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 di 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.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 Example Store.
  • AGENT_ENGINE_ID: l'ID risorsa dell'istanza 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.

Elenca gli eventi di una sessione

Elenca gli eventi di 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 della piattaforma agente.

    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 di 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 maggiore dettaglio.

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

Python 

for session_event in client.sessions.events.list(
    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 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 vedere un elenco di eventi associati alla tua sessione.

Aggiungi 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 della piattaforma agente.

    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 di 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 maggiore dettaglio.

  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.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. Ciò è utile per l'interoperabilità con altri framework di agenti o per l'archiviazione di dati sugli eventi personalizzati.

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

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 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, segui 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 i 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 su cui puoi eseguire query 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:

remote_agent.delete(force=True)