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

Questa sezione descrive come utilizzare le sessioni di Vertex AI Agent Engine 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 Vertex AI Agent Engine

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

Se non hai un'istanza Vertex AI Agent Engine 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 le sessioni.

Elenco sessioni

Elenca le sessioni associate alla tua istanza di Vertex AI Agent Engine.

Console Google Cloud

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 Vertex AI Agent Engine.

    Vai ad Agent Engine

    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.

SDK Vertex AI per 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 Google Cloud

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 Vertex AI Agent Engine.

    Vai ad Agent Engine

    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.

SDK Vertex AI per Python 

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

dove USER_ID è l'ID utente che hai definito. 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.
  • USER_ID: l'ID utente che hai definito. Ad esempio, sessions-agent.

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.

Recuperare una sessione

Recupera una sessione specifica associata alla tua istanza di Vertex AI Agent Engine.

Console Google Cloud

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 Vertex AI Agent Engine.

    Vai ad Agent Engine

    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 modo più dettagliato.

SDK Vertex AI per 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 all'istanza di Vertex AI Agent Engine.

Console Google Cloud

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 Vertex AI Agent Engine.

    Vai ad Agent Engine

    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.

SDK Vertex AI per 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 Vertex AI Agent Engine.

Console Google Cloud

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 Vertex AI Agent Engine.

    Vai ad Agent Engine

    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 modo più dettagliato.

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

SDK Vertex AI per 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 vedere 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 Vertex AI Agent Engine.

Console Google Cloud

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 Vertex AI Agent Engine.

    Vai ad Agent Engine

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

SDK Vertex AI per 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"}]
        },
    },
)

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 a cui vuoi aggiungere gli eventi.
  • AUTHOR: l'autore dell'evento. Può essere 'user' o il nome di un agente.
  • INVOCATION_ID: un identificatore di una chiamata.
  • TIMESTAMP: il timestamp dell'evento.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

{
  "author": AUTHOR,
  "invocationId": INVOCATION_ID,
  "timestamp": TIMESTAMP,
}

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/SESSION_ID:appendEvent"

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/SESSION_ID:appendEvent" | Select-Object -Expand Content

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

Esegui la pulizia

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

agent_engine.delete(force=True)