Sitzungen mit dem ADK verwalten

Auf dieser Seite wird beschrieben, wie Sie einen ADK-Agenten (Agent Development Kit) mit Agent Platform-Sitzungen verbinden und verwaltete Sitzungen in der lokalen und Produktionsumgebung verwenden können.

Hinweis

In dieser Anleitung wird die folgende grundlegende Projektdateistruktur verwendet, um einen ADK-Agenten und den zugehörigen Runner- und Bereitstellungscode zu definieren:

my_agent/
    agent.py      # main agent code
    runner.py     # code for interacting with the agent
    deploy.py     # code for deploying the agent to Google Cloud

Richten Sie Ihre Umgebung ein. Folgen Sie dazu den Schritten Erforderliche Rollen abrufen und Authentifizierung unter Umgebung einrichten.

Umgebungsvariablen festlegen

Zwecks Verwendung des ADK legen Sie Ihre Umgebungsvariablen fest:

import os

os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "LOCATION"

Ersetzen Sie Folgendes:

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 Runtime bereits verwendet haben, dauert das Erstellen einer Agent Runtime-Instanz nur wenige Sekunden und erfordert keine Codebereitstellung. Wenn Sie die Agent Runtime zum ersten Mal verwenden, kann es länger dauern.

Google Cloud -Projekt

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(
    config={
      "display_name": "My Session Store",
    }
)

# Print the runtime ID, you will need it in the later steps to initialize
# the ADK `VertexAiSessionService`.
print(remote_agent.api_resource.name.split("/")[-1])

Ersetzen Sie Folgendes:

Multiregionale, globale und unternehmensweite Sicherheitsoptionen

Sitzungen unterstützen regionale, multiregionale (us und eu) und globale (global) Endpunkte. Beachten Sie bei der Auswahl eines Standorts und beim Erstellen der Instanz die folgenden Sicherheits- und Verschlüsselungsanforderungen:

  • Kundenverwaltete Verschlüsselungsschlüssel (CMEK): Sie können CMEK nicht verwenden, wenn Ihre Sessions-Instanz für die Verwendung des global-Endpunkts (location="global") konfiguriert ist, da Cloud Key Management Service (Cloud KMS) Verschlüsselungsschlüssel innerhalb einer geografischen Datenstandortgrenze erfordert. Wenn Sie Sitzungsdaten mit einem Cloud KMS-Schlüssel verschlüsseln möchten, erstellen Sie eine eigenständige übergeordnete Instanz (ohne Agent-Laufzeitcode bereitzustellen) an einem unterstützten regionalen oder multiregionalen Standort (us mit einem us-Schlüssel oder eu mit einem europe-Schlüssel) und fügen Sie encryption_spec in config ein, wenn Sie client.runtimes.create() aufrufen. Instanzen, die auch einen Agenten in Agent Runtime bereitstellen, unterstützen CMEK nur an Standorten mit einer einzelnen Region. Weitere Informationen finden Sie unter CMEK für Sitzungen.
  • VPC Service Controls: Informationen zum Schutz Ihrer Sitzungsressourcen innerhalb eines Dienstperimeters oder zum Weiterleiten von Sitzungstraffic über das Agent Gateway finden Sie unter VPC Service Controls für Sitzungen.

ADK-Agenten entwickeln

Wenn Sie Ihren ADK-Agenten erstellen möchten, folgen Sie der Anleitung unter ADK oder verwenden Sie den folgenden Code, um einen Agenten zu erstellen, der einen Nutzer mit festgelegten Begrüßungen begrüßt. Speichern Sie diesen Code in einer Datei mit dem Namen agent.py.

# file: my_agent/agent.py
from google import adk

def greetings(query: str):
  """Tool to greet user."""
  if 'hello' in query.lower():
    return {"greeting": "Hello, world"}
  else:
    return {"greeting": "Goodbye, world"}

# Define an ADK agent
root_agent = adk.Agent(
    model="gemini-2.0-flash",
    name='my_agent',
    instruction="You are an Agent that greet users, always use greetings tool to respond.",
    tools=[greetings]
)

ADK-Runner einrichten

Die ADK-Laufzeit orchestriert die Ausführung Ihrer Agenten, Tools und Callbacks sowie Aufrufe zum Lesen und Schreiben von Sitzungen. Initialisieren Sie den Runner mit VertexAiSessionService, um eine Verbindung zu Agent Platform-Sitzungen herzustellen. Speichern Sie diesen Code in einer Datei mit dem Namen runner.py.

Google Cloud -Projekt

# file: my_agent/runner.py
import agent # Import from your agent.py
from google.adk import Runner
from google.adk.sessions import VertexAiSessionService
from google.genai import types

app_name="APP_NAME"
user_id="USER_ID"

# Create the ADK runner with VertexAiSessionService
session_service = VertexAiSessionService(
      project="PROJECT_ID",
      location="LOCATION",
      agent_engine_id="AGENT_ENGINE_ID"
)
runner = Runner(
    agent=agent.root_agent,
    app_name=app_name,
    session_service=session_service)

# Helper method to send query to the runner
async def call_agent(query, session_id, user_id):
  content = types.Content(role='user', parts=[types.Part(text=query)])
  async for event in runner.run_async(
      user_id=user_id, session_id=session_id, new_message=content):
      if event.is_final_response():
          final_response = event.content.parts[0].text
          print("Agent Response: ", final_response)

Ersetzen Sie Folgendes:

  • APP_NAME: Der Name Ihrer KI-Agentenanwendung.

  • USER_ID: Wählen Sie eine eigene Nutzer-ID mit einer Zeichenbeschränkung von 128 Zeichen aus. Beispiel: user-123.

  • AGENT_ENGINE_ID: Die Ressourcen-ID einer Agent Runtime-Instanz.

  • Bei bereitgestellten KI-Agenten wird die Ressourcen-ID als Umgebungsvariable GOOGLE_CLOUD_AGENT_ENGINE_ID aufgeführt.

  • Für lokale Agenten können Sie die Ressourcen-ID mit remote_agent.api_resource.name.split("/")[-1] abrufen.

Mit dem Agent interagieren

Nachdem Sie Ihren KI-Agenten definiert und Agent Platform-Sitzungen eingerichtet haben, können Sie mit Ihrem KI-Agenten interagieren, um zu prüfen, ob der Sitzungsverlauf und die Status beibehalten werden.

ADK-Benutzeroberfläche

Wenn Sie Ihren Agenten mit der ADK-Benutzeroberfläche testen und eine Verbindung zu Agent Platform Sessions herstellen möchten, führen Sie den Befehl adk web in Ihrem Terminal aus.

adk web liest Umgebungsvariablen normalerweise aus einer .env-Datei, ignoriert diese Datei jedoch, wenn Sie das Flag --session_service_uri verwenden. Stattdessen müssen Sie die Umgebungsvariablen GOOGLE_CLOUD_PROJECT und GOOGLE_CLOUD_LOCATION in Ihrer Terminalsitzung festlegen, bevor Sie den Befehl ausführen.

export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="LOCATION"
adk web --session_service_uri=agentengine://AGENT_ENGINE_ID
# Sample output
+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

ADK-Benutzeroberfläche

Python

ADK-Python-Code zum Verwalten von Sitzungen und Status verwenden Fügen Sie am Ende der Datei runner.py den folgenden Code hinzu, um mit dem KI-Agenten zu interagieren.

Die folgenden Snippets enthalten der Kürze halber await-Aufrufe auf oberster Ebene. Wenn Sie diesen Code als Python-Skript ausführen möchten, fügen Sie die Snippets in eine async-Funktion ein und verwenden Sie asyncio.run(), um sie auszuführen, wie in diesem Beispiel gezeigt:

import asyncio

async def main():
  # Place one or more snippets here.
  # For example:
  session = await session_service.create_session(
         app_name=app_name,
         user_id=user_id)

  await call_agent("Hello!", session.id, user_id)

asyncio.run(main())

Sitzung erstellen und den KI-Agenten abfragen

Verwenden Sie den folgenden Code, um eine Sitzung zu erstellen und eine Anfrage an Ihren Agenten zu senden. Geben Sie eine benutzerdefinierte Sitzungs-ID an, um Sitzungen mit Ihrem eigenen Namensschema zu organisieren oder schnell von anderen Diensten zu wechseln. Wenn Sie keine Sitzungs-ID angeben, wird von der Agent-Plattform automatisch eine generiert.

# file: my_agent/runner.py
# Create a session
session = await session_service.create_session(
       app_name=app_name,
       user_id=user_id,
       session_id=session_id)

await call_agent("Hello!", session.id, user_id)
# Agent response: "Hello, world"

await call_agent("Thanks!", session.id, user_id)
# Agent response: "Goodbye, world"

Beachten Sie bei benutzerdefinierten Sitzungs-IDs 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.

Nachdem die Sitzung erstellt und an den Runner übergeben wurde, verwendet das ADK die Sitzung, um Ereignisse aus der aktuellen Interaktion zu speichern. Sie können auch eine vorherige Sitzung fortsetzen, indem Sie die ID für diese Sitzung angeben.

Gültigkeitsdauer (TTL) für Sitzungen konfigurieren

Alle Sitzungen müssen eine Ablaufzeit haben. Sie können diese Ablaufzeit beim Erstellen oder Aktualisieren einer Sitzung festlegen. Die Sitzung und die zugehörigen untergeordneten Ereignisse werden nach Ablauf der Ablaufzeit automatisch gelöscht. Sie können entweder die Ablaufzeit (expire_time) direkt festlegen oder die Gültigkeitsdauer (ttl) in Sekunden angeben. Wenn keine der beiden Optionen 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 als create_time + ttl für neu erstellte Sitzungen oder update_time + ttl für aktualisierte Sitzungen.

  session = await session_service.create_session(
        app_name=app_name,
        user_id=user_id,
        # Session will be deleted 10 days after creation time.
        ttl=f"{24 * 60 * 60 * 10}s"
  )
  ```

Ablaufzeit

  import datetime

  expire_time = datetime.datetime.now(
        tz=datetime.timezone.utc) + datetime.timedelta(seconds=24 * 60 * 60 * 10)

  session = await session_service.create_session(
        app_name=app_name,
        user_id=user_id,
        # Session will be deleted at the provided time (10 days after current time).
        expire_time=expire_time.isoformat()
  )

Vorhandene Sitzungen auflisten

Alle vorhandenen Sitzungen auflisten, die mit einer bestimmten Nutzer-ID verknüpft sind.

# List sessions
sessions = await session_service.list_sessions(app_name=app_name,user_id=user_id)
print(sessions)
# ListSessionsResponse(session_ids=['1122334455', '9988776655'])

Sitzungsstatus verwalten

Zustände enthalten Informationen, die der Agent für eine Unterhaltung benötigt. Sie können beim Erstellen einer Sitzung einen Anfangszustand als Dictionary angeben:

# Create a session with state
session = await session_service.create_session(
    app_name=app_name,
    user_id=user_id,
    state={'key': 'value'})

print(session.state['key'])
# value

Wenn Sie den Sitzungsstatus außerhalb des Runners aktualisieren möchten, hängen Sie mit state_delta ein neues Ereignis an die Sitzung an:

# file: my_agent/runner.py
from google.adk.events import Event, EventActions
import time

# Define state changes
state_changes = {'key': 'new_value'}

# Create event with actions
actions_with_update = EventActions(state_delta=state_changes)
system_event = Event(
invocation_id="invocation_id",
author="system", # Or 'agent', 'tool' etc.
actions=actions_with_update,
timestamp=time.time()
)

# Append the event
await session_service.append_event(session, system_event)

# Check updated state
updated_session = await session_service.get_session(
    app_name=app_name,
    user_id=user_id,
    session_id=session.id)
# State is updated to new value
print(updated_session.state['key'])
# new_value

Benutzerdefinierte Felder für Ereignisse

Das ADK unterstützt ein flexibles Ereignisschema, sodass Sie beliebige Daten in Sitzungsereignisse aufnehmen können. Das ist nützlich für die Interoperabilität mit anderen Agent-Frameworks oder zum Speichern benutzerdefinierter Ereignisdaten.

Wenn Sie ein Ereignis mit benutzerdefinierten Feldern anhängen, serialisiert das ADK die Ereignisdaten in das Feld raw_event des gespeicherten Sitzungsereignisses.

# Create an event with custom fields
custom_event = Event(
  invocation_id="invocation_id",
  author="user",
  timestamp=time.time(),
  custom_field="custom_value",
  another_field={"nested_key": "nested_value"}
)

# Append the event
await session_service.append_event(session, custom_event)

Wenn Sie die Sitzung abrufen, bleiben diese benutzerdefinierten Felder in den abgerufenen Ereignissen erhalten.

Sitzung löschen

So löschen Sie eine bestimmte Sitzung, die mit einer Nutzer-ID verknüpft ist:

await session_service.delete_session(app_name=app_name, user_id=user_id, session_id=session.id)

KI-Agenten auf der Agent Platform bereitstellen

Nachdem Sie Ihren Agenten lokal getestet haben, können Sie ihn in der Produktion bereitstellen. Aktualisieren Sie dazu die Agent Platform-Instanz mit den folgenden Parametern:

Google Cloud -Projekt

client.runtimes.update(
    resource_name=remote_agent.api_resource.name,
    agent=AGENT,
    config={
      "display_name": DISPLAY_NAME,      # Optional.
      "requirements": REQUIREMENTS,      # Optional.
      "staging_bucket": STAGING_BUCKET,  # Required.
    },
)

Ersetzen Sie Folgendes:

  • AGENT: Die Anwendung, die die Methode query / stream_query implementiert (z. B. AdkApp für einen ADK-Agenten).

  • DISPLAY_NAME: Ein nutzerfreundlicher Name für Ihren KI-Agenten.

  • REQUIREMENTS: Eine Liste der pip-Pakete, die Ihr Agent benötigt. Beispiel: ["google-cloud-storage", "google-cloud-agentplatform[runtimes,adk]"].

  • STAGING_BUCKET: Ein Cloud Storage-Bucket mit dem Präfix gs://.

Bereinigen

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

remote_agent.delete(force=True)

Nächste Schritte