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

Este tutorial demonstra como fazer chamadas API diretamente para as sessões e o banco de memória do Vertex AI Agent Engine através do SDK do Vertex AI Agent Engine. Use o SDK do Vertex AI Agent Engine se não quiser uma framework de agente para orquestrar chamadas por si ou se quiser integrar sessões e o banco de memória com frameworks de agentes que não sejam o Agent Development Kit (ADK).

Para o guia de início rápido com o ADK, consulte o artigo Guia de início rápido com o Agent Development Kit.

Este tutorial usa os seguintes passos:

  1. Crie memórias com as seguintes opções:
  2. Recuperar memórias.
  3. Limpar.

Antes de começar

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

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

Depois de configurar as sessões e o banco de memória do Vertex AI Agent Engine, pode criar sessões e anexar eventos às mesmas. As memórias são geradas como factos da conversa do utilizador com o agente, para que estejam disponíveis para interações futuras do utilizador. Para mais informações, consulte os artigos Gere memórias e Obtenha memórias.

  1. Crie uma sessão com um ID do utilizador opaco. Todas as memórias geradas a partir desta sessão são automaticamente associadas ao âmbito {"user_id": "USER_ID"}, a menos que forneça explicitamente um âmbito quando gera memórias.

    import vertexai

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

session = client.agent_engines.sessions.create(
  name=AGENT_ENGINE_NAME,
  user_id="USER_ID"
)

    Substitua o seguinte:

    • PROJECT_ID: o ID do seu projeto.

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

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

    • USER_ID: um identificador para o utilizador. Todas as memórias geradas a partir desta sessão são automaticamente associadas ao âmbito {"user_id": "USER_ID"}, a menos que forneça explicitamente um âmbito quando gera memórias.

  2. Carregue eventos de forma iterativa para a sua sessão. Os eventos podem incluir quaisquer interações entre o utilizador, o agente e as ferramentas. A lista ordenada de eventos representa o histórico de conversas da sua sessão. Este histórico de conversas é usado como material de origem para gerar memórias para esse utilizador 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 memórias a partir do seu histórico de conversas, acione um pedido de geração de memórias 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 o seguinte:

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

Carregue memórias

Em alternativa à geração de memórias através de diálogo não processado, pode carregar memórias ou fazer com que os seus agentes as adicionem diretamente através da GenerateMemories com factos pré-extraídos. Em vez de o banco de memória extrair informações do seu conteúdo, fornece diretamente os factos que devem ser armazenados sobre o utilizador. Recomendamos que escreva factos sobre os utilizadores na 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 o seguinte:

  • FACT: o facto pré-extraído que deve ser consolidado com as memórias existentes. Pode fornecer até 5 factos pré-extraídos numa lista como a seguinte:

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

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

Em alternativa, pode usar CreateMemory para carregar memórias sem usar o banco de memórias para extração ou consolidação de memórias.

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

Recupere e use memórias

Pode recuperar memórias do utilizador e incluí-las nas instruções do sistema para dar ao MDG acesso ao seu contexto personalizado.

Para mais informações sobre como obter memórias através de um método baseado no âmbito, consulte o artigo Obter memórias.

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

Pode usar jinja para converter as suas memórias estruturadas num 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>
"""

Elimine memórias

Pode eliminar uma memória específica através do respetivo nome do recurso:

client.agent_engines.memories.delete(name=MEMORY_NAME)

Substitua o seguinte:

  • MEMORY_NAME: o nome da memória a eliminar. O nome deve estar no seguinte formato: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory}. Pode encontrar o nome da memória obtendo memórias.

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 quaisquer sessões ou memórias associadas à instância do Vertex AI Agent Engine.

    agent_engine.delete(force=True)

  2. Elimine todos os ficheiros criados localmente.

O que se segue?