L'Agent Development Kit (ADK) connette gli agenti ad Agent Platform Memory Bank tramite
VertexAiMemoryBankService,
un'implementazione dell'interfaccia
BaseMemoryService
dell'ADK. Questo documento spiega come scegliere uno strumento di callback e recupero della memoria e come connettere il servizio di memoria in ogni runtime ADK.
Per eseguire prima un esempio completo, consulta la guida rapida di Memory Bank con ADK.
Prima di iniziare
- Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.
-
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.-
Se utilizzi una shell locale, crea credenziali di autenticazione locali per il tuo account utente:
gcloud auth application-default login
Non è necessario farlo se utilizzi Cloud Shell.
Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver eseguito l'accesso a gcloud CLI con la tua identità federata.
- Installa l'ADK e l'SDK Agent Platform:
pip install --upgrade "google-adk[gcp]" "google-cloud-agentplatform>=2.0.1"
- Crea un'istanza di Memory Bank nella console Google Cloud o con l'SDK Agent Platform. Nella pagina Memory Bank, fai clic su Collega a un agente > Utilizza con ADK per il codice di configurazione precompilato. Salta questo passaggio se l'istanza viene creata da Agent Runtime.
Ruoli obbligatori
Per ottenere le autorizzazioni necessarie per creare un'istanza di Memory Bank e generare e recuperare memorie, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:
- Creare o aggiornare un'istanza di Memory Bank: Agent Platform User (`roles/aiplatform.user`)
- Leggere, scrivere o generare memorie: Utente Memory Bank (`roles/aiplatform.memoryUser`)
Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.
Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.
Come funzionano i componenti ADK con Memory Bank
Un agente ADK utilizza i seguenti componenti per leggere e scrivere memorie:
| Componente | Ruolo | Obbligatorio |
|---|---|---|
| Istanza di Memory Bank | Archivia e consolida i ricordi. | Sì |
VertexAiMemoryBankService |
Connette l'agente a Memory Bank come servizio di memoria ADK. | Sì |
| Servizio di sessione | Memorizza la cronologia delle conversazioni. Puoi utilizzare qualsiasi servizio di sessione ADK. | Sì |
| Strumento di recupero della memoria | Recupera i ricordi per l'agente. Vedi Recuperare i ricordi con uno strumento. | Per leggere le informazioni salvate |
| Callback di generazione dei ricordi | Invia gli eventi della conversazione a Memory Bank dopo la risposta dell'agente. Consulta Genera ricordi con un callback. | Per scrivere informazioni salvate |
ADK Runner o AdkApp |
Orchestra l'agente, i servizi, gli strumenti e i callback. | Sì |
Il seguente diagramma mostra come questi componenti interagiscono a ogni turno quando un agente utilizza PreloadMemoryTool e un callback di memoria:
Memory Bank limita ogni ricordo all'ID utente e al nome dell'app che esegue l'agente, ad esempio {"user_id": USER_ID, "app_name": APP_NAME}. Solo le richieste con lo stesso ID utente e lo stesso nome dell'app recuperano questi ricordi.
Genera ricordi con un callback
Un callback di generazione della memoria invia gli eventi di conversazione a Memory Bank. Memory Bank estrae i ricordi da questi eventi e li consolida con i ricordi esistenti. Scegli un metodo in base alla frequenza con cui elabori gli eventi:
| Metodo | Eventi inviati | Quando utilizzarlo |
|---|---|---|
callback_context.add_events_to_memory |
Un sottoinsieme di eventi selezionati da te | Consigliata. Elabora gli eventi in modo incrementale, ad esempio dopo ogni turno. |
callback_context.add_session_to_memory |
Tutti gli eventi della sessione | Chiamalo una volta alla fine di una sessione, in modo che gli stessi eventi non vengano elaborati più di una volta. |
L'esempio seguente invia gli eventi recenti dopo ogni risposta dell'agente:
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
Per inviare l'intera sessione, chiama
await callback_context.add_session_to_memory() in un callback alla fine della
sessione.
Per impostazione predefinita, VertexAiMemoryBankService invia gli eventi utilizzando l'importazione
degli eventi. Per attendere il completamento della generazione della memoria nei test o nelle demo, passa custom_metadata={"wait_for_completion": True} a add_events_to_memory.
Recuperare i ricordi con uno strumento
Uno strumento di recupero agentico controlla quando l'agente recupera i ricordi e come questi vengono inseriti nel prompt. Scegli uno dei seguenti strumenti:
| Strumento | Quando vengono recuperati i ricordi | Quando utilizzarlo |
|---|---|---|
PreloadMemoryTool |
All'inizio di ogni turno. I ricordi vengono inseriti nel contesto della richiesta del modello prima del turno dell'utente corrente. | Stabilisci un contesto di base sull'utente a ogni turno. |
LoadMemoryTool |
Quando il modello decide che i ricordi sono necessari per rispondere alla query. | Consenti al modello di decidere quando i ricordi sono pertinenti. |
Personalizzato FunctionTool |
Quando il modello chiama lo strumento, guidato dalla descrizione dello strumento. | Fornisci all'agente istruzioni su quando recuperare i ricordi. |
L'esempio seguente crea un agente che utilizza PreloadMemoryTool e il callback della sezione precedente:
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,
)
Per consentire al modello di decidere quando recuperare i ricordi, importa LoadMemoryTool da google.adk.tools.load_memory_tool e passa LoadMemoryTool() in tools.
Per scrivere uno strumento di recupero personalizzato, chiama tool_context.search_memory da una chiamata allo strumento di funzione:
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,
)
Connetti il servizio di memoria al runtime
Il modo in cui ti connetti a VertexAiMemoryBankService dipende da dove viene eseguito l'agente. Seleziona il runtime:
Runner locale
Quando esegui l'agente con adk.Runner, crea il servizio di memoria e passalo al 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())
Sostituisci quanto segue:
- PROJECT_ID: l'ID progetto Google Cloud , ad esempio
my-project. - LOCATION: la tua località, ad esempio
global. Consulta le località supportate e gli endpoint globali e multiregionali per Memory Bank. - MEMORY_BANK_ID: l'ID istanza di Memory Bank, ad esempio
456inprojects/my-project/locations/us-central1/reasoningEngines/456. - APP_NAME: il nome dell'app ADK, ad esempio
my_agent. La Memory Bank include il nome dell'app nell'ambito della memoria, in modo che le memorie siano isolate tra le app. - USER_ID: un identificatore per l'utente, ad esempio
user-123. I ricordi generati da questa sessione hanno come ambito questo identificatore.
Agent Runtime su Gemini Enterprise Agent Platform
Quando esegui il deployment di un agente ADK in Agent Runtime con il
modello ADK
(AdkApp), il modello utilizza VertexAiMemoryBankService per impostazione predefinita. Puoi creare l'istanza di Memory Bank ed eseguire il deployment dell'agente in un unico passaggio:
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())
Per eseguire il deployment dell'agente in una risorsa esistente e conservare le memorie esistenti della risorsa, chiama client.runtimes.update:
runtime_instance = client.runtimes.update(
name="RUNTIME_NAME",
agent=adk_app,
config={
"staging_bucket": "STAGING_BUCKET",
"requirements": ["google-cloud-agentplatform[runtimes,adk]"],
},
)
Quando esegui AdkApp localmente, utilizza InMemoryMemoryService per impostazione predefinita.
Per utilizzare Memory Bank localmente, esegui l'override del servizio di memoria:
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,
)
Sostituisci quanto segue:
- PROJECT_ID: l'ID progetto Google Cloud , ad esempio
my-project. - LOCATION: la regione o la multi-regione di Agent Runtime, ad esempio
us-central1. Solo le istanzeVertexAiMemoryBankServiceautonome supportanoglobal, nonclient.runtimes.create. Consulta le località supportate. - STAGING_BUCKET: l'URI del bucket Cloud Storage per lo staging del tuo Agent Runtime, ad esempio
gs://my-staging-bucket. - USER_ID: un identificatore per l'utente, ad esempio
user-123. - RUNTIME_NAME: il nome della risorsa dell'Agent Runtime esistente, nel formato
projects/.../locations/.../reasoningEngines/.... - MEMORY_BANK_ID: l'ID istanza di Memory Bank, ad esempio
456inprojects/my-project/locations/us-central1/reasoningEngines/456.
Cloud Run
Per eseguire il deployment dell'agente in Cloud Run, segui la documentazione di ADK e passa l'istanza di Memory Bank come servizio di memoria:
adk deploy cloud_run \
...
--memory_service_uri=agentengine://MEMORY_BANK_ID
Sostituisci MEMORY_BANK_ID con l'ID istanza di Memory Bank, ad esempio 456. Per testare l'agente di cui è stato eseguito il deployment, consulta la
documentazione relativa al deployment di ADK Cloud Run.
Google Kubernetes Engine (GKE)
Per eseguire il deployment dell'agente in GKE, segui la documentazione di ADK e passa l'istanza di Memory Bank come servizio di memoria:
adk deploy gke \
...
--memory_service_uri=agentengine://MEMORY_BANK_ID
Sostituisci MEMORY_BANK_ID con l'ID istanza di Memory Bank, ad esempio 456. Per testare l'agente di cui è stato eseguito il deployment, consulta la sezione Test dell'agente della documentazione relativa al deployment di ADK GKE.
ADK Web
ADK Web è un'interfaccia del browser locale per testare e ispezionare l'agente durante lo sviluppo.
ADK Web legge il progetto e la località dalle variabili di ambiente. Esegui questi comandi nel terminale, dalla directory che contiene la cartella dell'agente:
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_IDSostituisci quanto segue:
- PROJECT_ID: l'ID progetto Google Cloud , ad esempio
my-project. - LOCATION: la tua località, ad esempio
global. Consulta le località supportate e gli endpoint globali e multiregionali per Memory Bank. - MEMORY_BANK_ID: l'ID istanza di Memory Bank, ad esempio
456.
Quindi apri http://localhost:8000 nel browser. Per impostazione predefinita, ADK Web imposta lo User ID su user. Per utilizzare un ID utente diverso, aggiungi il parametro di query userId, ad esempio http://localhost:8000?userId=USER_ID.
Utilizza un Memory Bank multiregionale con un runtime regionale
Per impostazione predefinita, quando utilizzi il runtime con la banca della memoria integrata, l'agente e la banca della memoria vengono distribuiti nella stessa regione. Per mantenere un Memory Bank centrale tra i deployment regionali, puoi accoppiare un Memory Bank multiregionale (ad esempio us) con un runtime regionale (ad esempio us-central1).
Per utilizzare una Memory Bank multiregionale, esegui l'override del builder del servizio di memoria ADK predefinito in modo che punti alla località e all'ID istanza multiregionali:
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]"],
},
)
Sostituisci quanto segue:
- PROJECT_ID: l'ID progetto Google Cloud , ad esempio
my-project. - STAGING_BUCKET: l'URI del bucket Cloud Storage per lo staging del tuo Agent Runtime, ad esempio
gs://my-staging-bucket.
Per eliminare queste risorse, elimina il runtime e l'istanza multiregionale.
Se elimini un'istanza subito dopo una conversazione, la richiesta potrebbe non riuscire con un errore FAILED_PRECONDITION mentre la generazione della memoria viene completata. In questo caso, attendi un minuto ed esegui di nuovo l'eliminazione.
client_runtime.runtimes.delete(
name=runtime_instance.api_resource.name,
force=True,
)
client_mb.memory_banks.delete(name=memory_bank.name, force=True)
Passaggi successivi
Guida rapida con Agent Development Kit
Crea un agente ADK che ricorda le preferenze dell'utente.