O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Guia de início rápido do Memory Bank com o ADK

O Memory Bank da Plataforma de Agentes permite que os agentes gerenciem memórias de longo prazo em várias sessões. Quando usado com o Kit de Desenvolvimento de Agente (ADK, na sigla em inglês), o agente pode orquestrar automaticamente chamadas para o Memory Bank para armazenar e recuperar memórias com base nas interações do usuário.

Este documento explica como criar um agente do ADK, configurá-lo para usar o Memory Bank e interagir com ele para gerar e acessar memórias.

Para informações sobre como fazer chamadas diretas para a API sem o ADK, consulte o início rápido da API Memory Bank.

Gerenciar memórias com o serviço de memória do ADK e o Memory Bank

VertexAiMemoryBankService é um wrapper do ADK em torno do Memory Bank definido pelo BaseMemoryService do ADK. É possível definir callbacks e ferramentas que interagem com o serviço de memória para ler e gravar memórias.

A interface VertexAiMemoryBankService inclui:

memory_service.add_session_to_memory aciona uma solicitação GenerateMemories para o Memory Bank usando todos os eventos no adk.Session fornecido como o conteúdo de origem. É possível orquestrar chamadas para esse método usando callback_context.add_session_to_memory nos callbacks.
```
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, que aciona uma GenerateMemories solicitação para o Memory Bank usando um subconjunto de eventos. É possível orquestrar chamadas para esse método usando callback_context.add_events_to_memory nos callbacks.

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 aciona uma RetrieveMemories solicitação para o Memory Bank para buscar memórias relevantes para o atual user_id e app_name. É possível orquestrar chamadas para esse método usando ferramentas de memória integradas (LoadMemoryTool ou PreloadMemoryTool) ou uma ferramenta personalizada que invoca tool_context.search_memory.

Antes de começar

Para concluir as etapas demonstradas neste tutorial, siga as etapas na seção de introdução da página Configurar o Memory Bank.

Defina as variáveis de ambiente

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

import os

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

Substitua:

PROJECT_ID: o ID do projeto.
LOCATION: sua região. Consulte as regiões com suporte para o Memory Bank.

Criar o agente do ADK

Para criar um agente com memória ativada, configure ferramentas e callbacks que orquestram chamadas para o serviço de memória.

Definir um callback de geração de memória

Para orquestrar chamadas para geração de memória, crie uma função de callback que acione a geração de memória. É possível enviar um subconjunto de eventos (com callback_context.add_events_to_memory) ou todos os eventos em uma sessão (com callback_context.add_session_to_memory) para serem processados em segundo plano:

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

Definir uma ferramenta de recuperação de memória

Ao desenvolver o agente do ADK, inclua uma ferramenta de memória que controle quando o agente recupera memórias e como elas são incluídas no comando.

Se você usar PreloadMemoryTool, o agente vai recuperar memórias no início de cada rodada e incluir as memórias recuperadas na instrução do sistema, o que é bom para estabelecer o contexto de linha de base sobre o usuário. Se você usar LoadMemoryTool, o modelo vai chamar essa ferramenta quando decidir que as memórias são necessárias para responder à consulta do usuário.

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
)

Como alternativa, é possível criar sua própria ferramenta personalizada para recuperar memórias, o que é útil quando você quer fornecer instruções ao agente sobre quando recuperar memórias:

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
)

Definir um serviço de memória do Memory Bank do ADK e uma instância do Memory Bank

Depois de criar o agente com memória ativada, é necessário vinculá-lo a um serviço de memória. O processo de configuração do serviço de memória do ADK depende de onde o agente do ADK é executado. O ambiente de execução orquestra a execução de agentes, ferramentas e callbacks.

Criar uma instância do Memory Bank

Primeiro, crie uma instância do Memory Bank. Essa etapa é opcional se você estiver usando o Agent Runtime para implantar o agente. Para mais informações sobre como personalizar o comportamento do Memory Bank, consulte a seção Configurar a instância do Memory Bank na página Configurar o 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]

Substitua:

PROJECT_ID: o ID do projeto.
LOCATION: sua região. Consulte as regiões com suporte para o Memory Bank.

Criar um ambiente de execução do ADK

Transmita o ID da instância do Memory Bank para os scripts de ambiente de execução ou implantação para que o agente use o Memory Bank como o serviço de memória do ADK.

Executor local

adk.Runner geralmente é usado em um ambiente local, como o Colab. Nesse caso, é necessário criar diretamente o serviço de memória e o executor.

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)

Substitua:

PROJECT_ID: o ID do projeto.
LOCATION: sua região. Consulte as regiões com suporte para o Memory Bank.
APP_NAME: nome do app do ADK. O nome do app será incluído no dicionário scope das memórias geradas para que as memórias sejam isoladas entre usuários e apps.
MEMORY_BANK_ID: o ID da instância do Memory Bank. Por exemplo, 456 em projects/my-project/locations/us-central1/reasoningEngines/456.
SESSIONS_ID: o ID da instância das sessões da Plataforma de Agentes. Por exemplo, 789 em projects/my-project/locations/us-central1/reasoningEngines/789.

Agent Runtime na Gemini Enterprise Agent Platform

O ADK do Agent Runtime modelo (AdkApp) pode ser usado localmente e para implantar um agente do ADK no Agent Runtime. Quando implantado na Plataforma de Agentes, o modelo do ADK do Memory Bank usa VertexAiMemoryBankService como o serviço de memória padrão. Assim, é possível criar a instância do Memory Bank e implantar em um ambiente de execução em uma única etapa.

Consulte Configurar o Memory Bank para mais detalhes sobre como configurar a instância do Memory Bank, incluindo como personalizar o comportamento do Memory Bank.

Use o código a seguir para implantar o agente do ADK com memória ativada no 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)

Substitua:

PROJECT_ID: o ID do projeto.
LOCATION: sua região. Consulte as regiões com suporte para o Memory Bank.
STAGING_BUCKET: o bucket do Cloud Storage a ser usado para preparar o Agent Runtime.

Quando executado localmente, o modelo do ADK usa InMemoryMemoryService como o serviço de memória padrão. No entanto, é possível substituir o serviço de memória padrão para usar 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)

Substitua:

PROJECT_ID: o ID do projeto.
LOCATION: sua região. Consulte as regiões com suporte para o Memory Bank.
MEMORY_BANK_ID: o ID da instância do Memory Bank a ser usado para o Memory Bank. Por exemplo, 456 em projects/my-project/locations/us-central1/reasoningEngines/456.

Cloud Run

Para implantar o agente no Cloud Run, consulte as instruções na documentação do ADK para saber como definir o agente a ser implantado no Cloud Run.

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

Google Kubernetes Engine (GKE)

Para implantar o agente no GKE, consulte as instruções na documentação do ADK para saber como definir o agente a ser implantado no GKE.

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

Web do ADK

A interface da web do ADK permite testar os agentes diretamente no navegador.

export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="LOCATION"

adk web --memory_service_uri=agentengine://MEMORY_BANK_ID

Substitua:

PROJECT_ID: o ID do projeto.
LOCATION: sua região. Consulte as regiões com suporte para o Memory Bank.
MEMORY_BANK_ID: o ID da instância do Memory Bank. Por exemplo, 456 em projects/my-project/locations/us-central1/reasoningEngines/456.

Interaja com seu agente

Depois de definir o agente e configurar o Memory Bank, é possível interagir com o agente. Se você forneceu um callback para acionar a geração de memória quando inicializar o agente, a geração de memórias será acionada sempre que o agente for invocado.

As memórias serão armazenadas usando o escopo {"user_id": USER_ID, "app_name": APP_NAME} correspondente ao ID do usuário e ao nome do app usados para executar o agente.

O método de interação com o agente depende do ambiente de execução:

Executor local

# 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"
)

Substitua:

APP_NAME: nome do app para o executor.
USER_ID: um identificador para o usuário. As memórias geradas nessa sessão são identificadas por esse identificador opaco. O escopo das memórias geradas é armazenado como {"user_id": "USER_ID"}.

Agent Runtime

Ao usar o modelo do ADK, é possível chamar o Agent Runtime para interagir com a memória e as sessões.

# 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"
)

Substitua:

USER_ID: um identificador para o usuário. As memórias geradas nessa sessão são identificadas por esse identificador opaco. O escopo das memórias geradas' é armazenado como {"user_id": "USER_ID"}.

Cloud Run

Consulte a seção Testar o agente da documentação de implantação do ADK Cloud Run.

GKE

Consulte a seção Testar o agente da documentação de implantação do ADK GKE.

Web do ADK

Para usar a web do ADK, acesse o servidor local em http://localhost:8000.

Por padrão, a web do ADK define o ID do usuário como user. Para substituir o ID do usuário padrão, inclua userId nos parâmetros de consulta, como http://localhost:8000?userId=YOUR_USER_ID.

Para mais informações, consulte a página da web do ADK na documentação do ADK .

Exemplo de interação

Primeira sessão

Se você usou a PreloadMemoryTool, o agente vai tentar recuperar memórias no início de cada rodada para acessar as preferências que o usuário comunicou anteriormente ao agente. Durante a primeira interação do agente com o usuário, não há memórias disponíveis para serem recuperadas. Portanto, o agente não conhece as preferências do usuário, como a temperatura preferida, conforme mostrado no exemplo a seguir:

Primeira rodada:
- Usuário: "Você pode ajustar a temperatura?"
- (Chamada de ferramenta): O ADK tenta buscar memórias. Nenhuma memória está disponível.
- Modelo: "Qual temperatura você prefere?"
- (Callback): O ADK aciona a geração de memória. Nenhuma memória é extraída.
Segunda rodada:
- Usuário: "Me sinto confortável a 22 graus.
- (Chamada de ferramenta): O ADK tenta buscar memórias. Nenhuma memória está disponível.
- Modelo: Ok, atualizei a temperatura para 22 graus.
- (Callback): O ADK aciona a geração de memória. A memória "Gosto da temperatura de 22 graus" é criada.

Segunda sessão

A memória extraída estará disponível para a próxima sessão com o mesmo nome de app e ID do usuário. Se o usuário fornecer informações semelhantes ou contraditórias às memórias atuais, as novas informações serão consolidadas com as memórias atuais.

Primeira rodada
- Usuário: Ajuste a temperatura. Está muito desconfortável!
- (Chamada de ferramenta): O ADK tenta buscar memórias. A memória "Gosto da temperatura de 22 graus" é recuperada.
- Modelo: Ok, atualizei a temperatura para 22 graus.
- (Callback): O ADK aciona a geração de memória. Nenhuma memória é extraída, porque o usuário não compartilhou nada significativo para persistir.
Segunda rodada
- Usuário: "Na verdade, prefiro que esteja mais quente pela manhã.
- (Chamada de ferramenta): O ADK tenta buscar memórias. A memória "Gosto da temperatura de 22 graus" é recuperada.
- Modelo: "Ok, aumentei a temperatura.
- (Callback): O ADK aciona a geração de memória. A memória atual "Gosto da temperatura de 22 graus" é atualizada para "Geralmente gosto da temperatura de 22 graus, mas prefiro que esteja mais quente pela manhã".

Usar um Memory Bank multirregional com um ambiente de execução regional

Ao usar o ambiente de execução com o Memory Bank integrado, o agente e o Memory Bank são implantados na mesma região por padrão. No entanto, é possível desvinculá-los para usar um Memory Bank multirregional (por exemplo, us) com um ambiente de execução regional (por exemplo, us-central1). Essa configuração permite manter um Memory Bank central em diferentes implantações regionais.

Para usar um Memory Bank multirregional, é necessário substituir o builder de serviço de memória do ADK padrão para apontar para o local multirregional e o ID do Memory Bank correspondente.

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

Substitua:

PROJECT_ID: o ID do projeto.
STAGING_BUCKET: o bucket do Cloud Storage a ser usado para preparar o Agent Runtime.

Limpar

Para limpar todos os recursos usados neste projeto, você pode excluir o Google Cloud projeto usado para o início rápido.

Caso contrário, exclua os recursos individuais criados neste tutorial, da seguinte maneira:

Use o exemplo de código a seguir para excluir a instância do Agent Runtime, que também exclui todas as sessões ou memórias pertencentes a esse ambiente de execução.
```
agent_engine.delete(force=True)
```
Exclua todos os arquivos criados localmente.

A seguir

Início rápido

Início rápido da API Memory Bank

Comece a usar a API Memory Bank para gerenciar memórias de longo prazo.

Guia de início rápido do Memory Bank com o ADK Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Gerenciar memórias com o serviço de memória do ADK e o Memory Bank

Antes de começar

Defina as variáveis de ambiente

Criar o agente do ADK

Definir um callback de geração de memória

Definir uma ferramenta de recuperação de memória

Definir um serviço de memória do Memory Bank do ADK e uma instância do Memory Bank

Criar uma instância do Memory Bank

Criar um ambiente de execução do ADK

Executor local

Agent Runtime na Gemini Enterprise Agent Platform

Cloud Run

Google Kubernetes Engine (GKE)

Web do ADK

Interaja com seu agente

Executor local

Agent Runtime

Cloud Run

GKE

Web do ADK

Exemplo de interação

Usar um Memory Bank multirregional com um ambiente de execução regional

Limpar

A seguir

Início rápido da API Memory Bank

Guia de início rápido do Memory Bank com o ADK