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

Depois de configurar o agente do Kit de desenvolvimento de agentes (ADK) para usar o Memory Bank, ele vai orquestrar chamadas para o Memory Bank e gerenciar memórias de longo prazo para você.

Neste tutorial, mostramos como usar o Memory Bank com o ADK para gerenciar memórias de longo prazo:

  1. Crie seu agente e executor do ADK local.

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

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

Antes de começar

Para concluir as etapas demonstradas neste tutorial, siga as instruções em 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_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

  1. Ao desenvolver seu agente do ADK, inclua uma ferramenta Memory que controle quando o agente recupera memórias e como elas são incluídas no comando. O agente de exemplo usa o PreloadMemoryTool, que sempre recupera memórias no início de cada turno e as inclui 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 VertexAiMemoryBankService, que o executor do ADK usa para recuperar memórias. Isso é opcional se você estiver usando o modelo do ADK do Agent Engine em vez de definir seu próprio ambiente 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 para o Memory Bank definido por BaseMemoryService do ADK e usa uma interface diferente do SDK do Agent Engine. É possível usar o SDK do Agent Engine para fazer chamadas diretas de API para o Memory Bank. A interface VertexAiMemoryBankService inclui:

    • memory_service.add_session_to_memory, que aciona uma solicitação GenerateMemories ao Memory Bank usando o adk.Session fornecido como conteúdo de origem. As chamadas para esse método não são organizadas pelo executor da ADK. Se quiser automatizar a geração de memória com o ADK, defina suas próprias funções de callback.

    • memory_service.search_memory, que aciona uma solicitação RetrieveMemories ao Memory Bank para buscar recordações relevantes para o user_id e o app_name atuais. As chamadas para esse método são organizadas pelo executor do ADK quando você fornece uma ferramenta de memória ao seu agente.

  3. Crie um ambiente de execução do ADK, que organiza a execução de agentes, ferramentas e callbacks. A configuração do ADK Runner depende do ambiente de implantação que você está usando:

adk.Runner

O adk.Runner geralmente é usado em um ambiente local, como o Colab. A maioria das opções de implantação, como o Agent Engine Runtime, oferece o próprio ambiente de execução para o 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)

Substitua:

  • APP_NAME: o nome do seu app do ADK.

Modelo do ADK do Agent Engine

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 Agent Engine Runtime, 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 Memory Bank e o Agent Engine Runtime. Não é necessário fornecer explicitamente um serviço de memória nesse caso.

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 o agente do ADK no ambiente de execução do Agent Engine:

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)

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 banco de memória. Por exemplo, 456 em projects/my-project/locations/us-central1/reasoningEngines/456.
  • 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 banco de memória. Por exemplo, 456 em projects/my-project/locations/us-central1/reasoningEngines/456.

Interaja com seu agente

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

  1. Crie sua primeira sessão. Como não há memórias disponíveis durante a primeira sessão com um usuário, o agente não conhece as preferências dele, como a temperatura preferida:

    adk.Runner

    Ao usar adk.Runner, é possível 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:

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

    Modelo do ADK do Agent Engine

    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.

    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:

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

  2. Gerar lembranças para sua sessão atual. Se o Memory Bank extrair recordações da conversa, elas serão armazenadas no escopo {"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 segunda sessão. Se você usou o PreloadMemoryTool, o agente vai recuperar memórias no início de cada turno para acessar as preferências que o usuário comunicou anteriormente.

    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 é possível usar memory_service.search_memory para recuperar recordações diretamente:

    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?

    Você também pode usar agent_engine.async_search_memory para recuperar memórias diretamente: Observação: para usar async_search_memory, seu AdkApp precisa ter sido criado com a versão 1.110.0 ou mais recente do google-cloud-aiplatform. Caso contrário, você pode recuperar recordações 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, é 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:

  1. 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 Vertex AI Agent Engine.

    agent_engine.delete(force=True)

  2. Exclua todos os arquivos criados localmente.

A seguir