Kurzanleitung für Agent Platform Memory Bank mit dem Agent Development Kit

Mit der Agent Platform Memory Bank können Ihre Agents Langzeiterinnerungen sitzungsübergreifend verwalten. Wenn Sie sie mit dem Agent Development Kit (ADK) verwenden, kann Ihr Agent automatisch Aufrufe an die Memory Bank orchestrieren, um Erinnerungen basierend auf Nutzerinteraktionen zu speichern und abzurufen.

In diesem Dokument wird erläutert, wie Sie einen ADK-Agenten erstellen, ihn für die Verwendung der Memory Bank konfigurieren und mit ihm interagieren, um Erinnerungen zu generieren und darauf zuzugreifen.

Informationen zu direkten Aufrufen der API ohne ADK finden Sie in der Kurzanleitung zur Memory Bank API.

Erinnerungen mit dem ADK-Speicherdienst und der Memory Bank verwalten

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

Die VertexAiMemoryBankService-Schnittstelle umfasst:

  • memory_service.add_session_to_memory löst eine GenerateMemories-Anfrage an die Memory Bank aus , wobei alle Ereignisse in der bereitgestellten adk.Session als Quellinhalt verwendet werden. Sie können Aufrufe an diese 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 löst eine GenerateMemories Anfrage an die Memory Bank mit einer Teilmenge von Ereignissen aus. Sie können Aufrufe an diese 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 die Memory Bank aus, um relevante Erinnerungen für die aktuelle user_id und app_name abzurufen. Sie können Aufrufe an diese Methode mit integrierten Speichertools (LoadMemoryTool oder PreloadMemoryTool) oder einem benutzerdefinierten Tool orchestrieren, das tool_context.search_memory aufruft.

Hinweis

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

Legen Sie die Umgebungsvariablen fest, um das ADK zu verwenden:

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:

  • PROJECT_ID: Ihre Projekt-ID.
  • LOCATION: Ihre Region. Informationen zu den unterstützten Regionen für die Memory Bank

ADK-Agenten erstellen

Wenn Sie einen Agenten mit Speicherfunktion erstellen möchten, richten Sie Tools und Callbacks ein, die Aufrufe an Ihren Speicherdienst orchestrieren.

Callback für das Merken von Informationen definieren

Um Aufrufe für das Merken von Informationen zu orchestrieren, erstellen Sie eine Callback-Funktion, die das Merken von Informationen 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 Erinnerungen definieren

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

Wenn Sie PreloadMemoryTool verwenden, ruft Ihr Agent zu Beginn jeder Runde Erinnerungen ab und fügt sie in die Systemanweisung ein. Das ist gut, um einen grundlegenden Kontext zum Nutzer zu erstellen. Wenn Sie LoadMemoryTool verwenden, ruft das Modell dieses Tool auf, wenn es feststellt, dass Erinnerungen erforderlich sind, um die Nutzerabfrage 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 Agenten Anweisungen geben möchten, wann er Erinnerungen abrufen soll:

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
)

ADK Memory Bank-Speicherdienst und -Laufzeit definieren

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

Agent Runtime-Instanz erstellen

Sie müssen zuerst eine Agent Runtime-Instanz für die Memory Bank erstellen. Dieser Schritt ist optional, wenn Sie Agent Runtime verwenden, um Ihren Agenten bereitzustellen. Weitere Informationen zum Anpassen des Verhaltens der Memory Bank finden Sie im Abschnitt Agent Runtime-Instanz für die Memory Bank konfigurieren auf der Seite Memory Bank einrichten.

import vertexai

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

# Optionally, print out the resource name. You will need the
# resource name if you want to interact with your Runtime 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. Informationen zu den unterstützten Regionen für die Memory Bank

ADK-Laufzeit erstellen

Übergeben Sie die Agent Runtime-ID an die Laufzeit- oder Bereitstellungsskripts, damit Ihr Agent die 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 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. Informationen zu den unterstützten Regionen für die Memory Bank
  • APP_NAME: ADK-App-Name. Der App-Name wird in das scope-Wörterbuch der generierten Erinnerungen aufgenommen, damit Erinnerungen sowohl für Nutzer als auch für Apps isoliert werden.
  • AGENT_ENGINE_ID: Die Agent Runtime-ID, die für die Memory Bank und Agent Platform-Sitzungen verwendet werden soll. Beispiel: 456 in projects/my-project/locations/us-central1/reasoningEngines/456.

Laufzeit für KI-Agenten

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

Weitere Informationen zum Einrichten Ihrer Agent Runtime-Instanz, einschließlich zum Anpassen des Verhaltens Ihrer Memory Bank, finden Sie unter Agent Runtime konfigurieren.

Verwenden Sie den folgenden Code, um Ihren ADK-Agenten mit Speicherfunktion in der Agent Runtime bereitzustellen:

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 resource with your agent deployed to Agent Runtime.
# The Agent Runtime 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 resource to deploy your agent to Agent Platform.
# Your agent will have access to the Runtime 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. Informationen zu den unterstützten Regionen für die Memory Bank
  • STAGING_BUCKET: Ihr Cloud Storage-Bucket, der für das Staging Ihrer Agent Runtime verwendet werden soll.

Bei der lokalen Ausführung verwendet die ADK-Vorlage 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 Runtime,
  # use `client.agent_engines.create(...)` or `client.agent_engines.update(...)`
  # and call the returned Agent Runtime 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. Informationen zu den unterstützten Regionen für die Memory Bank
  • AGENT_ENGINE_ID: Die Agent Runtime-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. Dort wird erläutert, wie Sie Ihren Agenten für die Bereitstellung in Cloud Run definieren.

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

GKE

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

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

ADK Web

Über die ADK-Web oberflä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. Informationen zu den unterstützten Regionen für die Memory Bank
  • AGENT_ENGINE_ID: Die Agent Runtime-ID, die für die Memory Bank verwendet werden soll. 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 Ihrem Agenten interagieren. Wenn Sie beim Initialisieren Ihres Agenten einen Callback für die Speicher generierung angegeben haben, wird die Speicher generierung 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 Agenten verwendet werden.

Die Methode zur Interaktion mit Ihrem Agenten hängt von seiner 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 undurchsichtigen Kennung versehen. Der Bereich der generierten Erinnerungen wird als {"user_id": "USER_ID"} gespeichert.

Laufzeit für KI-Agenten

Wenn Sie die ADK-Vorlage verwenden, können Sie Ihre Agent Runtime aufrufen, um mit Speicher und 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 undurchsichtigen Kennung versehen. Der Bereich der generierten Erinnerungen wird als {"user_id": "USER_ID"} gespeichert.

Cloud Run

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

GKE

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

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 gesetzt. Wenn Sie die Standard Nutzer-ID überschreiben möchten, fügen Sie userId in die Suchparameter ein, wie http://localhost:8000?userId=YOUR_USER_ID.

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

Beispielinteraktion

Erste Sitzung

Wenn Sie PreloadMemoryTool verwendet haben, versucht der Agent zu Beginn jeder Runde, Erinnerungen abzurufen, um auf Einstellungen zuzugreifen, die der Nutzer dem Agenten zuvor mitgeteilt hat. Bei der ersten Interaktion des Agenten mit dem Nutzer sind keine Erinnerungen verfügbar. Daher kennt der Agent keine Nutzereinstellungen, z. B. die bevorzugte Temperatur, wie im folgenden Beispiel gezeigt:

  1. Erste Runde:

    • Nutzer: "Kannst du die Temperatur anpassen?"

    • (Toolaufruf): ADK versucht, Erinnerungen abzurufen. Es sind keine Erinnerungen verfügbar.

    • Modell: "Welche Temperatur bevorzugen Sie?"

    • (Callback): ADK löst das Merken von Informationen aus. Es werden keine Erinnerungen extrahiert.

  2. Zweite Runde:

    • Nutzer: „Ich fühle mich bei 22 Grad wohl.“

    • (Toolaufruf): ADK versucht, Erinnerungen abzurufen. Es sind keine Erinnerungen verfügbar.

    • Modell: „Ok, ich habe die Temperatur auf 22 Grad aktualisiert.“

    • (Callback): ADK löst das Merken von Informationen aus. Die Erinnerung „Ich mag die Temperatur von 22 Grad“ wird erstellt.

Zweite Sitzung

Die extrahierte Erinnerung 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.

  1. Erste Runde

    • Nutzer: „Stell die Temperatur ein.“ Es ist so unangenehm!

    • (Toolaufruf): ADK versucht, Erinnerungen abzurufen. Die Erinnerung "Ich mag die Temperatur von 22 Grad" wird abgerufen.

    • Modell: „Ok, ich habe die Temperatur auf 22 Grad aktualisiert.“

    • (Callback): ADK löst das Merken von Informationen aus. Es werden keine Erinnerungen extrahiert, da der Nutzer nichts Sinnvolles mitgeteilt hat, das gespeichert werden könnte.

  2. Zweite Runde

    • Nutzer: „Eigentlich mag ich es morgens lieber wärmer.“

    • (Toolaufruf): ADK versucht, Erinnerungen abzurufen. Die Erinnerung "Ich mag die Temperatur von 22 Grad" wird abgerufen.

    • Modell: „Ok, ich habe die Temperatur erhöht.“

    • (Callback): ADK löst das Merken von Informationen aus. Die vorhandene Erinnerung „Ich mag die Temperatur von 22 Grad“ wird in „Ich mag die Temperatur im Allgemeinen bei 22 Grad, aber morgens mag ich es wärmer“ geändert.

Multiregionale Memory Bank mit einer regionalen Laufzeit verwenden

Standardmäßig werden Ihr Agent und Ihre Memory Bank in derselben Region bereitgestellt. Sie können sie jedoch entkoppeln, um eine multiregionale Memory Bank (z. B. us) mit einer regionalen Laufzeit (z. B. us-central1) zu verwenden. Mit dieser Konfiguration können Sie eine zentrale Memory Bank für verschiedene regionale Bereitstellungen verwenden.

Wenn Sie eine multiregionale Memory Bank verwenden möchten, müssen Sie den Standard-ADK-Speicherdienst-Builder überschreiben, um auf den multiregionalen Standort und die entsprechende Laufzeit-ID zu verweisen.

import vertexai
from google.adk.memory import VertexAiMemoryBankService
from vertexai.agent_engines import AdkApp

# Create the Memory Bank store in a multi-region location (for example, 'us')
client_mb = vertexai.Client(project="PROJECT_ID", location="us")
mb_engine = client_mb.agent_engines.create()
mb_engine_id = mb_engine.api_resource.name.split(\"/\")[-1]


# Point your memory service to the 'us' location, 'us' Memory Bank
def memory_bank_service_builder():
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="us",
        agent_engine_id=mb_engine_id
    )

# Create the AdkApp with the overridden builder
adk_app = AdkApp(
    agent=agent,
    memory_service_builder=memory_bank_service_builder
)

# Deploy the runtime to a specific region (for example, 'us-central1')
client_runtime = vertexai.Client(project="PROJECT_ID", location="us-central1")
agent_engine = client_runtime.agent_engines.create(
    agent=adk_app,
    config={
        "staging_bucket": "STAGING_BUCKET",
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"]
    }
)

Ersetzen Sie Folgendes:

  • PROJECT_ID: Ihre Projekt-ID.
  • STAGING_BUCKET: Ihr Cloud Storage-Bucket, der für das Staging Ihrer Agent Runtime verwendet werden soll.

Bereinigen

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

Andernfalls können Sie die einzelnen Ressourcen löschen, die Sie in dieser Anleitung erstellt haben. Gehen Sie dazu so vor:

  1. Verwenden Sie das folgende Codebeispiel, um die Agent Runtime-Instanz zu löschen. Dadurch werden auch alle Sitzungen oder Erinnerungen gelöscht, die zu dieser Laufzeit gehören.

    agent_engine.delete(force=True)

  2. Löschen Sie alle lokal erstellten Dateien.

Nächste Schritte

Kurzanleitung

Erste Schritte mit der Memory Bank API zum Verwalten von Langzeiterinnerungen.