Guida rapida di Agent Platform Memory Bank con Agent Development Kit

Agent Platform Memory Bank consente agli agenti di gestire i ricordi a lungo termine nelle varie 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 utilizzare Memory Bank e interagire con lui 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.

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

VertexAiMemoryBankService è un wrapper ADK intorno a Memory Bank definito da BaseMemoryService di ADK. Puoi definire callback e strumenti che interagiscono con il servizio di memoria per leggere e scrivere 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 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 richiesta RetrieveMemories a Memory Bank per recuperare i ricordi pertinenti per l'user_id e l'app_name correnti. Puoi orchestrare le chiamate a questo metodo utilizzando 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 introduttiva della pagina Configurare 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 con memoria, configura strumenti e 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 attiva il salvataggio di informazioni. 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 il tuo agente ADK, includi uno strumento di memoria che controlli 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 il contesto di base dell'utente. Se utilizzi LoadMemoryTool, il modello chiamerà questo strumento quando deciderà 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-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
)

In alternativa, puoi creare uno strumento personalizzato per recuperare i ricordi, il che è utile quando vuoi fornire istruzioni al tuo 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-2.5-flash",
    name='stateful_agent',
    instruction="""...""",
    tools=[FunctionTool(func=search_memories)],
    after_agent_callback=generate_memories_callback
)

Definisci un servizio di memoria e un runtime di Memory Bank ADK

Dopo aver creato l'agente con 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, che orchestra l'esecuzione di agenti, strumenti e callback.

Crea un'istanza di Agent Runtime

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

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]

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 runtime dell'agente agli script di runtime o di deployment in modo che l'agente utilizzi Memory Bank come servizio di memoria dell'ADK.

Corriere 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="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)

Sostituisci quanto segue:

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

Agent Runtime

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

Consulta Configurare Agent Runtime per maggiori dettagli sulla configurazione dell'istanza di Agent Runtime, incluso come personalizzare il comportamento di 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.
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. Consulta le regioni supportate per Memory Bank.
  • STAGING_BUCKET: il bucket Cloud Storage da utilizzare per lo 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="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)

Sostituisci quanto segue:

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

Cloud Run

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

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

GKE

Per eseguire il deployment dell'agente in Google Kubernetes Engine (GKE), consulta le istruzioni nella documentazione di ADK per scoprire come definire l'agente da eseguire il deployment in GKE.

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

ADK Web

L'interfaccia web dell'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://AGENT_ENGINE_ID

Sostituisci quanto segue:

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

Interagire 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 di ricordi durante l'inizializzazione dell'agente, la generazione di ricordi 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:

Corriere 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 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. 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 ADK Cloud Run.

GKE

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

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 neiparametri di ricercay, ad esempio http://localhost:8000?userId=YOUR_USER_ID.

Per ulteriori informazioni, consulta la pagina ADK Web nella documentazione di ADK.

Interazione di esempio

Prima sessione

Se hai utilizzato PreloadMemoryTool, l'agente tenterà di recuperare i ricordi 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 ricordi 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, ma non sono disponibili.

    • Modello: "Quale temperatura preferisci?"

    • (Callback): ADK attiva il salvataggio di informazioni. Non vengono estratti ricordi.

  2. Secondo turno:

    • Utente: mi trovo bene a 22 °C.

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

    • 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 rispetto ai ricordi esistenti, le nuove informazioni verranno consolidate con i ricordi esistenti.

  1. Primo turno

    • Utente: sistema la temperatura. È insopportabile!

    • (Chiamata allo strumento): l'ADK tenta di recuperare i ricordi. Viene recuperato il ricordo "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 la temperatura sia più alta al mattino.

    • (Chiamata allo strumento): l'ADK tenta di recuperare i ricordi. Viene recuperato il ricordo "Mi piace la temperatura di 22 gradi".

    • Modello: Ok, ho alzato la temperatura.

    • (Callback): l'ADK attiva il salvataggio di informazioni. Il ricordo esistente "Mi piace la temperatura di 21 gradi" viene aggiornato a "In genere mi piace la temperatura di 21 gradi, ma la preferisco più calda al mattino".

Utilizza una Memory Bank multiregionale con un runtime regionale

Per impostazione predefinita, l'agente e la Memory Bank vengono implementati nella stessa regione. Tuttavia, puoi separarli 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 diverse implementazioni regionali.

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

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]"]
    }
)

Sostituisci quanto segue:

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

Esegui la pulizia

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 nel seguente modo:

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

    agent_engine.delete(force=True)

  2. Elimina tutti i file creati localmente.

Passaggi successivi

Guida rapida

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