Guida rapida all'utilizzo dell'Agent Development Kit

Anteprima

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

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.

Questo tutorial mostra come utilizzare Memory Bank con l'ADK per gestire i ricordi a lungo termine:

1. Crea l'agente e il runner ADK locali.

2. Interagisci con il tuo agente per generare dinamicamente ricordi a lungo termine accessibili in tutte le sessioni.

3. Pulisci.

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

Prima di iniziare

Per completare i passaggi illustrati in questo tutorial, devi prima seguire i passaggi descritti in Configurazione di 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 l'agente ADK

1. Quando sviluppi il tuo agente ADK, includi uno strumento Memory che controlla quando l'agente recupera i ricordi e come vengono inclusi nel prompt. L'agente di esempio utilizza PreloadMemoryTool, che recupera sempre i ricordi all'inizio di ogni turno e li include nell'istruzione di sistema:

   from google import adk
   
   agent = adk.Agent(
       model="gemini-2.0-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=[adk.tools.preload_memory_tool.PreloadMemoryTool()]
   )
   

2. Crea un servizio di memoria VertexAiMemoryBankService, che il runner ADK utilizza per recuperare i ricordi. Questo passaggio è facoltativo se utilizzi il modello ADK di Agent Engine anziché definire il tuo runtime ADK.

   from google.adk.memory import VertexAiMemoryBankService
   
   agent_engine_id = agent_engine.api_resource.name.split("/")[-1]
   
   memory_service = VertexAiMemoryBankService(
       project="PROJECT_ID",
       location="LOCATION",
       agent_engine_id=agent_engine_id
   )
   

   VertexAiMemoryBankService è un wrapper ADK intorno a Memory Bank definito da BaseMemoryService di ADK e utilizza un'interfaccia diversa dall'SDK Agent Engine. Puoi utilizzare l'SDK Agent Engine per effettuare chiamate API dirette a Memory Bank. L'interfaccia VertexAiMemoryBankService include:

   • memory_service.add_session_to_memory che attiva una richiesta GenerateMemories a Memory Bank utilizzando adk.Session come contenuti di origine. Le chiamate a questo metodo non sono coordinate dal runner ADK. Se vuoi automatizzare la generazione di ricordi con l'ADK, devi definire le tue funzioni di callback.

   • memory_service.search_memory che attiva una richiesta RetrieveMemories a Memory Bank per recuperare i ricordi pertinenti per l'user_id e l'app_name attuali. Le chiamate a questo metodo vengono coordinate dal runner dell'ADK quando fornisci uno strumento di memoria al tuo agente.

3. Crea un runtime ADK, che coordina l'esecuzione di agenti, strumenti e callback. La configurazione di ADK Runner dipende dall'ambiente di deployment che utilizzi:

adk.Runner

adk.Runner viene generalmente utilizzato in un ambiente locale, come Colab. La maggior parte delle opzioni di deployment, come Agent Engine Runtime, offre il proprio runtime per ADK.

from google.adk.sessions import VertexAiSessionService
from google.genai import types

# You can use any ADK session service.
session_service = VertexAiSessionService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id=agent_engine_id
)

app_name="APP_NAME"

runner = adk.Runner(
    agent=agent,
    app_name=app_name,
    session_service=session_service,
    memory_service=memory_service
)

def call_agent(query, session, user_id):
  content = types.Content(role='user', parts=[types.Part(text=query)])
  events = runner.run(user_id=user_id, session_id=session, new_message=content)

  for event in events:
      if event.is_final_response():
          final_response = event.content.parts[0].text
          print("Agent Response: ", final_response)

Sostituisci quanto segue:

• APP_NAME: Il nome dell'app ADK.

Modello ADK del 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 caso non è necessario fornire esplicitamente un servizio di memoria.

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 in Agent Engine Runtime:

import vertexai
from vertexai.preview.reasoning_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.
• 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.
• STAGING_BUCKET: il bucket Cloud Storage da utilizzare per lo staging di Agent Engine Runtime.

Se 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.

Interagire con l'agente

Dopo aver definito l'agente e configurato la Banca della memoria, puoi interagire con lui.

1. Crea la tua prima sessione. Poiché non sono disponibili ricordi durante la prima sessione con un utente, l'agente non conosce le preferenze dell'utente, ad esempio la temperatura preferita:

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

   adk.Runner

   Quando utilizzi adk.Runner, puoi chiamare direttamente i servizi di memoria e sessione dell'ADK.

   session = await session_service.create_session(
       app_name="APP_NAME",
       user_id="USER_ID"
   )
   
   call_agent(
       "Can you update the temperature to my preferred temperature?",
       session.id,
       "USER_ID"
   )
   
   # Agent response: "What is your preferred temperature?"
   call_agent("I like it at 71 degrees", session.id, "USER_ID")
   # Agent Response:  Setting the temperature to 71 degrees Fahrenheit.
   # Temperature successfully changed.
   

   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"}.

   Modello ADK del motore agente

   Quando utilizzi il modello ADK di Agent Engine, puoi chiamare Agent Engine Runtime per interagire con la memoria e le sessioni.

   session = await agent_engine.async_create_session(user_id="USER_ID")
   
   await call_agent(
       "Can you update the temperature to my preferred temperature?",
       session.get("id"),
       "USER_ID"
   )
   
   # Agent response: "What is your preferred temperature?"
   await call_agent("I like it at 71 degrees", session.get("id"), "USER_ID")
   # Agent Response:  Setting the temperature to 71 degrees Fahrenheit.
   # Temperature successfully changed.
   

   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"}.

2. Genera ricordi per la sessione corrente. Se Memory Bank estrae ricordi dalla conversazione, questi vengono archiviati nell'ambito {"user_id": USER_ID, "app_name": APP_NAME}.

   adk.Runner

   session = await session_service.get_session(
       app_name=app_name,
       user_id="USER_ID",
       session_id=session.id
   )
   memory_service.add_session_to_memory(session)
   

   Modello ADK del motore agente

   Nota: per utilizzare async_add_session_to_memory, il tuo AdkApp deve essere stato creato con google-cloud-aiplatform versione 1.110.0 o successive. In caso contrario, puoi attivare la generazione di ricordi effettuando chiamate dirette a Memory Bank.

   await agent_engine.async_add_session_to_memory(session=session)
   

3. Crea la seconda sessione. Se hai utilizzato PreloadMemoryTool, l'agente recupera i ricordi all'inizio di ogni turno per accedere alle preferenze che l'utente ha comunicato in precedenza all'agente.

   adk.Runner

   session = await session_service.create_session(
       app_name=app_name,
       user_id="USER_ID"
   )
   
   call_agent("Fix the temperature!", session.id, "USER_ID")
   # Agent Response:  Setting temperature to 71 degrees.  Is that correct?
   

   Puoi anche utilizzare memory_service.search_memory per recuperare direttamente i ricordi:

   await memory_service.search_memory(
       app_name="APP_NAME",
       user_id="USER_ID",
       query="Fix the temperature!",
   )
   

   Modello ADK del motore agente

   session = await agent_engine.async_create_session(user_id="USER_ID")
   
   await call_agent("Fix the temperature!", session.get("id"), "USER_ID")
   # Agent Response:  Setting temperature to 71 degrees.  Is that correct?
   

   Puoi anche utilizzare agent_engine.async_search_memory per recuperare i ricordi direttamente: Nota: per utilizzare async_search_memory, il tuo AdkApp deve essere stato creato con google-cloud-aiplatform versione 1.110.0 o successive. In caso contrario, puoi recuperare i ricordi effettuando chiamate dirette a Memory Bank.

   await agent_engine.async_search_memory(
       user_id="USER_ID",
       query="Fix the temperature!",
   )
   

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:

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

2. Elimina tutti i file creati localmente.

Passaggi successivi

• Guida rapida con l'SDK Agent Engine.