Configurar o ambiente para o Memory Bank

Antes de trabalhar com o Memory Bank do Vertex AI Agent Engine, é necessário configurar seu ambiente. Embora o Memory Bank faça parte do Agent Engine, não é necessário implantar seu código no ambiente de execução do Agent Engine para usar o Memory Bank.

Crie o projeto Google Cloud

Cada projeto pode ser identificado de duas formas: pelo número ou pelo ID. O PROJECT_NUMBER é criado automaticamente quando você cria o projeto, enquanto o PROJECT_ID é criado por você ou por quem criou o projeto. Para configurar um projeto:

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI API.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI API.

    Enable the API

    8.

    Ter os papéis necessários

    Para receber as permissões necessárias para usar o Vertex AI Agent Engine, peça ao administrador para conceder a você o papel do IAM de Usuário da Vertex AI (roles/aiplatform.user) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

    Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

    Se você estiver fazendo solicitações ao Memory Bank de um agente implantado no Google Kubernetes Engine ou no Cloud Run, verifique se a conta de serviço tem as permissões necessárias. O agente de serviço do Reasoning Engine já tem as permissões necessárias para ler e gravar memórias. Portanto, as solicitações de saída do tempo de execução do Agent Engine já têm permissão para acessar o banco de memória.

    Configurar o ambiente

    Nesta seção, pressupomos que você configurou um ambiente de desenvolvimento em Python ou está usando um ambiente de execução com um ambiente de desenvolvimento em Python, como o Colab.

    Instalar bibliotecas

    Instale o SDK da Vertex AI:

      pip install google-cloud-aiplatform>=1.104.0

    Autenticação

    As instruções de autenticação dependem de você estar usando a Vertex AI no modo rápido:

    • Se você não estiver usando a Vertex AI no modo express, siga as instruções em Autenticar na Vertex AI.

    • Se você estiver usando a Vertex AI no modo express, configure a autenticação definindo a chave de API no ambiente:

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

    Configurar um cliente do SDK da Vertex AI

    Execute o código a seguir para configurar um cliente do SDK da Vertex AI:

    import vertexai
client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
)

    em que

    Configurar a instância do Agent Engine

    Para começar a usar o Memory Bank, primeiro você precisa de uma instância do Agent Engine.

    Você tem estas três opções:

    Usar uma instância atual

    Se você não precisar modificar uma instância do Agent Engine, execute o seguinte comando para configurar a instância para o Memory Bank:

    agent_engine = client.agent_engines.get(name="AGENT_ENGINE_NAME")

    Substitua:

    • AGENT_ENGINE_NAME: o nome do mecanismo de agente. Ele precisa estar no formato projects/.../locations/.../reasoningEngines/.... Consulte as regiões compatíveis com o Memory Bank.

    Criar ou atualizar uma instância

    Ao criar ou atualizar uma instância do Agent Engine, é possível substituir os padrões do Agent Engine para fazer as seguintes modificações:

    Criar

    O Memory Bank é ativado por padrão quando você cria uma instância do Agent Engine. É possível usar a instância em qualquer ambiente, incluindo o Google Kubernetes Engine e o Cloud Run. Você precisa do nome do Agent Engine que identifica o banco de memória e permissão suficiente para chamar o banco de memória.

      agent_engine = client.agent_engines.create()

    As novas instâncias ficam vazias, a menos que você primeiro crie ou gere recordações.

    Atualizar

    É possível atualizar uma instância do Agent Engine se você quiser atualizar o Agent Engine e manter as memórias armazenadas na instância. É possível fazer atualizações como mudar a configuração do banco de memória ou implantar seu agente no ambiente de execução do Agent Engine.

      agent_engine = client.agent_engines.update(
        # If you have an existing AgentEngine, you can access the name using `agent_engine.api_resource.name`.
        name="AGENT_ENGINE_NAME",
        # Optional.
        agent_engine=...,
        # Optional.
        config=...
  )

    Substitua:

    • AGENT_ENGINE_NAME: o nome do mecanismo de agente. Ele precisa estar no formato projects/.../locations/.../reasoningEngines/.... Consulte as regiões compatíveis com o Memory Bank.

    Definir a configuração do Memory Bank

    Você pode configurar o Banco de Memórias para personalizar como as recordações são geradas e gerenciadas. Se a configuração não for fornecida, o Memory Bank vai usar as configurações padrão.

    # Optional.
similarity_search_config = {
        "similarity_search_config": {
                "embedding_model": "EMBEDDING_MODEL",
        }
}

# Optional
generation_config = {
      "generation_config": {
            "model": "LLM_MODEL",
      }
}

context_spec = {
      "context_spec": {
            "memory_bank_config": {
                  **similarity_search_config,
                  **generation_config
            }
      }
}

# Create an Agent Engine with a Memory Bank Config.
agent_engine = client.agent_engines.create(
      config={
            # Optional.
            **context_spec
      }
)

    Substitua:

    • EMBEDDING_MODEL: o modelo de embedding de texto do Google a ser usado para a pesquisa de similaridade, no formato projects/{project}/locations/{location}/publishers/google/models/{model}. O Memory Bank usa o text-embedding-005 como modelo padrão. Se você espera que as conversas dos usuários sejam em idiomas diferentes do inglês, use um modelo que ofereça suporte a vários idiomas, como gemini-embedding-001 ou text-multilingual-embedding-002, para melhorar a qualidade da recuperação.

    • LLM_MODEL: o modelo de LLM do Google a ser usado para extrair e consolidar memórias, no formato projects/{project}/locations/{location}/publishers/google/models/{model}. O Memory Bank usa o gemini-2.0-flash-001 como modelo padrão.

    Implantar seu agente com memória no Agent Engine

    Embora o Memory Bank possa ser usado em qualquer ambiente de execução, você também pode usá-lo com o ambiente de execução do Agent Engine para ler e gravar memórias do seu agente implantado.

    Para implantar um agente com o Memory Bank no ambiente de execução do Vertex AI Agent Engine, primeiro configure seu ambiente para o ambiente de execução do Agent Engine. Em seguida, prepare o agente para ser implantado no ambiente de execução do Agent Engine com integração de memória. O agente implantado precisa fazer chamadas para ler e gravar memórias conforme necessário.

    AdkApp

    Se você estiver usando o modelo do kit de desenvolvimento de agentes do Agent Engine, o agente usará o VertexAiMemoryBankService por padrão quando for implantado no ambiente de execução do Agent Engine. Isso significa que o agente usa automaticamente o Memory Bank para gerenciar as memórias.

    from google.adk.agents import Agent
from vertexai.preview.reasoning_engines import AdkApp

# Develop an agent using the ADK template.
agent = Agent(...)

adk_app = AdkApp(
      agent=adk_agent,
      ...
)

# Deploy the agent to Agent Engine runtime.
agent_engine = client.agent_engines.create(
      agent_engine=adk_app,
      config={
            "staging_bucket":
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
            # Optional.
            **context_spec
      }
)

    Quando executado localmente, o modelo do ADK usa InMemoryMemoryService por padrão. Se você quiser usar instâncias diferentes do Agent Engine para memórias e implantação ou usar um AdkApp com o Memory Bank localmente, substitua a instância usada pelo Memory Bank:

    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
)

agent_engine = client.agent_engines.create(
      agent_engine=adk_app,
      config={
            "staging_bucket":
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
            # Optional.
            **context_spec
      }
)

    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.

    Para mais informações sobre como usar o Memory Bank com o ADK, consulte o Guia de início rápido com o Agent Development Kit.

    Agente personalizado

    É possível usar o Memory Bank com seu agente personalizado implantado no ambiente de execução do Agent Engine.

    Se quiser usar a mesma instância do Agent Engine para o banco de memória e o ambiente de execução do Agent Engine, leia as variáveis de ambiente GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION,GOOGLE_CLOUD_AGENT_ENGINE_ID para inferir o nome do Agent Engine no ambiente:

    project = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION")
agent_engine_id = os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID")

agent_engine_name = f"projects/{project}/locations/{location}/reasoningEngines/{agent_engine_id}"

    A seguir