Início rápido com o Agent Development Kit

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Depois de configurar o seu agente do Agent Development Kit (ADK) para usar o banco de memória, o agente orquestra as 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. Os executores do ADK associam o seu agente a serviços que oferecem gestão de sessões e memória.

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.

Importante: o ADK usa principalmente funções assíncronas. Se estiver a executar código num bloco de notas, como o Colab, pode executar diretamente await funções assíncronas porque já está a ser executado um ciclo de eventos. Se estiver a executar este código como um script Python padrão, tem de envolver as chamadas de funções assíncronas com asyncio.run() para criar e gerir um ciclo de eventos para executar as suas funções assíncronas. Caso contrário, pode receber um erro como 'await' outside function.

Para ver um exemplo de utilização do Memory Bank com o ADK, execute o bloco de notas "Comece a usar o Memory Bank no ADK" num dos seguintes ambientes:

Abrir no Colab | Abrir no Colab Enterprise | Abrir no Vertex AI Workbench | Ver no GitHub

Antes de começar

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

Nota: se já tiver um Google Cloud projeto, pode seguir o guia com o número do projeto e a localização através das instruções "Google Cloud Projeto". Se for um utilizador Google Cloud pela primeira vez, pode inscrever-se com a sua conta do Gmail para obter um projeto e uma chave de API do modo expresso sem faturação através do registo do modo expresso e, em seguida, seguir o guia com as instruções do "Modo expresso da Vertex AI".

Defina variáveis de ambiente

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

Google Cloud Projeto

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 projeto.
• LOCATION: a sua região. Consulte as regiões suportadas para o Banco de memória.

Modo expresso do Vertex AI

import os

os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "TRUE"
os.environ["GOOGLE_API_KEY"] = "API_KEY"

Substitua o seguinte:

• API_KEY: a chave da API do modo expresso da Vertex AI. Pode inscrever-se com a sua Conta do Gmail para receber uma chave da API através do registo no modo expresso se for um utilizador da API Google Maps pela primeira vez Google Cloud.

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. Se quiser configurar o comportamento da instância do Memory Bank, consulte o guia de configuração.

   Google Cloud Projeto

   from google.adk.memory import VertexAiMemoryBankService
   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 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]
   
   memory_service = VertexAiMemoryBankService(
       project="PROJECT_ID",
       location="LOCATION",
       agent_engine_id=agent_engine_id
   )
   

   Substitua o seguinte:

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

   Modo expresso do Vertex AI

   from google.adk.memory import VertexAiMemoryBankService
   import vertexai
   
   client = vertexai.Client(
     api_key="API_KEY",
   )
   # 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 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]
   
   # Make sure your environment variables are set. VertexAiMemoryBankService
   # will read your api key from the GOOGLE_API_KEY environment variable.
   memory_service = VertexAiMemoryBankService(
       agent_engine_id=agent_engine_id
   )
   

   Substitua o seguinte:

   • API_KEY: a chave da API do modo expresso da Vertex AI. Pode inscrever-se com a sua Conta do Gmail para receber uma chave da API através do registo no modo expresso se for um utilizador da API Google Maps pela primeira vez Google Cloud.

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

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.

import asyncio

from google.adk.sessions import VertexAiSessionService
from google.genai import types

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

# For Express Mode users, ensure your environment variables are set and
# initialize VertexAiSessionService as follows:
#
# session_service = VertexAiSessionService(
#    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
)

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

Nota: os utilizadores do modo expresso devem seguir as instruções para implementar a partir de ficheiros de origem para implementar a sua app ADK.

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

• PROJECT_ID: o ID do 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:

# For Google Cloud Project users:
def memory_bank_service_builder():
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="LOCATION",
        agent_engine_id="AGENT_ENGINE_ID"
    )
# For Express Mode users, ensure your environment variables are set.
#
# def memory_bank_service_builder():
#    return VertexAiMemoryBankService(
#        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 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:

   Nota: pode haver alguma variação nas respostas do agente e do banco de memória, consoante os modelos usados.

   adk.Runner

   Quando usa o adk.Runner, pode chamar diretamente os serviços de memória e sessão do ADK.

   # 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 update the temperature to my preferred temperature?",
       session.id,
       "USER_ID"
   )
   # Agent response: "What is your preferred temperature?"
   
   # Use `asyncio.run(call_agent(...))` if you're running this code as a
   # standard Python script.
   await 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.

   # 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 update the temperature to my preferred temperature?",
       session.get("id"),
       "USER_ID"
   )
   # Agent response: "What is your preferred temperature?"
   
   # Use `asyncio.run(call_agent(...))` if you're running this code as a
   # standard Python script.
   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

   async def trigger_memory_generation(app_name, session):
       # Refresh your `session` object so that all of the session events locally available.
       session = await session_service.get_session(
           app_name=app_name,
           user_id="USER_ID",
           session_id=session.id
       )
       await memory_service.add_session_to_memory(session)
   
   # Use `asyncio.run(trigger_memory_generation(...))` if you're running this
   # code as a standard Python script.
   await trigger_memory_generation(app_name, session)
   

   Modelo do ADK do Agent Engine

   Nota: para usar o async_add_session_to_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 acionar a geração de memória fazendo chamadas diretas para o banco de memória.

   # Use `asyncio.run(agent_engine.async_add_session_to_memory(...))` if
   # you're running this code as a standard Python script.
   await agent_engine.async_add_session_to_memory(session=session)
   

3. Crie a sua segunda sessão. Se usou o 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

   # Use `asyncio.run(session_service.create_session(...))` 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("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:

   # Use `asyncio.run(memory_service.search_memory(...))` if you're running
   # this code as a standard Python script.
   await memory_service.search_memory(
       app_name="APP_NAME",
       user_id="USER_ID",
       query="Fix the temperature!",
   )
   

   Modelo do ADK do Agent Engine

   # Use `asyncio.run(agent_engine.async_add_session_to_memory(...))` 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("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.

   # Use `asyncio.run(agent_engine.async_search_memory(...))` if you're
   # running this code as a standard Python script.
   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.