Guia de início rápido do SDK do Vertex AI Agent Engine

Neste tutorial, mostramos como fazer chamadas de API diretamente para sessões e banco de memória do Vertex AI Agent Engine usando o SDK do Vertex AI Agent Engine. Use o SDK do Vertex AI Agent Engine se não quiser um framework de agente para orquestrar chamadas ou se quiser integrar as Sessões e o Banco de Memória com frameworks de agente que não sejam o Kit de Desenvolvimento de Agente (ADK).

Para o início rápido usando o ADK, consulte Início rápido com o Kit de Desenvolvimento de Agente.

Este tutorial usa as seguintes etapas:

  1. Crie recordações usando as seguintes opções:
  2. Recuperar lembranças.
  3. Limpeza.

Antes de começar

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

Gerar memórias com sessões do Agent Engine da Vertex AI

Depois de configurar as sessões e o Memory Bank do Vertex AI Agent Engine, é possível criar sessões e anexar eventos a elas. As recordações são geradas como fatos da conversa do usuário com o agente para que fiquem disponíveis para interações futuras. Para mais informações, consulte Gerar recordações e Buscar recordações.

  1. Crie uma sessão com um ID de usuário opaco. Todas as recordações geradas nessa sessão são automaticamente identificadas pelo escopo {"user_id": "USER_ID"}, a menos que você forneça um escopo explicitamente ao gerar recordações.

    import vertexai

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

# This assumes that you already have an Agent Engine instance. If you don't,
# you can create one using `agent_engine = client.agent_engines.create()`.
session = client.agent_engines.sessions.create(
  # The name can be fetched using `agent_engine.api_resource.name`.
  name="AGENT_ENGINE_NAME",
  user_id="USER_ID"
)

    Substitua:

    • PROJECT_ID: o ID do projeto.

    • LOCATION: sua região. Consulte as regiões compatíveis com o Memory Bank.

    • AGENT_ENGINE_NAME: o nome da instância do Vertex AI Agent Engine que você criou ou uma instância atual do Vertex AI Agent Engine. O nome precisa estar no seguinte formato: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}.

    • USER_ID: um identificador do usuário. Todas as recordações geradas nessa sessão são automaticamente identificadas pelo escopo {"user_id": "USER_ID"}, a menos que você forneça um escopo explicitamente ao gerar recordações.

  2. Faça upload iterativo de eventos para sua sessão. Os eventos podem incluir qualquer interação entre o usuário, o agente e as ferramentas. A lista ordenada de eventos representa o histórico de conversas da sua sessão. Esse histórico de conversas é usado como material de origem para gerar memórias para esse usuário específico.

    import datetime

client.agent_engines.sessions.events.append(
  name=session.response.name,
  author="user",  # Required by Sessions.
  invocation_id="1",  # Required by Sessions.
  timestamp=datetime.datetime.now(tz=datetime.timezone.utc),  # Required by Sessions.
  config={
    "content": {
      "role": "user",
      "parts": [{"text": "hello"}]
    }
  }
)

  3. Para gerar recordações do seu histórico de conversas, acione uma solicitação de geração de recordações para a sessão:

    client.agent_engines.memories.generate(
  name=agent_engine.api_resource.name,
  vertex_session_source={
    # `session` should have the format "projects/.../locations/.../reasoningEngines/.../sessions/...".
    "session": session.response.name
  },
  # Optional when using Agent Engine Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE
)

Substitua:

  • (Opcional) SCOPE: um dicionário que representa o escopo das memórias geradas, com um máximo de cinco pares de chave-valor e sem caracteres *. Por exemplo, {"session_id": "MY_SESSION"}. Somente as memórias com o mesmo escopo são consideradas para consolidação. Se não for fornecido, {"user_id": session.user_id} será usado.

Fazer upload de recordações

Como alternativa a gerar memórias usando diálogos brutos, você pode fazer upload de memórias ou pedir que seus agentes as adicionem diretamente usando GenerateMemories com fatos pré-extraídos. Em vez de extrair informações do seu conteúdo, o Memory Bank recebe diretamente os fatos que devem ser armazenados sobre o usuário.

Para garantir a consistência com as memórias geradas, tente escrever fatos pré-extraídos na mesma perspectiva que você configurou para o escopo específico. Por padrão, as recordações são geradas na perspectiva em primeira pessoa (por exemplo, I am a software engineer).

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

Substitua:

  • FACT: o fato pré-extraído que precisa ser consolidado com as memórias atuais. É possível fornecer até cinco fatos pré-extraídos em uma lista como esta:

    {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}

  • SCOPE: um dicionário que representa o escopo das memórias geradas. Por exemplo, {"session_id": "MY_SESSION"}. Somente as memórias com o mesmo escopo são consideradas para consolidação.

Você também pode usar CreateMemory para fazer upload de recordações sem usar o Banco de recordações para extração ou consolidação.

memory = client.agent_engines.memories.create(
    name=agent_engine.api_resource.name,
    fact="This is a fact.",
    scope={"user_id": "123"}
)

"""
Returns an AgentEngineMemoryOperation containing the created Memory like:

AgentEngineMemoryOperation(
  done=True,
  metadata={
    "@type': 'type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateMemoryOperationMetadata",
    "genericMetadata": {
      "createTime": '2025-06-26T01:15:29.027360Z',
      "updateTime": '2025-06-26T01:15:29.027360Z'
    }
  },
  name="projects/.../locations/us-central1/reasoningEngines/.../memories/.../operations/...",
  response=Memory(
    create_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC)),
    fact="This is a fact.",
    name="projects/.../locations/us-central1/reasoningEngines/.../memories/...",
    scope={
      "user_id": "123"
    },
    update_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC))
  )
)
"""

Recuperar e usar recordações

Você pode recuperar memórias do usuário e incluí-las nas instruções do sistema para dar ao LLM acesso ao seu contexto personalizado.

Para mais informações sobre como recuperar recordações usando um método baseado em escopo, consulte Buscar recordações.

# Retrieve all memories for User ID 123.
retrieved_memories = list(
    client.agent_engines.memories.retrieve(
        name=agent_engine.api_resource.name,
        scope={"user_id": "123"}
    )
)

Use o jinja para converter suas recordações estruturadas em um comando:


from jinja2 import Template

template = Template("""
<MEMORIES>
Here is some information about the user:
{% for retrieved_memory in data %}* {{ retrieved_memory.memory.fact }}
{% endfor %}</MEMORIES>
""")

prompt = template.render(data=retrieved_memories)

"""
Output:

<MEMORIES>
Here is some information about the user:
* This is a fact
</MEMORIES>
"""

Remover recordações

Há várias maneiras de excluir recordações da sua instância do Banco de recordações, dependendo de como você quer selecionar quais delas devem ser removidas.

Remover pelo nome do recurso

Se você souber exatamente qual recurso de memória quer remover, poderá excluir uma memória específica usando o nome do recurso:

client.agent_engines.memories.delete(
    name=MEMORY_NAME,
    config={
        # Set to false (default) if you want to delete the memory asynchronously.
        "wait_for_completion": True
    }
)

Substitua:

  • MEMORY_NAME: o nome da memória a ser excluída. O nome precisa estar no seguinte formato: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory}. Para encontrar o nome de uma recordação, busque as recordações.

Remover por critérios

Você pode usar a exclusão com base em critérios para remover uma ou mais recordações. Somente as recordações que corresponderem ao filtro fornecido serão excluídas.

operation = client.agent_engines.memories.purge(
    name=agent_engine.api_resource.name,
    filter=FILTER_STRING,
    # Set to false (default) if you want to stage but not execute the purge operation.
    force=True,
    config={
        # Set to false (default) if you want to purge memories asynchronously.
        "wait_for_completion": True
    }
)

Substitua:

  • FILTER_STRING: uma string que usa a sintaxe EBNF para filtrar campos do sistema. Os campos do sistema incluem create_time, update_time, fact e topics. Consulte esta documentação para saber mais sobre a filtragem em campos do sistema.

A operação vai retornar uma contagem de quantas memórias foram removidas (se force=True) ou seriam removidas se a operação fosse executada (se force=False).

print(operation.response.purge_count)

Remover por significado semântico

Durante a geração de recordações, o Banco de Memórias decide se cria, atualiza ou exclui recordações com base no conteúdo das informações recém-extraídas e nas recordações atuais. Uma recordação pode ser excluída se as novas informações a contradizerem ou se o conteúdo extraído instruir o Banco de Memória a esquecer um assunto (no caso do tema de recordação EXPLICIT_INSTRUCTIONS).

Por exemplo, a solicitação a seguir excluiria as recordações que contêm informações sobre preferências alimentares, se elas existirem para o scope especificado:

from google import genai

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_contents_source={
      "events": [{
        "content": genai.types.Content(
          role="user",
          parts=[
            genai.types.Part.from_text(text="Forget my dietary preferences.")
          ]
        )
      }]
    },
    scope={...}
)

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 associadas a ela.

    agent_engine.delete(force=True)

  2. Exclua todos os arquivos criados localmente.

A seguir