Guida rapida all'utilizzo dell'Agent Development Kit

Questo tutorial mostra come utilizzare Memory Bank con l'ADK per gestire i ricordi a lungo termine. Dopo aver configurato l'agente Agent Development Kit (ADK) per utilizzare Memory Bank, l'agente coordina le chiamate a Memory Bank per gestire le memorie a lungo termine per te.

L'utilizzo di Memory Bank con l'ADK prevede i seguenti passaggi:

Crea l'agente e il runner ADK. I runner ADK connettono l'agente ai servizi che forniscono la gestione di sessioni e memoria.
Interagisci con il tuo agente per generare dinamicamente ricordi a lungo termine accessibili in tutte le sessioni.
Pulisci.

Per effettuare chiamate direttamente a Memory Bank senza l'orchestrazione di ADK, consulta la guida rapida all'SDK Agent Engine. L'utilizzo dell'SDK Agent Engine è utile per capire come Memory Bank genera i ricordi o per esaminarne i contenuti.

Gestire i ricordi con il servizio di memoria dell'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 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 l'user_id e l'app_name attuali. 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 Come iniziare 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_VERTEXAI"] = "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 di generazione della memoria

Per orchestrare le chiamate per la generazione di ricordi, crea una funzione di callback che attivi la generazione di ricordi. 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 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 un contesto di base sull'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, 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 ADK Memory Bank

Dopo aver creato l'agente con memoria, devi collegarlo a un servizio di memoria. La procedura di configurazione del servizio di memoria dell'ADK dipende da dove viene eseguito l'agente ADK, che coordina l'esecuzione di agenti, strumenti e callback.

Crea un'istanza di Agent Engine

Per utilizzare Memory Bank, devi prima creare un'istanza di Agent Engine. Questo passaggio è facoltativo se utilizzi Agent Engine Runtime per il deployment dell'agente. Per ulteriori informazioni sulla personalizzazione del comportamento di Memory Bank, consulta la sezione Configurare l'istanza di Agent Engine 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 Engine instance already, create an Agent Engine
# Memory Bank instance using the default configuration.
agent_engine = client.agent_engines.create()

# Optionally, print out the Agent Engine resource name. You will need the
# resource name if you want to interact with your Agent Engine 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 Agent Engine 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="AGENT_ENGINE_ID",
)

# You can use any ADK session service. This example uses Agent Engine 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: il 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 di Agent Engine da utilizzare per Memory Bank e Sessions. Ad esempio, 456 in projects/my-project/locations/us-central1/reasoningEngines/456.

Motore agente

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

Per ulteriori dettagli sulla configurazione di Agent Engine Runtime, incluso come personalizzare il comportamento di Memory Bank, consulta Configurare Agent Engine.

Utilizza il seguente codice per eseguire il deployment dell'agente ADK abilitato alla memoria in Agent Engine 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 Agent Engine with your agent deployed to Agent Engine Runtime.
# The Agent Engine 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 Agent Engine to deploy your agent to Agent Engine Runtime.
# Your agent will have access to the Agent Engine 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 Engine 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 Engine Runtime,
  # use `client.agent_engines.create(...)` or `client.agent_engines.update(...)`
  # and call the returned Agent Engine 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 di Agent Engine 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 dell'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 su Google Kubernetes Engine (GKE), consulta le istruzioni nella documentazione dell'ADK per scoprire come definire l'agente da distribuire su GKE.

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

ADK Web

L'interfaccia web di 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 di Agent Engine 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 la banca della memoria, puoi interagire con lui. 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 viene richiamato l'agente.

I ricordi verranno archiviati 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"}.

Motore agente

Quando utilizzi il modello ADK di Agent Engine, puoi chiamare il runtime di Agent Engine 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 Testare l'agente della documentazione sul deployment di ADK Cloud Run.

GKE

Consulta la sezione Testare l'agente della documentazione di deployment 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 ignorare l'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.

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:

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 la generazione della memoria. Non vengono estratti ricordi.
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 la generazione della memoria. 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.

Primo turno
- Utente: correggi la temperatura. È così scomodo!
- (Chiamata allo strumento): ADK tenta di recuperare i ricordi. Viene recuperato il promemoria "Mi piace la temperatura di 22 gradi".
- Modello: ok, ho aggiornato la temperatura a 22 gradi.
- (Callback): ADK attiva la generazione della memoria. Non vengono estratte memorie perché l'utente non ha condiviso nulla di significativo da conservare.
Secondo turno
- Utente: In realtà, preferisco che la temperatura sia più alta al mattino.
- (Chiamata allo strumento): ADK tenta di recuperare i ricordi. Viene recuperato il promemoria "Mi piace la temperatura di 22 gradi".
- Modello: Ok, ho alzato la temperatura.
- (Callback): ADK attiva la generazione della memoria. La memoria esistente "Mi piace la temperatura a 22 gradi" viene aggiornata a "In genere mi piace la temperatura a 22 gradi, ma la preferisco più calda al mattino".

Esegui la pulizia

Per eliminare 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:

Utilizza il seguente esempio di codice per eliminare l'istanza di Vertex AI Agent Engine, che elimina anche eventuali sessioni o ricordi appartenenti a Vertex AI Agent Engine.
```
agent_engine.delete(force=True)
```
Elimina tutti i file creati localmente.

Passaggi successivi

Guida rapida con l'SDK Agent Engine.

Guida rapida all'utilizzo dell'Agent Development Kit Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

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

Prima di iniziare

Imposta le variabili di ambiente

Crea il tuo agente ADK

Definisci un callback di generazione della memoria

Definisci uno strumento di recupero della memoria

Definisci un servizio di memoria e un runtime ADK Memory Bank

Crea un'istanza di Agent Engine

Crea un runtime ADK

Runner locale

Motore agente

Cloud Run

GKE

ADK Web

Interagire con l'agente

Runner locale

Motore agente

Cloud Run

GKE

ADK Web

Interazione di esempio

Esegui la pulizia

Passaggi successivi

Guida rapida all'utilizzo dell'Agent Development Kit