Guida rapida di Memory Bank con ADK

Agent Platform Memory Bank consente agli agenti di gestire i ricordi a lungo termine tra le sessioni. Se utilizzato con l'Agent Development Kit (ADK), l'agente può orchestrare automaticamente le chiamate a Memory Bank per archiviare e recuperare i ricordi in base alle interazioni degli utenti.

Questo documento spiega come creare un agente ADK, configurarlo per l'utilizzo di Memory Bank e interagire con l'agente per generare e accedere ai ricordi.

Per informazioni su come effettuare chiamate dirette all'API senza ADK, consulta la guida rapida all'API Memory Bank.

Importante: l'ADK utilizza principalmente funzioni asincrone. Se esegui il codice in un blocco note come Colaboratory, puoi await direttamente le funzioni asincrone perché un loop di eventi è già in esecuzione. Se esegui questo codice come script Python standard, devi aggregare le chiamate di funzione asincrone con asyncio.run() per creare e gestire un loop di eventi per eseguire le funzioni asincrone. In caso contrario, potresti ricevere un errore come 'await' outside function.

Per vedere un esempio di utilizzo di Memory Bank con ADK, esegui il notebook "Inizia a utilizzare Memory Bank su ADK" in uno dei seguenti ambienti:

Apri in Colab | Apri in Colab Enterprise | Apri in Agent Platform Workbench | Visualizza su GitHub

Gestisci i ricordi con il servizio di memoria ADK e Memory Bank

VertexAiMemoryBankService è un wrapper ADK attorno a Memory Bank definito da BaseMemoryService di ADK. Puoi definire callback e strumenti che interagiscono con il servizio di memoria per leggere e scrivere i ricordi.

L'interfaccia VertexAiMemoryBankService include:

• memory_service.add_session_to_memory attiva una richiesta GenerateMemories a Memory Bank utilizzando tutti gli eventi nel adk.Session fornito come contenuti di origine. Puoi orchestrare le chiamate a questo metodo utilizzando callback_context.add_session_to_memory nei callback.

  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 che attiva una richiesta GenerateMemories a Memory Bank utilizzando un sottoinsieme di eventi. Puoi orchestrare le chiamate a questo metodo utilizzando callback_context.add_events_to_memory nei callback.

  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 attiva una richiesta RetrieveMemories a Memory Bank per recuperare i ricordi pertinenti per user_id e app_name correnti. Puoi orchestrare le chiamate a questo metodo utilizzando gli strumenti di memoria integrati (LoadMemoryTool o PreloadMemoryTool) o uno strumento personalizzato che richiama tool_context.search_memory.

Prima di iniziare

Per completare i passaggi illustrati in questo tutorial, devi prima seguire i passaggi descritti nella sezione Introduzione della pagina Configura Memory Bank.

Imposta le variabili di ambiente

Per utilizzare l'ADK, imposta le variabili di ambiente:

import os

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

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto.
• LOCATION: la tua regione. Consulta le regioni supportate per Memory Bank.

Crea il tuo agente ADK

Per creare un agente abilitato alla memoria, configura strumenti e callback che orchestrano le chiamate al servizio di memoria.

Definisci un callback per la generazione della memoria

Per orchestrare le chiamate per la generazione della memoria, crea una funzione di callback che attiva la generazione della memoria. Puoi inviare un sottoinsieme di eventi (con callback_context.add_events_to_memory) o tutti gli eventi di una sessione (con callback_context.add_session_to_memory) da elaborare in background:

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

Definisci uno strumento di recupero della memoria

Quando sviluppi l'agente ADK, includi uno strumento di memoria che controlla quando l'agente recupera i ricordi e come vengono inclusi nel prompt.

Se utilizzi PreloadMemoryTool, l'agente recupererà i ricordi all'inizio di ogni turno e li includerà nell'istruzione di sistema, il che è utile per stabilire un contesto di base sull'utente. Se utilizzi LoadMemoryTool, il modello chiamerà questo strumento quando decide che i ricordi sono necessari per rispondere alla query dell'utente.

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-3.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
)

In alternativa, puoi creare il tuo strumento personalizzato per recuperare i ricordi, il che è utile quando vuoi fornire istruzioni all'agente su quando recuperare i ricordi:

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-3.5-flash",
    name='stateful_agent',
    instruction="""...""",
    tools=[FunctionTool(func=search_memories)],
    after_agent_callback=generate_memories_callback
)

Definisci un servizio di memoria ADK Memory Bank e un'istanza Memory Bank

Dopo aver creato l'agente abilitato alla memoria, devi collegarlo a un servizio di memoria. La procedura di configurazione del servizio di memoria ADK dipende da dove viene eseguito l'agente ADK. Il runtime orchestra l'esecuzione di agenti, strumenti e callback.

Crea un'istanza di Memory Bank

Nota: salta questa sezione se hai già un'istanza di Memory Bank.

Devi prima creare un'istanza di Memory Bank. Questo passaggio è facoltativo se utilizzi Agent Runtime per eseguire il deployment dell'agente. Per saperne di più sulla personalizzazione del comportamento della banca della memoria, consulta la sezione Configura l'istanza della banca della memoria nella pagina Configura la banca della memoria.

import agentplatform

client = agentplatform.Client(
  project="PROJECT_ID",
  location="LOCATION"
)
# If you don't have a Memory Bank instance already, create a
# Memory Bank instance using the default configuration.
memory_bank = client.memory_banks.create()

# Optionally, print out the resource name. You will need the
# resource name if you want to interact with your Memory Bank instance later on.
print(memory_bank.name)

memory_bank_id = memory_bank.name.split("/")[-1]

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto.
• LOCATION: la tua regione. Consulta le regioni supportate per Memory Bank.

Crea un runtime ADK

Passa l'ID istanza di Memory Bank agli script di runtime o di deployment in modo che l'agente utilizzi Memory Bank come servizio di memoria ADK.

Runner locale

adk.Runner viene generalmente utilizzato in un ambiente locale, come Colab. In questo caso, devi creare direttamente il servizio di memoria e l'esecutore.

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="MEMORY_BANK_ID",
)

# You can use any ADK session service. This example uses Sessions.
session_service = VertexAiSessionService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id="SESSIONS_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)

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto.
• LOCATION: la tua regione. Consulta le regioni supportate per Memory Bank.
• APP_NAME: il nome dell'app ADK. Il nome dell'app verrà incluso nel dizionario scope dei ricordi generati, in modo che i ricordi siano isolati sia tra gli utenti sia tra le app.
• MEMORY_BANK_ID: l'ID istanza di Memory Bank. Ad esempio, 456 in projects/my-project/locations/us-central1/reasoningEngines/456.
• SESSIONS_ID: l'ID istanza di Agent Platform Sessions. Ad esempio, 789 in projects/my-project/locations/us-central1/reasoningEngines/789.

Agent Runtime su Gemini Enterprise Agent Platform

Il modello ADK di Agent Runtime (AdkApp) può essere utilizzato sia localmente sia per eseguire il deployment di un agente ADK in Agent Runtime. Quando viene eseguito il deployment su Agent Platform, il modello ADK Memory Bank utilizza VertexAiMemoryBankService come servizio di memoria predefinito. In questo modo, puoi creare l'istanza di Memory Bank ed eseguire il deployment in un runtime in un unico passaggio.

Per ulteriori dettagli sulla configurazione dell'istanza di Memory Bank, consulta Configura Memory Bank, incluse le informazioni su come personalizzare il comportamento di Memory Bank.

Utilizza il seguente codice per eseguire il deployment dell'agente ADK con memoria abilitata in Agent Runtime:

import asyncio

import agentplatform
from agentplatform.frameworks import AdkApp

client = agentplatform.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 instance.
runtime_instance = client.runtimes.create(
      agent=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-agentplatform[runtimes,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.
runtime_instance = client.runtimes.update(
      name=agent_engine.api_resource.name,
      agent=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-agentplatform[runtimes,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)

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto.
• LOCATION: la tua regione. Consulta le regioni supportate per Memory Bank.
• STAGING_BUCKET: il tuo bucket Cloud Storage da utilizzare per la gestione temporanea del tuo Agent Runtime.

Se eseguito localmente, il template ADK utilizza InMemoryMemoryService come servizio di memoria predefinito. Tuttavia, puoi eseguire l'override del servizio di memoria predefinito per utilizzare VertexAiMemoryBankService:

def memory_bank_service_builder():
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="LOCATION",
        agent_engine_id="MEMORY_BANK_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.runtimes.create(...)` or `client.runtimes.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)

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto.
• LOCATION: la tua regione. Consulta le regioni supportate per Memory Bank.
• MEMORY_BANK_ID: l'ID istanza di Memory Bank da utilizzare per Memory Bank. Ad esempio, 456 in projects/my-project/locations/us-central1/reasoningEngines/456.

Cloud Run

Per vedere un esempio di utilizzo di Memory Bank con Cloud Run, esegui il notebook "Inizia a utilizzare le sessioni e Memory Bank per gli agenti ADK in Cloud Run" in uno dei seguenti ambienti:

Apri in Colab | Apri in Colab Enterprise | Apri in Agent Platform Workbench | Visualizza su GitHub

Per eseguire il deployment dell'agente in Cloud Run, consulta le istruzioni nella documentazione di ADK per scoprire come definire l'agente per il deployment in Cloud Run.

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

Google Kubernetes Engine (GKE)

Per vedere un esempio di utilizzo di Memory Bank con Google Kubernetes Engine, esegui il blocco note "Inizia a utilizzare sessioni e Memory Bank per gli agenti ADK in GKE" in uno dei seguenti ambienti:

Apri in Colab | Apri in Colab Enterprise | Apri in Agent Platform Workbench | Visualizza su GitHub

Per eseguire il deployment dell'agente in GKE, consulta le istruzioni nella documentazione di ADK per scoprire come definire l'agente per il deployment in GKE.

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

ADK Web

Importante: ADK Web non è destinato all'utilizzo in deployment di produzione. Devi utilizzare ADK Web solo per scopi di sviluppo e debug.

L'interfaccia web ADK ti consente di testare i tuoi agenti direttamente nel browser.

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

adk web --memory_service_uri=agentengine://MEMORY_BANK_ID

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto.
• LOCATION: la tua regione. Consulta le regioni supportate per Memory Bank.
• MEMORY_BANK_ID: l'ID istanza di Memory Bank. Ad esempio, 456 in projects/my-project/locations/us-central1/reasoningEngines/456.

Interagisci con l'agente

Dopo aver definito l'agente e configurato la memory bank, puoi interagire con l'agente. Se hai fornito un callback per attivare la generazione della memoria durante l'inizializzazione dell'agente, la generazione delle memorie verrà attivata ogni volta che l'agente viene richiamato.

Le memorie verranno archiviate utilizzando l'ambito {"user_id": USER_ID, "app_name": APP_NAME} corrispondente all'ID utente e al nome dell'app utilizzati per eseguire l'agente.

Il metodo di interazione con l'agente dipende dal suo ambiente di esecuzione:

Runner locale

# 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"
)

Sostituisci quanto segue:

• APP_NAME: il nome dell'app per il runner.
• USER_ID: un identificatore per l'utente. I ricordi generati da questa sessione sono identificati da questo identificatore opaco. L'ambito dei ricordi generati viene memorizzato come {"user_id": "USER_ID"}.

Agent Runtime

Quando utilizzi il template ADK, puoi chiamare il tuo Agent Runtime per interagire con la memoria e le sessioni.

# 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"
)

Sostituisci quanto segue:

• USER_ID: un identificatore per l'utente. I ricordi generati da questa sessione sono identificati da questo identificatore opaco. L'ambito dei ricordi generati viene memorizzato come {"user_id": "USER_ID"}.

Cloud Run

Consulta la sezione Test dell'agente della documentazione sul deployment di Cloud Run di ADK.

GKE

Consulta la sezione Test dell'agente della documentazione di deployment di ADK GKE.

ADK Web

Per utilizzare ADK Web, vai al server locale all'indirizzo http://localhost:8000.

Per impostazione predefinita, ADK Web imposta l'ID utente su user. Per eseguire l'override dell'ID utente predefinito, includi userId nei parametri di ricerca, ad esempio http://localhost:8000?userId=YOUR_USER_ID.

Per saperne di più, consulta la pagina ADK Web nella documentazione di ADK.

Esempio di interazione

Prima sessione

Se hai utilizzato PreloadMemoryTool, l'agente tenterà di recuperare le memorie all'inizio di ogni turno per accedere alle preferenze comunicate in precedenza dall'utente all'agente. Durante la prima interazione dell'agente con l'utente, non sono disponibili memorie da recuperare. Pertanto, l'agente non conosce le preferenze dell'utente, ad esempio la temperatura preferita, come mostrato nell'esempio seguente:

1. Primo turno:

   • Utente: "Puoi regolare la temperatura?"

   • (Chiamata allo strumento): ADK tenta di recuperare i ricordi; non sono disponibili ricordi.

   • Modello: "Quale temperatura preferisci?"

   • (Callback): l'ADK attiva la generazione della memoria. Non vengono estratte memorie.

2. Secondo turno:

   • Utente: mi trovo bene con 21 gradi.

   • (Chiamata allo strumento): ADK tenta di recuperare i ricordi; non sono disponibili ricordi.

   • Modello: Ok, ho aggiornato la temperatura a 21 gradi.

   • (Callback): l'ADK attiva la generazione della memoria. Viene creata l'informazione salvata "Mi piace la temperatura di 21 gradi".

Seconda sessione

La memoria estratta sarà disponibile per la sessione successiva per lo stesso nome dell'app e lo stesso ID utente. Se l'utente fornisce informazioni simili o contraddittorie rispetto ai ricordi esistenti, le nuove informazioni verranno consolidate con i ricordi esistenti.

1. Primo turno

   • Utente: regola la temperatura. È così scomodo!

   • (Chiamata allo strumento): ADK tenta di recuperare i ricordi. Viene recuperata l'informazione salvata "Mi piace la temperatura di 21 gradi".

   • Modello: Ok, ho aggiornato la temperatura a 21 gradi.

   • (Callback): l'ADK attiva la generazione della memoria. Non vengono estratti ricordi perché l'utente non ha condiviso nulla di significativo da conservare.

2. Secondo turno

   • Utente: In realtà, preferisco che la mattina faccia più caldo.

   • (Chiamata allo strumento): ADK tenta di recuperare i ricordi. Viene recuperata l'informazione salvata "Mi piace la temperatura di 21 gradi".

   • Modello: Ok, ho alzato la temperatura.

   • (Callback): l'ADK attiva la generazione della memoria. La memoria esistente "Mi piace la temperatura di 21 gradi" viene aggiornata in "In genere mi piace la temperatura di 21 gradi, ma preferisco che sia più calda al mattino".

Nota: potrebbero esserci alcune variazioni nelle risposte dell'agente e della banca della memoria a seconda dei modelli utilizzati.

Utilizza un Memory Bank multiregionale con un runtime regionale

Quando utilizzi Runtime con Memory Bank integrato, l'agente e Memory Bank vengono distribuiti nella stessa regione per impostazione predefinita. Tuttavia, puoi disaccoppiarli per utilizzare una Memory Bank multiregionale (ad esempio, us) con un runtime regionale (ad esempio, us-central1). Questa configurazione ti consente di mantenere una Memory Bank centrale in diversi deployment regionali.

Per utilizzare una Memory Bank multiregionale, devi eseguire l'override del builder del servizio di memoria ADK predefinito in modo che punti alla località multiregionale e all'ID della Memory Bank corrispondente.

import agentplatform
from google.adk.memory import VertexAiMemoryBankService
from agentplatform.frameworks import AdkApp

# Create the Memory Bank instance in a multi-region location (for example, 'us')
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 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=memory_bank_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 = 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: il tuo ID progetto.
• STAGING_BUCKET: il bucket Cloud Storage da utilizzare per la gestione temporanea del runtime dell'agente.

Esegui la pulizia

Per eliminare tutte le risorse utilizzate in questo progetto, puoi eliminare il progetto Google Cloud utilizzato per la guida rapida.

In alternativa, puoi eliminare le singole risorse che hai creato in questo tutorial, come segue:

1. Utilizza il seguente esempio di codice per eliminare l'istanza di Agent Runtime, che elimina anche tutte le sessioni o le memorie appartenenti a quel runtime.

   client_runtime.runtimes.delete(name=runtime_instance.api_resource.name, force=True)
   client_mb.memory_banks.delete(name=memory_bank.name, force=True)
   

2. Elimina tutti i file creati localmente.

Passaggi successivi

Guida rapida

Guida rapida all'API Memory Bank

Inizia a utilizzare l'API Memory Bank per gestire i ricordi a lungo termine.