Guia de início rápido do Kit de desenvolvimento de agentes

Neste tutorial, mostramos como usar o Memory Bank com o ADK para gerenciar memórias de longo prazo. Depois de configurar o agente do Agent Development Kit (ADK) para usar o Memory Bank, ele orquestra as chamadas para o Memory Bank e gerencia as memórias de longo prazo para você.

O uso do Memory Bank com o ADK envolve as seguintes etapas:

Crie seu agente e executor do ADK. Os executores do ADK conectam seu agente a serviços que oferecem gerenciamento de sessão e de memória.
Interaja com seu agente para gerar dinamicamente recordações de longo prazo acessíveis em todas as sessões.
Limpeza.

Para fazer chamadas diretamente para o Memory Bank sem a orquestração do ADK, consulte o Guia de início rápido com o SDK do Agent Engine. Usar o SDK do Agent Engine é útil para entender como o banco de memória gera recordações ou para inspecionar o conteúdo dele.

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:

O memory_service.add_session_to_memory aciona uma solicitação GenerateMemories ao Memory Bank usando todos os eventos no adk.Session fornecido como conteúdo de origem. Você pode orquestrar chamadas para esse método usando callback_context.add_session_to_memory nos seus 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 solicitação GenerateMemories ao Memory Bank usando um subconjunto de eventos. Você pode orquestrar chamadas para esse método usando callback_context.add_events_to_memory nos seus 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

O memory_service.search_memory aciona uma solicitação RetrieveMemories ao banco de memória para buscar recordações relevantes para o user_id e o app_name atuais. É 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 instruções na seção Como começar da página "Configurar o banco de memória".

Defina as 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:

PROJECT_ID: o ID do projeto.
LOCATION: sua região. Consulte as regiões compatíveis com o Memory Bank.

Criar seu agente do ADK

Para criar um agente com memória, 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. Você pode enviar um subconjunto de eventos (com callback_context.add_events_to_memory) ou todos os eventos de 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 seu 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 turno e incluí-las na instrução do sistema, o que é bom para estabelecer um contexto básico 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.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
  )

Como alternativa, crie sua própria ferramenta personalizada para recuperar recordações, o que é útil quando você quer dar instruções ao seu agente sobre quando fazer isso:

  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
  )

Definir um serviço de memória e um ambiente de execução do Memory Bank do ADK

Depois de criar o agente com capacidade de memória, vincule-o 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 que orquestra a execução dos seus agentes, ferramentas e callbacks.

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

Substitua:

PROJECT_ID: o ID do projeto.
LOCATION: sua região. Consulte as regiões compatíveis com o Memory Bank.

Em seguida, transmita o ID do Agent Engine para os scripts de implantação ou de tempo de execução para que o agente use o Memory Bank como o serviço de memória do ADK.

Corredor local

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

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)

Substitua:

PROJECT_ID: o ID do projeto.
LOCATION: sua região. Consulte as regiões compatíveis com o Memory Bank.
APP_NAME: nome do app do ADK. O nome do app será incluído no dicionário scope das recordações geradas para que elas sejam isoladas entre usuários e apps.

Mecanismo do agente

O modelo do ADK do Agent Engine (AdkApp) pode ser usado localmente e para implantar um agente do ADK no ambiente de execução do Agent Engine. Quando implantado no tempo de execução do Agent Engine, o modelo do ADK do Agent Engine usa VertexAiMemoryBankService como o serviço de memória padrão, usando a mesma instância do Agent Engine para o banco de memória e o tempo de execução do Agent Engine. Assim, você pode criar sua instância do Memory Bank e implantar em um ambiente de execução em uma única etapa.

Consulte Configurar o Agent Engine para mais detalhes sobre como configurar o ambiente de execução do Agent Engine, incluindo como personalizar o comportamento do seu banco de memória.

Use o código a seguir para implantar seu agente do ADK com memória ativada no ambiente de execução do Agent Engine:

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)

Substitua:

PROJECT_ID: o ID do projeto.
LOCATION: sua região. Consulte as regiões compatíveis com o Memory Bank.
STAGING_BUCKET: o bucket do Cloud Storage que você vai usar para preparar o tempo de execução do mecanismo de agente.

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

Substitua:

PROJECT_ID: o ID do projeto.
LOCATION: sua região. Consulte as regiões compatíveis com o Memory Bank.
AGENT_ENGINE_ID: o ID do mecanismo de agente a ser usado no 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 e saiba como definir o agente para implantação no Cloud Run.

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

GKE

Para implantar seu agente no Google Kubernetes Engine (GKE), consulte as instruções na documentação do ADK e saiba como definir o agente para implantação no GKE.

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

Interaja com seu agente

Depois de definir o agente e configurar o banco de memória, você pode interagir com ele. Se você forneceu um callback para acionar a geração de memórias ao inicializar o agente, a geração de memórias será acionada sempre que o agente for invocado.

As recordações 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:

Corredor 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 seu executor.
USER_ID: um identificador do usuário. As recordações geradas nessa sessão são identificadas por esse identificador opaco. O escopo das recordações geradas é armazenado como {"user_id": "USER_ID"}.

Mecanismo do agente

Ao usar o modelo do ADK do Agent Engine, você pode chamar o tempo de execução do Agent Engine 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 do usuário. As recordações geradas nessa sessão são identificadas por esse identificador opaco. O escopo das recordações geradas é armazenado como {"user_id": "USER_ID"}.

Cloud Run

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

GKE

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

Exemplo de interação

Primeira sessão

Se você usou o PreloadMemoryTool, o agente vai tentar recuperar memórias no início de cada turno para acessar as preferências que o usuário comunicou anteriormente. Durante a primeira interação do agente com o usuário, não há memórias disponíveis para serem recuperadas. Assim, 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 recordações, mas nenhuma está disponível.
- Modelo: "Qual temperatura você prefere?"
- Callback: o ADK aciona a geração de memória. Nenhuma recordação é extraída.
Segunda rodada:
- Usuário: Me sinto confortável a 22 graus.
- (Chamada de ferramenta): o ADK tenta buscar recordações, mas nenhuma está disponível.
- Modelo: tudo bem, 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 vai 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. É tão desconfortável!
- (Chamada de ferramenta): o ADK tenta buscar memórias. A memória "Gosto da temperatura de 21 graus" é recuperada.
- Modelo: tudo bem, atualizei a temperatura para 22 graus.
- Callback: o ADK aciona a geração de memória. Nenhuma recordação é extraída porque o usuário não compartilhou nada significativo para manter.
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 21 graus" é recuperada.
- Modelo: Ok, aumentei a temperatura.
- Callback: o ADK aciona a geração de memória. A memória "Gosto de uma temperatura de 22 graus" é atualizada para "Geralmente gosto de uma temperatura de 22 graus, mas prefiro que esteja mais quente pela manhã".

Limpar

Para limpar todos os recursos usados neste projeto, é possível excluir o projeto Google Cloud usado no guia de 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 Vertex AI Agent Engine, o que também exclui todas as sessões ou memórias pertencentes a esse mecanismo.
```
agent_engine.delete(force=True)
```
Exclua todos os arquivos criados localmente.

A seguir

Guia de início rápido com o SDK do Agent Engine.

Guia de início rápido do Kit de desenvolvimento de agentes 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 seu 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 e um ambiente de execução do Memory Bank do ADK

Corredor local

Mecanismo do agente

Cloud Run

GKE

Interaja com seu agente

Corredor local

Mecanismo do agente

Cloud Run

GKE

Exemplo de interação

Limpar

A seguir

Guia de início rápido do Kit de desenvolvimento de agentes