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, primeiro tem de seguir os passos em Configuração do banco de memória.

Gere memórias com 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-lhes eventos. 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 indexadas pelo â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"
)
# For Express Mode users, initialize the Vertex AI Client as follows:
# client = vertexai.Client(
#   api_key="API_KEY",
# )

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

    • PROJECT_ID: o ID do 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 iterativamente 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"}. Só são consideradas para a consolidação as memórias com o mesmo âmbito. Se não for indicado, é usado {"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 de 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"}. Só são consideradas para a consolidação as memórias com o mesmo âmbito.

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 todas as 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?