Esta página foi traduzida pela API Cloud Translation.

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

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

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

Crie seu agente e executor local 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 memórias 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.

Antes de começar

Para concluir as etapas demonstradas neste tutorial, primeiro siga as etapas em Configurar o Memory Bank.

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

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

Modo Express da Vertex AI

import os

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

Substitua:

API_KEY: sua chave de API do modo Express da Vertex AI. Se você estiver usando o Google Cloudpela primeira vez, inscreva-se com sua conta do Gmail para receber uma chave de API usando o Registro no modo expresso.

Criar seu agente do ADK

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()]
)

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. 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:
- PROJECT_ID: o ID do projeto.
- LOCATION: sua região. Consulte as regiões compatíveis com o Memory Bank.
Modo Express da 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:
- API_KEY: sua chave de API do modo Express da Vertex AI. Se você estiver usando o Google Cloudpela primeira vez, inscreva-se com sua conta do Gmail para receber uma chave de API usando o Registro no modo expresso.
VertexAiMemoryBankService é um wrapper do ADK para o Memory Bank definido pelo 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órias com o ADK, defina suas próprias funções de callback.
- memory_service.search_memory, que aciona uma solicitação RetrieveMemories ao banco de memória 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.
Crie um ambiente de execução do ADK, que orquestra 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 tempo de execução do Agent Engine, oferece o 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:

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

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

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.

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.

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

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.

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

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

Gerar lembranças para sua sessão atual. Se o Banco de Memórias extrair recordações da conversa, elas serão armazenadas no escopo {"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

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

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`

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

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

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 Memory Bank.

# 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, é 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.

Antes de começar

Defina as variáveis de ambiente

Google Cloud Projeto

Modo Express da Vertex AI

Criar seu agente do ADK

Google Cloud Projeto

Modo Express da Vertex AI

adk.Runner

Modelo do ADK do Agent Engine

Interaja com seu agente

adk.Runner

Modelo do ADK do Agent Engine

adk.Runner

Modelo do ADK do Agent Engine

adk.Runner

Modelo do ADK do Agent Engine

Limpar

A seguir

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

`adk.Runner`

`adk.Runner`

`adk.Runner`

`adk.Runner`