Guia de início rápido da API REST

Neste tutorial, você vai aprender a fazer chamadas de API REST diretamente para as sessões e o banco de memória do Vertex AI Agent Engine para criar e usar sessões e memórias de longo prazo. Use a API REST se não quiser uma estrutura de agente para orquestrar chamadas ou se quiser integrar sessões e o banco de memória 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, primeiro siga as etapas em Configurar o Memory Bank.

Gerar memórias das 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 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.

    from google.cloud import aiplatform_v1beta1

sessions_client = aiplatform_v1beta1.SessionServiceClient(
  client_options={
    "api_endpoint": "https://LOCATION-aiplatform.googleapis.com"
  },
  transport="rest"
)

session_lro = sessions_client.create_session(
  parent=AGENT_ENGINE_NAME,
  session={"user_id": "USER_ID"}
)
session_name = "/".join(session_lro.operation.name.split("/")[0:-2])

    Substitua:

    • LOCATION: sua região. Somente us-central1 é compatível com o Memory Bank do Vertex AI Agent Engine.

    • 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.

    event = aiplatform_v1beta1.SessionEvent(
    author="user",  # Required by Sessions.
    invocation_id="1",  # Required by Sessions.
    timestamp=datetime.now().strftime('%Y-%m-%dT%H:%M:%SZ'),  # Required by Sessions.
    content = aiplatform_v1beta1.Content(
        role="user",
        parts=[aiplatform_v1beta1.Part(text="Hello")]
    )
)

sessions_client.append_event(name=session_name, event=event)

  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": session_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 CreateMemory. 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).

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

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