Kurzanleitung für das Agent-Entwicklungs-Kit

In dieser Anleitung wird gezeigt, wie Sie Memory Bank mit dem ADK verwenden können, um langfristige Erinnerungen zu verwalten. Nachdem Sie Ihren ADK-Agent für die Verwendung von Memory Bank konfiguriert haben, orchestriert Ihr Agent Aufrufe an Memory Bank, um Langzeiterinnerungen für Sie zu verwalten.

Die Verwendung von Memory Bank mit dem ADK umfasst die folgenden Schritte:

ADK-Agent und -Runner erstellen ADK-Runner verbinden Ihren Agenten mit Diensten, die die Sitzungs- und Speicherverwaltung übernehmen.
Interagieren Sie mit Ihrem Agent, um dynamisch langfristig gemerkte Informationen zu generieren, auf die über Sitzungen hinweg zugegriffen werden kann.
Führen Sie eine Bereinigung durch.

Wenn Sie Memory Bank ohne ADK-Orchestrierung direkt aufrufen möchten, lesen Sie die Kurzanleitung für das Agent Engine SDK. Mit dem Agent Engine SDK ist es leichter zu verstehen, wie Memory Bank Erinnerungen generiert, oder den Inhalt von Memory Bank zu prüfen.

Erinnerungen mit dem ADK-Speicherdienst und Memory Bank verwalten

VertexAiMemoryBankService ist ein ADK-Wrapper für Memory Bank, der durch BaseMemoryService des ADK definiert wird. Sie können Rückrufe und Tools definieren, die mit dem Memory-Dienst interagieren, um Erinnerungen zu lesen und zu schreiben.

Die VertexAiMemoryBankService-Schnittstelle umfasst:

memory_service.add_session_to_memory löst eine GenerateMemories-Anfrage an Memory Bank aus, wobei alle Ereignisse im bereitgestellten adk.Session als Quellinhalte verwendet werden. Sie können Aufrufe dieser Methode mit callback_context.add_session_to_memory in Ihren Callbacks orchestrieren.
```
from google.adk.agents.callback_context import CallbackContext

async def add_session_to_memory_callback(callback_context: CallbackContext):
    await callback_context.add_session_to_memory()
    return None
```

memory_service.add_events_to_memory, wodurch eine GenerateMemories-Anfrage mit einer Teilmenge von Ereignissen an Memory Bank gesendet wird. Sie können Aufrufe dieser Methode mit callback_context.add_events_to_memory in Ihren Callbacks orchestrieren.

from google.adk.agents.callback_context import CallbackContext

async def add_events_to_memory_callback(callback_context: CallbackContext):
    await callback_context.add_events_to_memory(events=callback_context.session.events[-5:-1])
    return None

memory_service.search_memory löst eine RetrieveMemories-Anfrage an Memory Bank aus, um relevante Erinnerungen für die aktuelle user_id und app_name abzurufen. Sie können Aufrufe dieser Methode mit integrierten Memory-Tools (LoadMemoryTool oder PreloadMemoryTool) oder einem benutzerdefinierten Tool, das tool_context.search_memory aufruft, orchestrieren.

Hinweise

Wenn Sie dieser Anleitung folgen möchten, sollten Sie zuerst die Schritte im Abschnitt Erste Schritte auf der Seite „Memory Bank einrichten“ ausführen.

Umgebungsvariablen festlegen

Um das ADK zu verwenden, legen Sie Ihre Umgebungsvariablen fest:

import os

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

Ersetzen Sie Folgendes:

PROJECT_ID: Ihre Projekt-ID.
LOCATION: Ihre Region. Unterstützte Regionen für Memory Bank

ADK-Agent erstellen

Wenn Sie einen Agent mit Gedächtnis erstellen möchten, richten Sie Tools und Rückrufe ein, die Aufrufe an Ihren Gedächtnisdienst orchestrieren.

Callback für die Speichergenerierung definieren

Um Aufrufe für die Speichergenerierung zu orchestrieren, erstellen Sie eine Callback-Funktion, die die Speichergenerierung auslöst. Sie können entweder eine Teilmenge von Ereignissen (mit callback_context.add_events_to_memory) oder alle Ereignisse in einer Sitzung (mit callback_context.add_session_to_memory) zur Verarbeitung im Hintergrund senden:

  from google.adk.agents.callback_context import CallbackContext

  async def generate_memories_callback(callback_context: CallbackContext):
      # Option 1 (Recommended): Send events to Memory Bank for memory generation,
      # which is ideal for incremental processing of events.
      await callback_context.add_events_to_memory(
        events=callback_context.session.events[-5:-1])

      # Option 2: Send the full session to Memory Bank for memory generation.
      # It's recommended to only call this at the end of a session to minimize
      # how many times a single event is re-processed.
      await callback_context.add_session_to_memory()

      return None

Tool zum Abrufen von Informationen aus dem Speicher definieren

Wenn Sie Ihren ADK-Agenten entwickeln, fügen Sie ein Tool für Erinnerungen ein. Dieses legt fest, wann der Agent Erinnerungen abruft und wie diese in den Prompt aufgenommen werden.

Wenn Sie PreloadMemoryTool verwenden, ruft Ihr KI-Agent zu Beginn jedes Turns Erinnerungen ab und fügt sie in die Systemanweisung ein. Das ist gut, um einen grundlegenden Kontext über den Nutzer zu schaffen. Wenn Sie LoadMemoryTool verwenden, ruft das Modell dieses Tool auf, wenn es feststellt, dass Erinnerungen erforderlich sind, um die Nutzeranfrage zu beantworten.

  from google import adk
  from google.adk.tools.load_memory_tool import LoadMemoryTool
  from google.adk.tools.preload_memory_tool import PreloadMemoryTool

  memory_retrieval_tools = [
    # Option 1: Retrieve memories at the start of every turn.
    PreloadMemoryTool(),
    # Option 2: Retrieve memories via tool calls. The model will only call this tool
    # when it decides that memories are necessary to respond to the user query.
    LoadMemoryTool()
  ]

  agent = adk.Agent(
      model="gemini-2.5-flash",
      name='stateful_agent',
      instruction="""You are a Vehicle Voice Agent, designed to assist users with information and in-vehicle actions.

  1.  **Direct Action:** If a user requests a specific vehicle function (e.g., "turn on the AC"), execute it immediately using the corresponding tool. You don't have the outcome of the actual tool execution, so provide a hypothetical tool execution outcome.
  2.  **Information Retrieval:** Respond concisely to general information requests with your own knowledge (e.g., restaurant recommendation).
  3.  **Clarity:** When necessary, try to seek clarification to better understand the user's needs and preference before taking an action.
  4.  **Brevity:** Limit responses to under 30 words.
  """,
      tools=memory_retrieval_tools,
      after_agent_callback=generate_memories_callback
  )

Alternativ können Sie ein eigenes benutzerdefiniertes Tool zum Abrufen von Erinnerungen erstellen. Das ist hilfreich, wenn Sie Ihrem Agent Anweisungen dazu geben möchten, wann Erinnerungen abgerufen werden sollen:

  from google import adk
  from google.adk.tools import ToolContext, FunctionTool

  async def search_memories(query: str, tool_context: ToolContext):
    """Query this tool when you need to fetch information about user preferences."""
    return await tool_context.search_memory(query)

  agent = adk.Agent(
      model="gemini-2.5-flash",
      name='stateful_agent',
      instruction="""...""",
      tools=[FunctionTool(func=search_memories)],
      after_agent_callback=generate_memories_callback
  )

Memory-Dienst und ‑Laufzeit für ADK Memory Bank definieren

Nachdem Sie einen Agent mit Speicherfunktion erstellt haben, müssen Sie ihn mit einem Speicherdienst verknüpfen. Die Konfiguration Ihres ADK-Speicherdienstes hängt davon ab, wo Ihr ADK-Agent ausgeführt wird. Dieser orchestriert die Ausführung Ihrer Agents, Tools und Callbacks.

Sie müssen zuerst eine Agent Engine-Instanz erstellen, die Sie für Memory Bank verwenden können. Dieser Schritt ist optional, wenn Sie Agent Engine Runtime zum Bereitstellen Ihres KI-Agenten verwenden. Weitere Informationen zum Anpassen des Verhaltens von Memory Bank finden Sie auf der Seite „Memory Bank einrichten“ im Abschnitt Agent Engine-Instanz für Memory Bank konfigurieren.

import vertexai

client = vertexai.Client(
  project="PROJECT_ID",
  location="LOCATION"
)
# If you don't have an Agent Engine instance already, create an Agent Engine
# Memory Bank instance using the default configuration.
agent_engine = client.agent_engines.create()

# Optionally, print out the Agent Engine resource name. You will need the
# resource name if you want to interact with your Agent Engine instance later on.
print(agent_engine.api_resource.name)

agent_engine_id = agent_engine.api_resource.name.split("/")[-1]

Ersetzen Sie Folgendes:

PROJECT_ID: Ihre Projekt-ID.
LOCATION: Ihre Region. Unterstützte Regionen für Memory Bank

Übergeben Sie dann die Agent Engine-ID an die Laufzeit- oder Bereitstellungsskripts, damit Ihr Agent Memory Bank als ADK-Speicherdienst verwendet.

Lokaler Runner

adk.Runner wird in der Regel in einer lokalen Umgebung wie Colab verwendet. In diesem Fall müssen Sie den Speicherdienst und den Runner direkt erstellen.

import asyncio

from google.adk.memory import VertexAiMemoryBankService
from google.adk.sessions import VertexAiSessionService
from google.genai import types

memory_service = VertexAiMemoryBankService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id=agent_engine_id
)

# You can use any ADK session service. This example uses Agent Engine Sessions.
session_service = VertexAiSessionService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id=agent_engine_id
)

runner = adk.Runner(
    agent=agent,
    app_name="APP_NAME",
    session_service=session_service,
    memory_service=memory_service
)

async def call_agent(query, session, user_id):
  content = types.Content(role='user', parts=[types.Part(text=query)])
  events = runner.run_async(
    user_id=user_id, session_id=session, new_message=content)

  async for event in events:
      if event.is_final_response():
          final_response = event.content.parts[0].text
          print("Agent Response: ", final_response)

Ersetzen Sie Folgendes:

PROJECT_ID: Ihre Projekt-ID.
LOCATION: Ihre Region. Unterstützte Regionen für Memory Bank
APP_NAME: ADK-App-Name. Der App-Name wird im scope-Dictionary der generierten Erinnerungen angegeben, damit Erinnerungen sowohl für Nutzer als auch für Apps isoliert werden.

Agent Engine

Die Agent Engine ADK-Vorlage (AdkApp) kann sowohl lokal als auch zum Bereitstellen eines ADK-Agents in der Agent Engine-Laufzeit verwendet werden. Wenn das Agent Engine ADK-Template in der Agent Engine-Laufzeit bereitgestellt wird, wird VertexAiMemoryBankService als Standardspeicherdienst verwendet. Dabei wird dieselbe Agent Engine-Instanz für Memory Bank wie für die Agent Engine-Laufzeit genutzt. Sie können also Ihre Memory Bank-Instanz erstellen und in einem einzigen Schritt in einer Laufzeitumgebung bereitstellen.

Weitere Informationen zum Einrichten der Agent Engine-Laufzeit, einschließlich der Anpassung des Verhaltens Ihrer Memory Bank, finden Sie unter Agent Engine konfigurieren.

Mit dem folgenden Code können Sie Ihren speicherfähigen ADK-Agenten in der Agent Engine-Laufzeit bereitstellen:

import asyncio

import vertexai
from vertexai.agent_engines import AdkApp

client = vertexai.Client(
  project="PROJECT_ID",
  location="LOCATION"
)

adk_app = AdkApp(agent=agent)

# Create a new Agent Engine with your agent deployed to Agent Engine Runtime.
# The Agent Engine instance will also include an empty Memory Bank.
agent_engine = client.agent_engines.create(
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"]
      }
)

# Alternatively, update an existing Agent Engine to deploy your agent to Agent Engine Runtime.
# Your agent will have access to the Agent Engine instance's existing memories.
agent_engine = client.agent_engines.update(
      name=agent_engine.api_resource.name,
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"]
      }
)

async def call_agent(query, session_id, user_id):
    async for event in agent_engine.async_stream_query(
        user_id=user_id,
        session_id=session_id,
        message=query,
    ):
        print(event)

Ersetzen Sie Folgendes:

PROJECT_ID: Ihre Projekt-ID.
LOCATION: Ihre Region. Unterstützte Regionen für Memory Bank
STAGING_BUCKET: Ihr Cloud Storage-Bucket, der für das Staging Ihrer Agent Engine-Laufzeit verwendet werden soll.

Bei der lokalen Ausführung verwendet das ADK-Template InMemoryMemoryService als Standardspeicherdienst. Sie können den Standardspeicherdienst jedoch überschreiben, um VertexAiMemoryBankService zu verwenden:

def memory_bank_service_builder():
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="LOCATION",
        agent_engine_id="AGENT_ENGINE_ID"
    )

adk_app = AdkApp(
      agent=adk_agent,
      # Override the default memory service.
      memory_service_builder=memory_bank_service_builder
)

async def call_agent(query, session_id, user_id):
  # adk_app is a local agent. If you want to deploy it to Agent Engine Runtime,
  # use `client.agent_engines.create(...)` or `client.agent_engines.update(...)`
  # and call the returned Agent Engine instance instead.
  async for event in adk_app.async_stream_query(
      user_id=user_id,
      session_id=session_id,
      message=query,
  ):
      print(event)

Ersetzen Sie Folgendes:

PROJECT_ID: Ihre Projekt-ID.
LOCATION: Ihre Region. Unterstützte Regionen für Memory Bank
AGENT_ENGINE_ID: Die Agent Engine-ID, die für die Memory Bank verwendet werden soll. Beispiel: 456 in projects/my-project/locations/us-central1/reasoningEngines/456.

Cloud Run

Informationen zum Bereitstellen Ihres Agenten in Cloud Run finden Sie in der ADK-Dokumentation.

adk deploy cloud_run \
    ...
    --memory_service_uri=agentengine://AGENT_ENGINE_ID

GKE

Informationen zum Bereitstellen Ihres Agents in Google Kubernetes Engine (GKE) finden Sie in der ADK-Dokumentation. Dort wird beschrieben, wie Sie Ihren Agent für die Bereitstellung in GKE definieren.

adk deploy gke \
    ...
    --memory_service_uri=agentengine://AGENT_ENGINE_ID

ADK Web

Über die ADK-Weboberfläche können Sie Ihre Agents direkt im Browser testen.

export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="LOCATION"

adk web --memory_service_uri=agentengine://AGENT_ENGINE_ID

Ersetzen Sie Folgendes:

PROJECT_ID: Ihre Projekt-ID.
LOCATION: Ihre Region. Unterstützte Regionen für Memory Bank
AGENT_ENGINE_ID: Die Agent Engine-ID, die für die Memory Bank verwendet werden soll. Zum Beispiel 456 in projects/my-project/locations/us-central1/reasoningEngines/456.

Mit dem Agent interagieren

Nachdem Sie Ihren Agenten definiert und die Memory Bank eingerichtet haben, können Sie mit ihm interagieren. Wenn Sie beim Initialisieren Ihres Agents einen Callback zum Auslösen der Speichergenerierung angegeben haben, wird die Speichergenerierung jedes Mal ausgelöst, wenn der Agent aufgerufen wird.

Erinnerungen werden mit dem Bereich {"user_id": USER_ID, "app_name": APP_NAME} gespeichert, der der Nutzer-ID und dem App-Namen entspricht, die zum Ausführen Ihres Agents verwendet werden.

Die Methode zur Interaktion mit Ihrem Agent hängt von der Ausführungsumgebung ab:

Lokaler Runner

# Use `asyncio.run(session_service.create(...))` if you're running this
# code as a standard Python script.
session = await session_service.create_session(
    app_name="APP_NAME",
    user_id="USER_ID"
)

# Use `asyncio.run(call_agent(...))` if you're running this code as a
# standard Python script.
await call_agent(
    "Can you fix the temperature?",
    session.id,
    "USER_ID"
)

Ersetzen Sie Folgendes:

APP_NAME: App-Name für Ihren Runner.
USER_ID: Eine Kennung für Ihren Nutzer. Erinnerungen, die aus dieser Sitzung generiert werden, werden mit dieser intransparenten Kennung versehen. Der Umfang der generierten Erinnerungen wird als {"user_id": "USER_ID"} gespeichert.

Agent Engine

Wenn Sie das Agent Engine ADK-Template verwenden, können Sie die Agent Engine-Laufzeit aufrufen, um mit dem Speicher und den Sitzungen zu interagieren.

# Use `asyncio.run(agent_engine.async_create_session(...))` if you're
# running this code as a standard Python script.
session = await agent_engine.async_create_session(user_id="USER_ID")

# Use `asyncio.run(call_agent(...))` if you're running this code as a
# standard Python script.
await call_agent(
    "Can you fix the temperature?",
    session.get("id"),
    "USER_ID"
)

Ersetzen Sie Folgendes:

USER_ID: Eine Kennung für Ihren Nutzer. Erinnerungen, die aus dieser Sitzung generiert werden, werden mit dieser intransparenten Kennung versehen. Der Umfang der generierten Erinnerungen wird als {"user_id": "USER_ID"} gespeichert.

Cloud Run

Weitere Informationen finden Sie im Abschnitt Agent testen der Dokumentation zur ADK Cloud Run-Bereitstellung.

GKE

Weitere Informationen finden Sie im Abschnitt Agent testen der ADK-Dokumentation zur GKE-Bereitstellung.

ADK Web

Wenn Sie ADK Web verwenden möchten, rufen Sie den lokalen Server unter http://localhost:8000 auf.

Standardmäßig wird die Nutzer-ID in ADK Web auf user festgelegt. Wenn Sie die Standardnutzer-ID überschreiben möchten, fügen Sie userId in die Abfrageparameter ein, z. B. http://localhost:8000?userId=YOUR_USER_ID.

Weitere Informationen finden Sie in der ADK-Dokumentation auf der Seite ADK Web.

Beispiel für eine Interaktion

Erste Sitzung

Wenn Sie PreloadMemoryTool verwendet haben, versucht der KI-Agent, zu Beginn jedes Turns Erinnerungen abzurufen, um auf Einstellungen zuzugreifen, die der Nutzer dem KI-Agenten zuvor mitgeteilt hat. Bei der ersten Interaktion des Agents mit dem Nutzer sind keine Erinnerungen verfügbar, die abgerufen werden könnten. Daher kennt der Agent keine Nutzerpräferenzen wie die bevorzugte Temperatur, wie im folgenden Beispiel gezeigt:

Erster Zug:
- Nutzer: „Kannst du die Temperatur anpassen?“
- (Toolaufruf): ADK versucht, Erinnerungen abzurufen. Es sind jedoch keine Erinnerungen verfügbar.
- Modell: „Welche Temperatur bevorzugst du?“
- (Callback): Das ADK löst die Generierung von Erinnerungen aus. Es werden keine Erinnerungen extrahiert.
Zweiter Zug:
- Nutzer: Ich fühle mich bei 22 Grad wohl.
- (Toolaufruf): ADK versucht, Erinnerungen abzurufen. Es sind jedoch keine Erinnerungen verfügbar.
- Modell: Okay, ich habe die Temperatur auf 22 Grad aktualisiert.
- (Callback): Das ADK löst die Generierung von Erinnerungen aus. Der Speicher „Ich mag die Temperatur von 22 Grad“ wird erstellt.

Zweite Sitzung

Der extrahierte Speicher ist für die nächste Sitzung für denselben App-Namen und dieselbe Nutzer-ID verfügbar. Wenn der Nutzer ähnliche oder widersprüchliche Informationen zu vorhandenen Erinnerungen angibt, werden die neuen Informationen mit den vorhandenen Erinnerungen zusammengeführt.

Erste Runde
- Nutzer: Fix the temperature. Das ist so unangenehm!
- (Toolaufruf): Das ADK versucht, Erinnerungen abzurufen. Die Erinnerung „Ich mag die Temperatur von 22 Grad“ wird abgerufen.
- Modell: Okay, ich habe die Temperatur auf 22 Grad aktualisiert.
- (Callback): Das ADK löst die Generierung von Erinnerungen aus. Es werden keine Erinnerungen extrahiert, da der Nutzer nichts geteilt hat, was gespeichert werden könnte.
Zweite Runde
- Nutzer: Ich hätte es lieber wärmer am Morgen.
- (Toolaufruf): Das ADK versucht, Erinnerungen abzurufen. Die Erinnerung „Ich mag die Temperatur von 22 Grad“ wird abgerufen.
- Modell: Okay, ich habe die Temperatur erhöht.
- (Callback): Das ADK löst die Generierung von Erinnerungen aus. Die vorhandene Erinnerung „Ich mag die Temperatur von 22 Grad“ wird zu „Ich mag die Temperatur von 22 Grad im Allgemeinen, aber morgens mag ich es wärmer“ aktualisiert.

Bereinigen

Wenn Sie alle in diesem Projekt verwendeten Ressourcen bereinigen möchten, können Sie das Google Cloud -Projekt löschen, das Sie für den Schnellstart verwendet haben.

Andernfalls können Sie die einzelnen Ressourcen löschen, die Sie in dieser Anleitung erstellt haben:

Verwenden Sie das folgende Codebeispiel, um die Vertex AI Agent Engine-Instanz zu löschen. Dadurch werden auch alle Sitzungen oder Erinnerungen gelöscht, die zu dieser Vertex AI Agent Engine gehören.
```
agent_engine.delete(force=True)
```
Löschen Sie alle lokal erstellten Dateien.

Nächste Schritte

Kurzanleitung für das Agent Engine SDK

Kurzanleitung für das Agent-Entwicklungs-Kit Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Erinnerungen mit dem ADK-Speicherdienst und Memory Bank verwalten

Hinweise

Umgebungsvariablen festlegen

ADK-Agent erstellen

Callback für die Speichergenerierung definieren

Tool zum Abrufen von Informationen aus dem Speicher definieren

Memory-Dienst und ‑Laufzeit für ADK Memory Bank definieren

Lokaler Runner

Agent Engine

Cloud Run

GKE

ADK Web

Mit dem Agent interagieren

Lokaler Runner

Agent Engine

Cloud Run

GKE

ADK Web

Beispiel für eine Interaktion

Bereinigen

Nächste Schritte

Kurzanleitung für das Agent-Entwicklungs-Kit