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 sua instância do Vertex AI Agent Engine para acessar as sessões e o banco de memória do Vertex AI Agent Engine.
  2. Crie recordações usando as seguintes opções:
  3. Recuperar lembranças.
  4. Limpeza.

Antes de começar

Para concluir as etapas demonstradas neste tutorial, primeiro configure seu projeto e ambiente.

Criar o projeto

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI API.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI API.

    Enable the API

    8.
  8. Se você selecionou um projeto, verifique se tem o papel do IAM de usuário da Vertex AI (roles/aiplatform.user) no projeto.

    9. Autenticar na Vertex AI

    Para usar os exemplos Python desta página em um ambiente de desenvolvimento local, instale e inicialize o gcloud CLI e e configure o Application Default Credentials com suas credenciais de usuário.

    1. Install the Google Cloud CLI.

    2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    3. To initialize the gcloud CLI, run the following command: 

      gcloud init

    4. If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud .

    Importar bibliotecas

    Instale o SDK da Vertex AI:

    pip install google-cloud-aiplatform>=1.100.0

    Criar sua instância do Vertex AI Agent Engine

    Para acessar as sessões e o banco de memória do Vertex AI Agent Engine, primeiro crie uma instância do Vertex AI Agent Engine. Não é necessário implantar um agente para começar a usar as sessões e o banco de memória. Sem a implantação do agente, a criação de uma instância do Vertex AI Agent Engine leva alguns segundos.

    import vertexai

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

agent_engine = client.agent_engines.create()

    Substitua:

    • PROJECT_ID: o ID do projeto.
    • LOCATION: sua região. Somente us-central1 é compatível com o banco de memória do Vertex AI Agent Engine.

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

    Depois de configurar as sessões e o banco de memória do Vertex AI Agent Engine, é possível criar sessões e adicionar eventos a elas. As memórias 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 e recuperar memórias.

    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 banco de memória 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 as recordações 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