Gestire le sessioni utilizzando chiamate API dirette

Questa sezione descrive come utilizzare le sessioni di Vertex AI Agent Engine per gestire le sessioni utilizzando chiamate API dirette. Puoi effettuare 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 utilizzare un'istanza di Vertex AI Agent Engine. Per iniziare a utilizzare le sessioni, non devi eseguire il deployment di alcun codice. Senza il deployment del codice, la creazione di un'istanza di Vertex AI Agent Engine richiede solo pochi secondi.

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

import vertexai
from vertexai import agent_engines

# Create an agent engine instance
agent_engine = agent_engines.create()

Elenco sessioni

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

API REST

Utilizza il metodo sessions.list:

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

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

Creare una sessione

Crea una sessione associata a un ID utente.

API REST

Utilizza il metodo sessions.create.

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

  • 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: un ID utente

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.

API REST

Utilizza il metodo sessions.get.

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

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

API REST

Utilizza il metodo sessions.delete.

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

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

API REST

Utilizza il metodo events.list.

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

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

API REST

Utilizza il metodo sessions.appendEvent.

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

  • 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

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"

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" | Select-Object -Expand Content

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