Sitzungen mit der Google Cloud Console oder API-Aufrufen verwalten

In diesem Abschnitt wird beschrieben, wie Sie Sitzungen mit Agent Platform Sessions über die Google Cloud Console oder direkte API-Aufrufe verwalten. Wenn Sie keinen ADK-Agenten zum Verwalten von Sitzungen verwenden möchten, können Sie die Google Cloud Console oder direkte API-Aufrufe verwenden.

Informationen zum Verwalten von Sitzungen mit dem ADK-Agenten finden Sie unter Sitzungen mit dem Agent Development Kit verwalten.

Agent Runtime-Instanz erstellen

Um auf Agent Platform-Sitzungen zuzugreifen, müssen Sie zuerst eine Agent Runtime-Instanz verwenden. Sie müssen keinen Code bereitstellen, um Sitzungen zu verwenden. Wenn Sie Agent Engine bereits verwendet haben, dauert das Erstellen einer Agent Runtime-Instanz nur wenige Sekunden und es ist keine Codebereitstellung erforderlich. Wenn Sie Agent Engine zum ersten Mal verwenden, kann es länger dauern.

Wenn Sie keine vorhandene Agent Runtime-Instanz haben, erstellen Sie eine mit dem folgenden Code:

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)

Ersetzen Sie Folgendes:

Sitzungen auflisten

Listet die Sitzungen auf, die mit Ihrer Agent Runtime-Instanz verknüpft sind.

Console

Bei bereitgestellten Agenten können Sie die Google Cloud Console verwenden, um die mit Ihrem Agenten verknüpften Sitzungen aufzulisten:

  1. Rufen Sie in der Google Cloud Console die Seite Bereitstellungen der Agent-Plattform auf.

    Zu Deployments

    Agent Engine-Instanzen, die Teil des ausgewählten Projekts sind, werden in der Liste angezeigt. Mit dem Feld Filter können Sie die Liste nach der von Ihnen angegebenen Spalte filtern.

  2. Klicken Sie auf den Namen Ihrer Agent Engine-Instanz.

  3. Klicken Sie auf den Tab Sitzungen. Eine Liste der Sitzungen wird nach ID angezeigt.

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: Wählen Sie eine eigene Nutzer-ID mit einem Zeichenlimit von 128 Zeichen aus. Beispiel: user-123.

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: Ihre Projekt-ID.
  • LOCATION: Die Region, in der Sie Ihre Agent Engine-Instanz erstellt haben.
  • AGENT_ENGINE_ID: Die Ressourcen-ID Ihrer Agent Engine-Instanz.

HTTP-Methode und URL:

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

Senden Sie die Anfrage mithilfe einer der folgenden Optionen:

curl

Führen Sie folgenden Befehl aus:

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

Führen Sie diesen Befehl aus:

$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

Es sollte eine Liste mit Sitzungen angezeigt werden.

Optional können Sie den Abfrageparameter ?filter=user_id=\"USER_ID\" hinzufügen, um Sitzungen für einen bestimmten Nutzer aufzulisten. Dabei ist USER_ID die ID des Nutzers, den Sie abfragen möchten.

Sitzung erstellen

Erstellen Sie eine Sitzung, die mit einer Nutzer-ID verknüpft ist.

Console

Für bereitgestellte Agents können Sie die Google Cloud Konsole verwenden, um Sitzungen zu erstellen:

  1. Rufen Sie in der Google Cloud Console die Seite Bereitstellungen der Agent-Plattform auf.

    Zu Deployments

    Agent Engine-Instanzen, die Teil des ausgewählten Projekts sind, werden in der Liste angezeigt. Mit dem Feld Filter können Sie die Liste nach der von Ihnen angegebenen Spalte filtern.

  2. Klicken Sie auf den Namen Ihrer Agent Engine-Instanz.

  3. Klicken Sie auf den Tab Playground.

  4. Klicken Sie auf Neue Sitzung, um eine neue Sitzung zu erstellen.

Python

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

Dabei ist USER_ID die von Ihnen definierte Nutzer-ID. Beispiel: user-123

Beachten Sie für SESSION_ID die folgenden Einschränkungen, um Konflikte mit vom System generierten IDs zu vermeiden:

  • Wenn das erste Zeichen ein Buchstabe ist, kann die ID bis zu 63 Zeichen lang sein. Gültige Zeichen sind Kleinbuchstaben, Ziffern und Bindestriche ([a-z0-9-]). Das letzte Zeichen muss ein Buchstabe oder eine Ziffer sein.
  • Wenn das erste Zeichen eine Zahl ist, kann die ID bis zu 9 Zeichen lang sein. Gültige Zeichen sind Zahlen ([0-9]) ohne führende Nullen.

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: Ihre Projekt-ID.
  • LOCATION: Die Region, in der Sie Ihre Agent Engine-Instanz erstellt haben.
  • AGENT_ENGINE_ID: Die Ressourcen-ID Ihrer Agent Engine-Instanz.
  • USER_ID: die von Ihnen definierte Nutzer-ID. Beispiel: sessions-agent
  • SESSION_ID: die von Ihnen definierte Sitzungs-ID. Beispiel: my-custom-session

    Um Konflikte mit systemgenerierten IDs zu vermeiden, müssen Sie die folgenden Einschränkungen beachten, wenn Sie eine benutzerdefinierte Sitzungs-ID angeben:

    • Wenn das erste Zeichen ein Buchstabe ist, kann die ID bis zu 63 Zeichen lang sein. Gültige Zeichen sind Kleinbuchstaben, Ziffern und Bindestriche (`[a–z0–9-]`). Das letzte Zeichen muss ein Buchstabe oder eine Ziffer sein.
    • Wenn das erste Zeichen eine Ziffer ist, darf die ID bis zu 9 Zeichen lang sein. Gültige Zeichen sind Ziffern (`[0-9]`) ohne führende Nullen.

    HTTP-Methode und URL:

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

    JSON-Text der Anfrage:

    {
      "userId": USER_ID
    }
    
    

    Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

    curl

    Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

    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

    Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

    $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

    Sie sollten einen lange laufenden Vorgang erhalten, den Sie abfragen können, um den Erstellungsstatus Ihrer Sitzung zu prüfen.

Gültigkeitsdauer von Sitzungen konfigurieren

Alle Sitzungen müssen eine Ablaufzeit haben. Sie können diese Ablaufzeit beim Erstellen oder Aktualisieren einer Sitzung definieren. Die Sitzung und ihre untergeordneten Ereignisse werden nach Ablauf der Gültigkeitsdauer automatisch gelöscht. Sie können entweder die Ablaufzeit (expire_time) direkt oder die Gültigkeitsdauer (ttl) in Sekunden festlegen. Wenn keines angegeben ist, wendet das System eine Standard-TTL von 365 Tagen an.

Gültigkeitsdauer

Wenn Sie die Gültigkeitsdauer festlegen, berechnet der Server die Ablaufzeit für neu erstellte Sitzungen als create_time + ttl und für aktualisierte Sitzungen als update_time + ttl.

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

Ablaufzeit

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

Sitzung abrufen

Eine bestimmte Sitzung abrufen, die mit Ihrer Agent Platform-Instanz verknüpft ist.

Console

Für bereitgestellte Agents können Sie die Google Cloud Konsole verwenden, um Sitzungen zu erstellen:

  1. Rufen Sie in der Google Cloud Console die Seite Bereitstellungen der Agent-Plattform auf.

    Zu Deployments

    Agent Engine-Instanzen, die Teil des ausgewählten Projekts sind, werden in der Liste angezeigt. Mit dem Feld Filter können Sie die Liste nach der von Ihnen angegebenen Spalte filtern.

  2. Klicken Sie auf den Namen Ihrer Agent Engine-Instanz.

  3. Klicken Sie auf den Tab Playground.

  4. Klicken Sie auf den Tab Sitzungen. Eine Liste der Sitzungen wird nach ID angezeigt.

  5. Klicken Sie auf die Sitzung, die Sie sich genauer ansehen möchten.

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

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: Ihre Projekt-ID.
  • LOCATION: Die Region, in der Sie Ihre Agent Engine-Instanz erstellt haben.
  • AGENT_ENGINE_ID: Die Ressourcen-ID Ihrer Agent Engine-Instanz.
  • SESSION_ID: Die Ressourcen-ID der Sitzung, die Sie abrufen möchten. Sie können die Sitzungs-ID aus der Antwort abrufen, die Sie beim Erstellen der Sitzung erhalten haben.

HTTP-Methode und URL:

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

Senden Sie die Anfrage mithilfe einer der folgenden Optionen:

curl

Führen Sie folgenden Befehl aus:

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

Führen Sie diesen Befehl aus:

$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

In der Antwort sollten Informationen zu Ihrer Sitzung angezeigt werden.

Sitzung löschen

Löschen Sie eine Sitzung, die mit Ihrer Agent Platform-Instanz verknüpft ist.

Console

Bei bereitgestellten Agents können Sie die Google Cloud -Konsole verwenden, um Sitzungen zu löschen, die mit Ihrem Agent verknüpft sind:

  1. Rufen Sie in der Google Cloud Console die Seite Bereitstellungen der Agent-Plattform auf.

    Zu Deployments

    Agent Engine-Instanzen, die Teil des ausgewählten Projekts sind, werden in der Liste angezeigt. Mit dem Feld Filter können Sie die Liste nach der von Ihnen angegebenen Spalte filtern.

  2. Klicken Sie auf den Namen Ihrer Agent Engine-Instanz.

  3. Klicken Sie auf den Tab Sitzungen. Eine Liste der Sitzungen wird nach ID angezeigt.

  4. Klicken Sie auf das Dreipunkt-Menü () der Sitzung, die Sie löschen möchten.

  5. Klicken Sie auf Löschen.

  6. Klicken Sie auf Sitzung löschen.

Python

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

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: Ihre Projekt-ID.
  • LOCATION: Die Region, in der Sie die Example Store-Instanz erstellen möchten.
  • AGENT_ENGINE_ID: Die Ressourcen-ID Ihrer Agent Engine-Instanz.
  • SESSION_ID: Die Ressourcen-ID der Sitzung, die Sie abrufen möchten.

HTTP-Methode und URL:

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

Senden Sie die Anfrage mithilfe einer der folgenden Optionen:

curl

Führen Sie folgenden Befehl aus:

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

Führen Sie folgenden Befehl aus:

$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

Sie sollten einen erfolgreichen Statuscode (2xx) und eine leere Antwort als Ausgabe erhalten.

Ereignisse in einer Sitzung auflisten

Listet Ereignisse in einer Sitzung auf, die mit Ihrer Agent Platform-Instanz verknüpft sind.

Console

Für bereitgestellte Agents können Sie die Google Cloud Konsole verwenden, um Sitzungen zu erstellen:

  1. Rufen Sie in der Google Cloud Console die Seite Bereitstellungen der Agent-Plattform auf.

    Zu Deployments

    Agent Engine-Instanzen, die Teil des ausgewählten Projekts sind, werden in der Liste angezeigt. Mit dem Feld Filter können Sie die Liste nach der von Ihnen angegebenen Spalte filtern.

  2. Klicken Sie auf den Namen Ihrer Agent Engine-Instanz.

  3. Klicken Sie auf den Tab Playground.

  4. Klicken Sie auf den Tab Sitzungen. Eine Liste der Sitzungen wird nach ID angezeigt.

  5. Klicken Sie auf die Sitzung, die Sie sich genauer ansehen möchten.

  6. Klicken Sie auf den Tab Ereignisse, um die mit der Sitzung verknüpften Ereignisse aufzurufen.

Python

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

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: Ihre Projekt-ID.
  • LOCATION: Die Region, in der Sie Ihre Agent Engine-Instanz erstellt haben.
  • AGENT_ENGINE_ID: Die Ressourcen-ID Ihrer Agent Engine-Instanz.
  • SESSION_ID: Die Ressourcen-ID der Sitzung, die Sie abrufen möchten.

HTTP-Methode und URL:

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

Senden Sie die Anfrage mithilfe einer der folgenden Optionen:

curl

Führen Sie folgenden Befehl aus:

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

Führen Sie diesen Befehl aus:

$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

In der Antwort sollte eine Liste der Ereignisse angezeigt werden, die mit Ihrer Sitzung verknüpft sind.

Ereignis an eine Sitzung anhängen

Ein Ereignis an eine Sitzung anhängen, die einer Agent Platform-Instanz zugeordnet ist.

Console

Für bereitgestellte Agents können Sie die Google Cloud Konsole verwenden, um Sitzungen zu erstellen:

  1. Rufen Sie in der Google Cloud Console die Seite Bereitstellungen der Agent-Plattform auf.

    Zu Deployments

    Agent Engine-Instanzen, die Teil des ausgewählten Projekts sind, werden in der Liste angezeigt. Mit dem Feld Filter können Sie die Liste nach der von Ihnen angegebenen Spalte filtern.

  2. Klicken Sie auf den Namen Ihrer Agent Engine-Instanz.

  3. Klicken Sie auf den Tab Playground.

  4. Klicken Sie auf den Tab Sitzungen. Eine Liste der Sitzungen wird nach ID angezeigt.

  5. Klicken Sie auf die Sitzung, die Sie sich genauer ansehen möchten.

  6. Klicken Sie auf den Tab Ereignisse, um die mit der Sitzung verknüpften Ereignisse aufzurufen.

  7. Geben Sie eine Nachricht ein und drücken Sie die Eingabetaste, um der Sitzung ein neues Ereignis hinzuzufügen.

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

Alternativ können Sie das Feld raw_event verwenden, um beliebige Daten in Sitzungsereignisse aufzunehmen. Das ist nützlich für die Interoperabilität mit anderen Agent-Frameworks oder zum Speichern benutzerdefinierter Ereignisdaten.

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

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: Ihre Projekt-ID.
  • LOCATION: Die Region, in der Sie Ihre Agent Engine-Instanz erstellt haben.
  • AGENT_ENGINE_ID: Die Ressourcen-ID Ihrer Agent Engine-Instanz.
  • USER_ID: die von Ihnen definierte Nutzer-ID. Beispiel: sessions-agent
  • SESSION_ID: die von Ihnen definierte Sitzungs-ID. Beispiel: my-custom-session

    Um Konflikte mit systemgenerierten IDs zu vermeiden, müssen Sie die folgenden Einschränkungen beachten, wenn Sie eine benutzerdefinierte Sitzungs-ID angeben:

    • Wenn das erste Zeichen ein Buchstabe ist, kann die ID bis zu 63 Zeichen lang sein. Gültige Zeichen sind Kleinbuchstaben, Ziffern und Bindestriche (`[a–z0–9-]`). Das letzte Zeichen muss ein Buchstabe oder eine Ziffer sein.
    • Wenn das erste Zeichen eine Ziffer ist, darf die ID bis zu 9 Zeichen lang sein. Gültige Zeichen sind Ziffern (`[0-9]`) ohne führende Nullen.

    HTTP-Methode und URL:

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

    JSON-Text der Anfrage:

    {
      "userId": USER_ID
    }
    
    

    Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

    curl

    Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

    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

    Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

    $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

    Sie sollten einen Vorgang mit langer Ausführungszeit erhalten, den Sie abfragen können, um den Erstellungsstatus Ihrer Sitzung zu prüfen.

Bereinigen

Wenn Sie alle in diesem Projekt verwendeten Ressourcen bereinigen möchten, können Sie die Agent Platform-Instanz zusammen mit den untergeordneten Ressourcen löschen:

agent_engine.delete(force=True)