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. Interaja 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 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ória.

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 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 orquestra 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:

adk.Runner

adk.Runner é geralmente usado num ambiente local, como o Colab. A maioria das opções de implementação, como o Agent Engine Runtime, oferece o seu próprio tempo 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 o seguinte:

  • APP_NAME: o nome da sua app ADK.

Modelo do ADK do Agent Engine

O modelo do ADK do Agent Engine (AdkApp) pode ser usado localmente e para implementar um agente ADK no tempo de execução do Agent Engine. Quando implementado no tempo de execução do Agent Engine, o modelo do ADK do Agent Engine usa o VertexAiMemoryBankService como o serviço de memória predefinido, usando a mesma instância do Agent Engine para o banco de memória que o tempo de execução do Agent Engine. Neste caso, não precisa de fornecer explicitamente um serviço de memória.

Consulte o artigo Configure o Agent Engine para ver mais detalhes sobre a configuração do tempo de execução do Agent Engine, incluindo como personalizar o comportamento do seu banco de memória.

Use o seguinte código para implementar o seu agente ADK no Agent Engine Runtime:

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 o seguinte:

  • PROJECT_ID: o ID do seu projeto.
  • LOCATION: a sua região. Consulte as regiões suportadas para o Banco de memória.
  • AGENT_ENGINE_ID: o ID do motor do agente a usar para o banco de memória. Por exemplo, 456 em projects/my-project/locations/us-central1/reasoningEngines/456.
  • STAGING_BUCKET: o seu contentor do Cloud Storage a usar para preparar o tempo de execução do Agent Engine.

Quando executado localmente, o modelo do ADK usa o InMemoryMemoryService como o serviço de memória predefinido. No entanto, pode substituir o serviço de memória predefinido 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 o seguinte:

  • PROJECT_ID: o ID do seu projeto.
  • LOCATION: a sua região. Consulte as regiões suportadas para o Banco de memória.
  • AGENT_ENGINE_ID: o ID do motor do agente a usar para o banco de memória. Por exemplo, 456 em projects/my-project/locations/us-central1/reasoningEngines/456.

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?