Início rápido com o Agent Development Kit

Depois de configurar o seu agente do Agent Development Kit (ADK) para usar o banco de memória, o agente orquestra chamadas para o banco de memória para gerir memórias a longo prazo por si.

Este tutorial demonstra como pode usar o banco de memória com o ADK para gerir memórias a longo prazo:

1. Crie o agente e o executor do ADK local.

2. Interagir com o seu agente para gerar dinamicamente memórias a longo prazo acessíveis em todas as sessões.

3. Limpar.

Para fazer chamadas diretamente para o Memory Bank sem a orquestração do ADK, consulte o Início rápido com o SDK do Agent Engine. A utilização do SDK do Agent Engine é útil para compreender como o banco de memória gera memórias ou para inspecionar o conteúdo do banco de memória.

Antes de começar

Para concluir os passos demonstrados neste tutorial, tem de seguir primeiro os passos em Configuração para o banco de memória.

Defina variáveis de ambiente

Para usar o ADK, defina as variáveis de ambiente:

import os

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

Substitua o seguinte:

• PROJECT_ID: o ID do seu projeto.
• LOCATION: a sua região. Consulte as regiões suportadas para o Banco de memórias.

Crie o seu agente do ADK

1. Ao desenvolver o seu agente ADK, inclua uma ferramenta Memory que controle quando o agente obtém memórias e como as memórias são incluídas no comando. O agente de exemplo usa o PreloadMemoryTool, que obtém sempre memórias no início de cada interação e inclui as memórias na instrução do 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. Crie um serviço de memória do VertexAiMemoryBankService, que o executor do ADK usa para obter memórias. Isto é opcional se estiver a usar o modelo do ADK do Agent Engine em vez de definir o seu próprio tempo de execução do 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 é um wrapper do ADK em torno do Memory Bank que é definido pelo BaseMemoryService do ADK e usa uma interface diferente da do SDK Agent Engine. Pode usar o SDK Agent Engine para fazer chamadas diretas à API Memory Bank. A interface VertexAiMemoryBankService inclui:

   • memory_service.add_session_to_memory que aciona um pedido GenerateMemories ao banco de memória com o adk.Session fornecido como conteúdo de origem. As chamadas para este método não são orquestradas pelo executor do ADK. Se quiser automatizar a geração de memórias com o ADK, tem de definir as suas próprias funções de callback.

   • memory_service.search_memory, o que aciona um pedido RetrieveMemories ao banco de memórias para obter memórias relevantes para o user_id e o app_name atuais. As chamadas para este método são orquestradas pelo executor do ADK quando fornece uma ferramenta de memória ao seu agente.

3. Crie um ADK Runtime, que coordena a execução dos seus agentes, ferramentas e callbacks. A configuração do ADK Runner depende do ambiente de implementação que está a usar:

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)

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)

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)

Interaja com o seu agente

Depois de definir o agente e configurar o banco de memória, pode interagir com o agente.

1. Crie a sua primeira sessão. Uma vez que não existem memórias disponíveis durante a primeira sessão com um utilizador, o agente não conhece as preferências do utilizador, como a temperatura preferida:

   adk.Runner

   Quando usa o adk.Runner, pode chamar diretamente os serviços de memória e sessão do 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.
   

   Substitua o seguinte:

   • APP_NAME: nome da app para o corredor.
   • USER_ID: um identificador para o utilizador. As memórias geradas a partir desta sessão são identificadas por este identificador opaco. O âmbito das memórias geradas é armazenado como {"user_id": "USER_ID"}.

   Modelo do ADK do Agent Engine

   Quando usa o modelo do ADK do Agent Engine, pode chamar o tempo de execução do Agent Engine para interagir com a memória e as sessões.

   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.
   

   Substitua o seguinte:

   • USER_ID: um identificador para o utilizador. As memórias geradas a partir desta sessão são identificadas por este identificador opaco. O âmbito das memórias geradas é armazenado como {"user_id": "USER_ID"}.

2. Gerar memórias para a sua sessão atual. Se o banco de memórias extrair memórias da conversa, estas são armazenadas no âmbito {"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)
   

   Modelo do ADK do Agent Engine

   await agent_engine.async_add_session_to_memory(session=session)
   

3. Crie a sua segunda sessão. Se usou a funcionalidade PreloadMemoryTool, o agente recupera memórias no início de cada interação para aceder às preferências que o utilizador comunicou anteriormente ao 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?
   

   Também pode usar memory_service.search_memory para aceder diretamente às memórias:

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

   Modelo do ADK do Agent Engine

   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?
   

   Também pode usar agent_engine.async_search_memory para aceder diretamente às memórias: Nota: para usar async_search_memory, o seu AdkApp tem de ter sido criado com a versão 1.110.0 ou mais recente do google-cloud-aiplatform. Caso contrário, pode aceder às memórias fazendo chamadas diretas para o banco de memórias.

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

Limpar

Para limpar todos os recursos usados neste projeto, pode eliminar o Google Cloud projeto que usou para o início rápido.

Caso contrário, pode eliminar os recursos individuais que criou neste tutorial, da seguinte forma:

1. Use o seguinte exemplo de código para eliminar a instância do Vertex AI Agent Engine, que também elimina todas as sessões ou memórias pertencentes a esse Vertex AI Agent Engine.

   agent_engine.delete(force=True)
   

2. Elimine todos os ficheiros criados localmente.

O que se segue?

• Início rápido com o SDK Agent Engine.