Das Agent Development Kit (ADK) verbindet KI-Agenten über VertexAiMemoryBankService, eine Implementierung der ADK-Schnittstelle BaseMemoryService, mit der Memory Bank der Agent Platform. In diesem Dokument wird erläutert, wie Sie ein Tool für den Abruf und Callback von gemerkten Informationen auswählen und wie Sie den Dienst für gemerkte Informationen in den einzelnen ADK-Laufzeiten verbinden.
Wenn Sie zuerst ein vollständiges Beispiel ausführen möchten, lesen Sie die Kurzanleitung für Memory Bank mit ADK.
Hinweis
- Melden Sie sich in Ihrem Google Cloud Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie einfach ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.-
Wenn Sie eine lokale Shell verwenden, erstellen Sie lokale Authentifizierungsdaten für Ihr Nutzerkonto:
gcloud auth application-default login
Wenn Sie Cloud Shell verwenden, ist dies nicht erforderlich.
Wenn ein Authentifizierungsfehler zurückgegeben wird und Sie einen externen Identitätsanbieter (IdP) verwenden, prüfen Sie, ob Sie sich mit Ihrer föderierten Identität in der gcloud CLI angemeldet haben.
- Installieren Sie das ADK und das Agent Platform SDK:
pip install --upgrade "google-adk[gcp]" "google-cloud-agentplatform>=2.0.1"
- Erstellen Sie eine Memory Bank-Instanz in der Google Cloud Console oder mit dem Agent Platform SDK. Klicken Sie auf der Seite Memory Bank auf Mit einem KI-Agenten verknüpfen > Mit ADK verwenden, um den vorausgefüllten Einrichtungscode zu erhalten. Überspringen Sie diesen Schritt, wenn die Agent Runtime die Instanz für Sie erstellt.
Erforderliche Rollen
Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen einer Memory Bank-Instanz und zum Generieren und Abrufen von gemerkten Informationen benötigen:
- Memory Bank-Instanz erstellen oder aktualisieren: Agent Platform User (`roles/aiplatform.user`)
- Gemerkte Informationen lesen, schreiben oder generieren: Memory Bank User (`roles/aiplatform.memoryUser`)
Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.
Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.
So funktionieren ADK-Komponenten mit der Memory Bank
Ein ADK-Agent verwendet die folgenden Komponenten, um gemerkte Informationen zu lesen und zu schreiben:
| Komponente | Rolle | Erforderlich |
|---|---|---|
| Memory Bank-Instanz | Speichert und konsolidiert Erinnerungen. | Ja |
VertexAiMemoryBankService |
Verbindet Ihren KI-Agenten mit Memory Bank als ADK-Speicherdienst. | Ja |
| Sitzungsdienst | Speichert den Unterhaltungsverlauf. Sie können einen beliebigen ADK-Sitzungsdienst verwenden. | Ja |
| Tool zum Abrufen von gemerkten Informationen | Ruft gemerkte Informationen für den Agenten ab. Weitere Informationen finden Sie unter Gemerkte Informationen mit einem Tool abrufen. | Gemerkte Informationen lesen |
| Callback für das Merken von Informationen | Sendet Unterhaltungsereignisse an die Memory Bank, nachdem der Agent geantwortet hat. Weitere Informationen finden Sie unter Erinnerungen mit einem Callback generieren. | Informationen merken |
ADK Runner oder AdkApp |
Orchestriert den Agenten, die Dienste, die Tools und die Callbacks. | Ja |
Das folgende Diagramm zeigt, wie diese Komponenten bei jedem Turn interagieren, wenn ein Agent PreloadMemoryTool und einen Memory-Callback verwendet:
Die Memory Bank ordnet jede gemerkte Information der Nutzer-ID und dem App-Namen zu, die Ihren KI-Agenten ausführen, als {"user_id": USER_ID, "app_name": APP_NAME}. Nur Anfragen mit derselben Nutzer-ID und demselben App-Namen rufen diese gemerkten Informationen ab.
Gemerkte Informationen mit einem Callback generieren
Ein Callback zur Generierung von Erinnerungen sendet Unterhaltungsereignisse an die Memory Bank. Die Memory Bank extrahiert gemerkte Informationen aus diesen Ereignissen und konsolidiert sie mit vorhandenen gemerkten Informationen. Wählen Sie eine Methode aus, je nachdem, wie oft Sie Ereignisse verarbeiten:
| Methode | Gesendete Ereignisse | Geeignet für |
|---|---|---|
callback_context.add_events_to_memory |
Eine von Ihnen ausgewählte Teilmenge von Ereignissen | Recommended. Ereignisse inkrementell verarbeiten, z. B. nach jedem Zug. |
callback_context.add_session_to_memory |
Alle Ereignisse in der Sitzung | Rufen Sie die Methode einmal am Ende einer Sitzung auf, damit dieselben Ereignisse nicht mehrmals verarbeitet werden. |
Im folgenden Beispiel werden nach jeder KI-Agentenantwort aktuelle Ereignisse gesendet:
from google.adk.agents.callback_context import CallbackContext
async def generate_memories_callback(
callback_context: CallbackContext,
) -> None:
await callback_context.add_events_to_memory(
events=callback_context.session.events[-5:]
)
return None
Wenn Sie stattdessen die gesamte Sitzung senden möchten, rufen Sie await callback_context.add_session_to_memory() in einem Callback am Ende der Sitzung auf.
Standardmäßig sendet VertexAiMemoryBankService Ereignisse über die Ereignisaufnahme. Wenn Sie in Tests oder Demos warten möchten, bis die Speichergenerierung abgeschlossen ist, übergeben Sie custom_metadata={"wait_for_completion": True} an add_events_to_memory.
Gemerkte Informationen mit einem Tool abrufen
Ein Tool zum Abrufen von gemerkten Informationen steuert, wann der Agent gemerkte Informationen abruft und wie diese in den Prompt aufgenommen werden. Wählen Sie eines der folgenden Tools aus:
| Tool | Wann gemerkte Informationen abgerufen werden | Geeignet für |
|---|---|---|
PreloadMemoryTool |
Zu Beginn jeder Runde. Gemerkte Informationen werden vor der aktuellen Nutzerrunde in den Kontext der Modellanfrage eingefügt. | Ermitteln Sie bei jeder Interaktion den grundlegenden Kontext des Nutzers. |
LoadMemoryTool |
Wenn das Modell entscheidet, dass gemerkte Informationen zum Beantworten der Anfrage erforderlich sind. | Das Modell entscheidet, wann gemerkte Informationen relevant sind. |
Benutzerdefiniert FunctionTool |
Wenn das Modell Ihr Tool aufruft, wird es von der Beschreibung des Tools geleitet. | Geben Sie dem KI-Agenten Anweisungen dazu, wann er gemerkte Informationen abrufen soll. |
Im folgenden Beispiel wird ein Agent erstellt, der PreloadMemoryTool und den Callback aus dem vorherigen Abschnitt verwendet:
from google import adk
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
agent = adk.Agent(
model="gemini-3.5-flash",
name="stateful_agent",
instruction="You are a vehicle voice agent. Limit responses to 30 words.",
tools=[PreloadMemoryTool()],
after_agent_callback=generate_memories_callback,
)
Wenn Sie das Modell entscheiden lassen möchten, wann gemerkte Informationen abgerufen werden sollen, importieren Sie LoadMemoryTool aus google.adk.tools.load_memory_tool und übergeben Sie LoadMemoryTool() in tools.
Wenn Sie ein benutzerdefiniertes Abruftool schreiben möchten, rufen Sie tool_context.search_memory über einen Toolaufruf auf:
from typing import Any
from google import adk
from google.adk.tools import FunctionTool, ToolContext
async def search_memories(query: str, tool_context: ToolContext) -> Any:
"""Query this tool when you need information about user preferences."""
return await tool_context.search_memory(query)
agent = adk.Agent(
model="gemini-3.5-flash",
name="stateful_agent",
instruction=(
"You are a vehicle voice agent. Before you change a setting, call "
"search_memories to look up the user's preferences. Limit responses "
"to 30 words."
),
tools=[FunctionTool(func=search_memories)],
after_agent_callback=generate_memories_callback,
)
Memory-Dienst mit der Laufzeit verbinden
Wie Sie VertexAiMemoryBankService verbinden, hängt davon ab, wo Ihr Agent ausgeführt wird. Laufzeit auswählen:
Lokaler Runner
Wenn Sie Ihren Agenten mit adk.Runner ausführen, erstellen Sie den Memory-Dienst und übergeben Sie ihn an den Runner:
import asyncio
import os
from google import adk
from google.adk.memory import VertexAiMemoryBankService
from google.adk.sessions import InMemorySessionService
from google.genai import types
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "LOCATION"
memory_service = VertexAiMemoryBankService(
project="PROJECT_ID",
location="LOCATION",
agent_engine_id="MEMORY_BANK_ID",
)
# You can use any ADK session service. This example keeps sessions in memory.
# To persist conversation history, use VertexAiSessionService with a
# Sessions instance instead.
session_service = InMemorySessionService()
runner = adk.Runner(
agent=agent,
app_name="APP_NAME",
session_service=session_service,
memory_service=memory_service,
)
async def main() -> None:
session = await session_service.create_session(
app_name="APP_NAME",
user_id="USER_ID",
)
message = types.Content(
role="user", parts=[types.Part(text="Can you fix the temperature?")]
)
async for event in runner.run_async(
user_id="USER_ID",
session_id=session.id,
new_message=message,
):
if event.is_final_response() and event.content:
print(event.content.parts[0].text)
asyncio.run(main())
Ersetzen Sie Folgendes:
- PROJECT_ID: Ihre Google Cloud -Projekt-ID, z. B.
my-project. - LOCATION: Ihr Standort, z. B.
global. Informationen zu Memory Bank finden Sie unter Unterstützte Standorte und Globale und multiregionale Endpunkte. - MEMORY_BANK_ID: Die ID der Memory Bank-Instanz, z. B.
456inprojects/my-project/locations/us-central1/reasoningEngines/456. - APP_NAME: Der Name der ADK-Anwendung, z. B.
my_agent. Die Memory Bank enthält den App-Namen im Speicherbereich, sodass gemerkte Informationen über Apps hinweg isoliert sind. - USER_ID: Eine Kennung für Ihren Nutzer, z. B.
user-123. Gemerkte Informationen, die aus dieser Sitzung generiert werden, sind auf diese Kennung beschränkt.
Agent Runtime auf der Gemini Enterprise Agent Platform
Wenn Sie einen ADK-Agenten mit der ADK-Vorlage (AdkApp) in der Agent Runtime bereitstellen, wird standardmäßig VertexAiMemoryBankService verwendet. Sie können die Memory Bank-Instanz erstellen und den KI-Agenten in einem Schritt bereitstellen:
import asyncio
import agentplatform
from agentplatform.frameworks import AdkApp
client = agentplatform.Client(
project="PROJECT_ID",
location="LOCATION",
)
adk_app = AdkApp(agent=agent)
# Create a resource with your agent deployed to Agent Runtime. The
# resource also includes an empty Memory Bank instance.
runtime_instance = client.runtimes.create(
agent=adk_app,
config={
"staging_bucket": "STAGING_BUCKET",
"requirements": ["google-cloud-agentplatform[runtimes,adk]"],
},
)
async def main() -> None:
session = await runtime_instance.async_create_session(
user_id="USER_ID"
)
async for event in runtime_instance.async_stream_query(
user_id="USER_ID",
session_id=session.get("id"),
message="Can you fix the temperature?",
):
print(event)
asyncio.run(main())
Wenn Sie den KI-Agenten in einer vorhandenen Ressource bereitstellen und die vorhandenen gemerkten Informationen der Ressource beibehalten möchten, rufen Sie stattdessen client.runtimes.update auf:
runtime_instance = client.runtimes.update(
name="RUNTIME_NAME",
agent=adk_app,
config={
"staging_bucket": "STAGING_BUCKET",
"requirements": ["google-cloud-agentplatform[runtimes,adk]"],
},
)
Wenn Sie AdkApp lokal ausführen, wird standardmäßig InMemoryMemoryService verwendet.
Wenn Sie die Memory Bank lokal verwenden möchten, überschreiben Sie den Memory-Dienst:
from google.adk.memory import VertexAiMemoryBankService
def memory_bank_service_builder() -> VertexAiMemoryBankService:
return VertexAiMemoryBankService(
project="PROJECT_ID",
location="LOCATION",
agent_engine_id="MEMORY_BANK_ID",
)
adk_app = AdkApp(
agent=agent,
memory_service_builder=memory_bank_service_builder,
)
Ersetzen Sie Folgendes:
- PROJECT_ID: Ihre Google Cloud -Projekt-ID, z. B.
my-project. - LOCATION: Die Region oder Multiregion Ihrer Agent Runtime, z. B.
us-central1. Nur eigenständigeVertexAiMemoryBankService-Instanzen unterstützenglobal, nichtclient.runtimes.create. Siehe unterstützte Standorte. - STAGING_BUCKET: Der Cloud Storage-Bucket-URI für das Staging Ihrer Agent Runtime, z. B.
gs://my-staging-bucket. - USER_ID: Eine Kennung für Ihren Nutzer, z. B.
user-123. - RUNTIME_NAME: Der Ressourcenname der vorhandenen Agent Runtime im Format
projects/.../locations/.../reasoningEngines/.... - MEMORY_BANK_ID: Die ID der Memory Bank-Instanz, z. B.
456inprojects/my-project/locations/us-central1/reasoningEngines/456.
Cloud Run
Wenn Sie Ihren Agenten in Cloud Run bereitstellen möchten, folgen Sie der ADK-Dokumentation und übergeben Sie Ihre Memory Bank-Instanz als Speicherdienst:
adk deploy cloud_run \
...
--memory_service_uri=agentengine://MEMORY_BANK_ID
Ersetzen Sie MEMORY_BANK_ID durch die Instanz-ID Ihrer Memory Bank, z. B. 456. Informationen zum Testen des bereitgestellten Agenten finden Sie in der Dokumentation zur ADK-Bereitstellung in Cloud Run.
Google Kubernetes Engine (GKE)
Wenn Sie Ihren KI-Agenten in GKE bereitstellen möchten, folgen Sie der ADK-Dokumentation und übergeben Sie Ihre Memory Bank-Instanz als Memory-Dienst:
adk deploy gke \
...
--memory_service_uri=agentengine://MEMORY_BANK_ID
Ersetzen Sie MEMORY_BANK_ID durch die Instanz-ID Ihrer Memory Bank, z. B. 456. Informationen zum Testen des bereitgestellten KI-Agenten finden Sie im Abschnitt KI-Agenten testen der ADK-GKE-Bereitstellungsdokumentation.
ADK Web
ADK Web ist eine lokale Browseroberfläche zum Testen und Prüfen Ihres KI-Agenten während der Entwicklung.
ADK Web liest Ihr Projekt und Ihren Standort aus Umgebungsvariablen. Führen Sie die folgenden Befehle in Ihrem Terminal aus, und zwar in dem Verzeichnis, das Ihren Agentenordner enthält:
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=LOCATION
adk web --memory_service_uri=agentengine://MEMORY_BANK_IDErsetzen Sie Folgendes:
- PROJECT_ID: Ihre Google Cloud -Projekt-ID, z. B.
my-project. - LOCATION: Ihr Standort, z. B.
global. Informationen zu Memory Bank finden Sie unter Unterstützte Standorte und Globale und multiregionale Endpunkte. - MEMORY_BANK_ID: Die ID der Memory Bank-Instanz, z. B.
456.
Öffnen Sie dann http://localhost:8000 in Ihrem Browser. Standardmäßig legt ADK Web die Nutzer-ID auf user fest. Wenn Sie eine andere Nutzer-ID verwenden möchten, fügen Sie den Abfrageparameter userId hinzu, z. B. http://localhost:8000?userId=USER_ID.
Multiregionale Memory Bank mit einer regionalen Laufzeit verwenden
Wenn Sie die Laufzeit mit integrierter Memory Bank verwenden, werden Ihr Agent und die Memory Bank standardmäßig in derselben Region bereitgestellt. Wenn Sie eine zentrale Memory Bank für regionale Bereitstellungen verwalten möchten, können Sie eine multiregionale Memory Bank (z. B. us) mit einer regionalen Laufzeit (z. B. us-central1) koppeln.
Wenn Sie eine multiregionale Memory Bank verwenden möchten, überschreiben Sie den Standard-ADK-Memory-Service-Builder, sodass er auf den multiregionalen Standort und die Instanz-ID verweist:
import agentplatform
from agentplatform.frameworks import AdkApp
from google.adk.memory import VertexAiMemoryBankService
# Create the Memory Bank instance in a multi-region location.
client_mb = agentplatform.Client(
project="PROJECT_ID",
location="us",
)
memory_bank = client_mb.memory_banks.create()
memory_bank_id = memory_bank.name.split("/")[-1]
# Point the memory service to the multi-regional instance.
def memory_bank_service_builder() -> VertexAiMemoryBankService:
return VertexAiMemoryBankService(
project="PROJECT_ID",
location="us",
agent_engine_id=memory_bank_id,
)
adk_app = AdkApp(
agent=agent,
memory_service_builder=memory_bank_service_builder,
)
# Deploy the runtime to a specific region.
client_runtime = agentplatform.Client(
project="PROJECT_ID",
location="us-central1",
)
runtime_instance = client_runtime.runtimes.create(
agent=adk_app,
config={
"staging_bucket": "STAGING_BUCKET",
"requirements": ["google-cloud-agentplatform[runtimes,adk]"],
},
)
Ersetzen Sie Folgendes:
- PROJECT_ID: Ihre Google Cloud -Projekt-ID, z. B.
my-project. - STAGING_BUCKET: Der Cloud Storage-Bucket-URI für das Staging Ihrer Agent Runtime, z. B.
gs://my-staging-bucket.
Wenn Sie diese Ressourcen löschen möchten, müssen Sie die Laufzeit und die multiregionale Instanz löschen.
Wenn Sie eine Instanz direkt nach einer Unterhaltung löschen, kann die Anfrage mit dem Fehler FAILED_PRECONDITION fehlschlagen, während die Speichergenerierung abgeschlossen wird. Warten Sie in diesem Fall eine Minute und führen Sie den Löschvorgang noch einmal aus.
client_runtime.runtimes.delete(
name=runtime_instance.api_resource.name,
force=True,
)
client_mb.memory_banks.delete(name=memory_bank.name, force=True)
Nächste Schritte
Schnellstart mit dem Agent Development Kit
ADK-Agenten erstellen, der sich Nutzerpräferenzen merkt
Erinnerungen erstellen
Informationen zum Generieren von gemerkten Informationen in der Memory Bank