Guida rapida di Memory Bank con ADK

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

Questo documento spiega come creare un agente ADK, configurarlo per utilizzare Memory Bank e interagire con esso per generare e accedere alle memorie.

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

Importante: ADK utilizza principalmente funzioni asincrone. Se esegui il codice in un notebook come Colaboratory, puoi utilizzare direttamente await le funzioni asincrone perché è già in esecuzione un loop di eventi. Se esegui questo codice come script Python standard, devi racchiudere le chiamate di funzioni 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 "Get started with Memory Bank on ADK" in uno dei seguenti ambienti:

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

Gestire le memorie con il servizio di memoria ADK e Memory Bank

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

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 GenerateMemories richiesta 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 RetrieveMemories richiesta a Memory Bank per recuperare le memorie pertinenti per correnti user_id e app_name. 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 Guida introduttiva della pagina Configura Memory Bank.

Imposta le variabili di ambiente

Per utilizzare 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. Vedi le regioni supportate per Memory Bank.

Crea l'agente ADK

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

Definisci un callback di salvataggio di informazioni

Per orchestrare le chiamate per il salvataggio di informazioni, crea una funzione di callback che attivi il salvataggio di informazioni. Puoi inviare un sottoinsieme di eventi (con callback_context.add_events_to_memory) o tutti gli eventi in 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 le memorie e come le memorie vengono incluse nel prompt.

Se utilizzi PreloadMemoryTool, l'agente recupererà le memorie all'inizio di ogni turno e le includerà nell'istruzione di sistema, il che è utile per stabilire il contesto di base dell'utente. Se utilizzi LoadMemoryTool, il modello chiamerà questo strumento quando decide che le memorie sono necessarie 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 uno strumento personalizzato per recuperare le memorie, utile quando vuoi fornire istruzioni all'agente su quando recuperare le memorie:

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 Memory Bank

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

Per prima cosa devi creare un'istanza Memory Bank. Questo passaggio è facoltativo se utilizzi Agent Runtime per eseguire il deployment dell'agente. Per ulteriori informazioni sulla personalizzazione del comportamento di Memory Bank, consulta la sezione Configura l'istanza Memory Bank nella pagina Configura Memory Bank.

import vertexai

client = vertexai.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.agent_engines.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.api_resource.name)

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

Sostituisci quanto segue:

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

Crea un runtime ADK

Passa l'ID istanza 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 il runner.

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. Vedi le regioni supportate per Memory Bank.
• APP_NAME: il nome dell'app ADK. Il nome dell'app verrà incluso nel dizionario scope delle memorie generate in modo che le memorie siano isolate tra utenti e app.
• MEMORY_BANK_ID: l'ID istanza 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 di Memory Bank utilizza VertexAiMemoryBankService come servizio di memoria predefinito. Pertanto, puoi creare l'istanza Memory Bank ed eseguire il deployment in un runtime in un unico passaggio.

Per ulteriori dettagli sulla configurazione dell'istanza Memory Bank, incluso come personalizzare il comportamento di Memory Bank, consulta Configura Memory Bank.

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

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

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto.
• LOCATION: la tua regione. Vedi le regioni supportate per Memory Bank.
• STAGING_BUCKET: il bucket Cloud Storage da utilizzare per il staging di Agent Runtime.

Quando viene eseguito localmente, il modello ADK utilizza InMemoryMemoryService come servizio di memoria predefinito. Tuttavia, puoi sostituire il 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.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)

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto.
• LOCATION: la tua regione. Vedi le regioni supportate per Memory Bank.
• MEMORY_BANK_ID: l'ID istanza 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 "Get started with Sessions and Memory Bank for ADK agents 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 notebook "Get started with Sessions and Memory Bank for ADK agents in Google Kubernetes Engine" 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'uso nei deployment di produzione. Devi utilizzare ADK Web solo per scopi di sviluppo e debug.

L'interfaccia web ADK ti consente di testare gli 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. Vedi le regioni supportate per Memory Bank.
• MEMORY_BANK_ID: l'ID istanza 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 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 della memoria verrà attivata ogni volta che viene richiamato l'agente.

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. Le memorie generate da questa sessione sono identificate da questo identificatore opaco. L'ambito delle memorie generate viene memorizzato come {"user_id": "USER_ID"}.

Agent Runtime

Quando utilizzi il modello ADK, puoi chiamare 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. Le memorie generate da questa sessione sono identificate da questo identificatore opaco. L'ambito delle memorie generate viene memorizzato come {"user_id": "USER_ID"}.

Cloud Run

Consulta la sezione Testare il tuo agente della documentazione di deployment di ADK Cloud Run.

GKE

Consulta la sezione Testare l' 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 sostituire l'ID utente predefinito, includi userId nei parametri di ricerca, ad esempio http://localhost:8000?userId=YOUR_USER_ID.

Per ulteriori informazioni, 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 che l'utente ha comunicato in precedenza 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 correggere la temperatura?"

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

   • Modello: "Quale temperatura preferisci?"

   • (Callback): ADK attiva il salvataggio di informazioni. Non vengono estratte memorie.

2. Secondo turno:

   • Utente: Mi sento a mio agio a 22 gradi.

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

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

   • (Callback): ADK attiva il salvataggio di informazioni. Viene creata la memoria "Mi piace la temperatura di 22 gradi".

Seconda sessione

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

1. Primo turno

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

   • (Chiamata allo strumento): ADK tenta di recuperare le memorie. Viene recuperata la memoria "Mi piace la temperatura di 22 gradi".

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

   • (Callback): ADK attiva il salvataggio di informazioni. Non vengono estratte memorie perché l'utente non ha condiviso nulla di significativo da conservare.

2. Secondo turno

   • Utente: In realtà, preferisco che sia più caldo al mattino.

   • (Chiamata allo strumento): ADK tenta di recuperare le memorie. Viene recuperata la memoria "Mi piace la temperatura di 22 gradi".

   • Modello: Ok, ho aumentato la temperatura.

   • (Callback): ADK attiva il salvataggio di informazioni. La memoria esistente "Mi piace la temperatura di 22 gradi" viene aggiornata a "In genere mi piace che la temperatura sia di 22 gradi, ma mi piace che sia più calda al mattino".

Nota: le risposte dell'agente e di Memory Bank possono variare a seconda dei modelli utilizzati.

Utilizzare un Memory Bank multiregionale con un runtime regionale

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

Per utilizzare un Memory Bank multiregionale, devi sostituire il builder del servizio di memoria ADK predefinito in modo che punti alla località multiregionale e all'ID Memory Bank corrispondente.

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

# Create the Memory Bank instance in a multi-region location (for example, 'us')
client_mb = vertexai.Client(project="PROJECT_ID", location="us")
memory_bank = client_mb.agent_engines.create()
memory_bank_id = memory_bank.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=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 = 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]"]
    }
)

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto.
• STAGING_BUCKET: il bucket Cloud Storage da utilizzare per il staging di Agent Runtime.

Libera spazio

Per liberare spazio da tutte le risorse utilizzate in questo progetto, puoi eliminare il Google Cloud progetto 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 Agent Runtime, che elimina anche tutte le sessioni o le memorie appartenenti a quel runtime.

   agent_engine.delete(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 le memorie a lungo termine.