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

Este tutorial demonstra 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 uma estrutura de agente para orquestrar chamadas ou se quiser integrar sessões e o Memory Bank com estruturas de agente diferentes do Kit de desenvolvimento de agentes (ADK, na sigla em inglês).

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

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, siga as instruções em Configurar o Memory Bank.

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

Depois de configurar as sessões e o Memory Bank do Vertex AI Agent Engine, é possível criar sessões e adicionar eventos a elas. As recordações são geradas como fatos da conversa do usuário com o agente para que estejam 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"
)

session = client.agent_engines.create_session(
  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 existente 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.append_session_event(
  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 com base no histórico de conversas, acione uma solicitação de geração de recordações para a sessão:

    client.agent_engines.generate_memories(
  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 o Memory Bank extrair informações do seu conteúdo, você fornece diretamente os fatos que devem ser armazenados sobre o usuário. Recomendamos que você escreva fatos sobre os usuários na primeira pessoa (por exemplo, I am a software engineer).

client.agent_engines.generate_memories(
    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.create_memory(
    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 as 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.retrieve_memories(
        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>
"""

Excluir recordações

É possível excluir uma memória específica usando o nome do recurso dela:

client.agent_engines.delete_memory(name=MEMORY_NAME)

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.

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