Usar o serviço de memória standalone

Crie um projeto somente de memória.

Execute o seguinte comando para estruturar um projeto somente de memória. Substitua "My Project" pelo nome do seu projeto .

agentengine create --memory-only --name "My Project"

O comando gera um diretório de projeto que contém apenas um arquivo project-config.yaml, sem nenhum arquivo agent.yaml ou espaço de trabalho.

Crie e selecione o projeto na plataforma.

1. Execute o seguinte comando para registrar o projeto. O comando imprime o novo ID do projeto:

   agentengine project create "My Project"

2. Selecione o novo projeto como ativo. Substitua <project-id> pelo ID do projeto impresso pelo comando anterior:

   agentengine auth login --project-id <project-id>

Configurar configurações de memória.

1. Abra o arquivo project-config.yaml e defina seus nomes secretos e o provedor de extração sob o bloco memory:.

2. Execute os seguintes comandos para definir os segredos necessários para seu projeto:

   agentengine secret set MONGODB_URI --value "<value>" --project-id <project-id>
   agentengine secret set VOYAGE_API_KEY --value "<value>" --project-id <project-id>
   agentengine secret set ANTHROPIC_API_KEY --value "<value>" --project-id <project-id>

   Substitua os seguintes valores de espaço reservado:

   • <value>: valor do segredo.

     • MONGODB_URI: Connection string do seu Atlas cluster.

     • VOYAGE_API_KEY: Sua chave de IA Voyage.

     • ANTHROPIC_API_KEY: A chave do seu provedor LLM.

   • <project-id>: ID do objeto do projeto retornado pelo comando agentengine project create. Esse sinalizador é necessário porque o fluxo de trabalho somente de memória não inclui um arquivo agents.yaml.

   Substitua ANTHROPIC_API_KEY pelo nome da chave do seu provedor de LLM se você usar um provedor diferente.

3. Armazene a configuração de memória:

   agentengine memory configure

Provisione o servidor de memória.

Inicie o tempo de execução da memória e aguarde até que esteja pronto:

agentengine memory apply --wait

Crie uma conta de serviço e recupere um token de acesso.

1. Execute o seguinte comando para criar uma conta de serviço para o projeto:

   agentengine service-account create memory-service --project-id <project-id> --role PROJECT_OWNER

   Substitua o espaço reservado <project-id> pelo ID do projeto. Salve o ID do cliente e o segredo do cliente da saída do comando. O Atlas Agent Engine mostra o segredo do cliente apenas uma vez.

2. Execute o seguinte comando para trocar o ID e o segredo do cliente por um token de acesso:

   export ACCESS_TOKEN=$(curl --fail-with-body --silent --show-error \
     --user <client-id> \
     --data grant_type=client_credentials \
     "https://agentengine.mongodb.com/api/v1/oauth/token" | jq -er .access_token)

   Substitua o placeholder <client-id> pelo seu ID de cliente . curl solicita o segredo do cliente sem repeti-lo.

   Dica

   O token de acesso é válido por uma hora. Solicite um novo token antes que o atual expire.

Instale o Python SDK.

Instale o pacote agent-engine-sdk-memory do registro privado da plataforma usando o token de acesso que você exportou na etapa anterior:

pip install agent-engine-sdk-memory \
  --extra-index-url "https://ignore:$ACCESS_TOKEN@agentengine.mongodb.com/api/v1/packages/python/simple"

uv pip install agent-engine-sdk-memory \
  --extra-index-url "https://ignore:$ACCESS_TOKEN@agentengine.mongodb.com/api/v1/packages/python/simple"

O URL utiliza o formato username:password. ignore é um nome de usuário do espaço reservado, porque o registro autentica usando somente o token de acesso no campo de senha. $ACCESS_TOKEN for resolvido para o token de acesso que você exportou na etapa anterior.

Registre e recupere o contexto da conversa.

Em seu aplicação, adicione o seguinte código para criar um cliente, vincular uma identidade de usuário, registrar as reviravoltas conforme elas acontecem e recuperar o contexto relevante em conversas posteriores:

from agent_engine_sdk_memory import (
    Memory,
    MemoryRequestContext,
)
# Create the client using your access token.
memory = Memory(service_account_token="<your-access-token>")
# Bind the user and session for this conversation.
chat = memory.bind(
    MemoryRequestContext(
        user_id="user_1",
        session_id="thread_123",
    )
)
# Record turns as they happen.
chat.record_turn(
    role="user",
    content="I always fly out of Boston.",
)
chat.record_turn(
    role="assistant",
    content="Got it, Boston is saved as your home airport.",
)
# In a later conversation, recall what matters.
later = memory.bind(
    MemoryRequestContext(
        user_id="user_1",
        session_id="thread_456",
    )
)
context = later.build_context(
    query="Where should the flight book from?"
)
hits = later.search("home airport", top_k=5)

Organize um projeto de memória local .

Execute o seguinte comando para estruturar um projeto somente de memória para desenvolvimento local. Substitua "My Project" pelo nome do seu projeto :

agentengine create --memory-only --name "My Project"

O comando grava um arquivo project-config.yaml que define memory_only como true e especifica o esquema de configuração de memória.

Esse comando não gera um arquivo agent.yaml, um diretório agents/ ou código de tempo de execução do agente . Você não pode combinar o sinalizador --memory-only com os sinalizadores --template, --llm, --memory ou --open-egress.

Configure variáveis de ambiente.

Crie um arquivo .env no seu diretório de projeto e, em seguida, defina as seguintes variáveis no arquivo:

• VOYAGE_API_KEY: necessário para incorporações do Voyage AI

• Chave do provedor LLM, como ANTHROPIC_API_KEY: necessária se a extração em segundo plano estiver ativada em project-config.yaml

Você não precisa definir a variável MONGODB_URI. O comando agentengine dev up provisiona e conecta automaticamente ao container MongoDB local agrupado. Se você quiser usar uma instância externa do MongoDB , defina esta variável.

Inicie a pilha local.

No diretório do projeto , execute o seguinte comando para iniciar a pilha de memória local:

agentengine dev up

Para um projeto somente de memória, este comando inicia somente os seguintes containers:

• mongodb: Uma instância MongoDB compatível com Atlas local

• memory-server: O serviço de tempo de execução da memória

• oe: O proxy do Mecanismo de Orquestração local pelo qual o SDK se conecta

A saída do comando inclui as URLs para os serviços locais oe e memory-server. Copie a URL oe para usar em uma etapa futura.

Use os seguintes comandos para gerenciar a pilha local:

Instale o pacoteagentic-platform-memory .

Execute o seguinte comando para instalar o pacoteagentic-platform-memory :

pip install agentic-platform-memory

Conecte o SDK à pilha local.

Navegue até o diretório do aplicação Python. Este diretório pode ser separado do diretório do projeto que você criou na primeira etapa.

Em seguida, conecte-se à pilha local adicionando o seguinte código ao seu aplicação. Substitua http://localhost:<oe-port> pela URL que você copiou da saída do comando agentengine dev up.

from agentic_platform_memory import Memory, MemoryRequestContext
# Set the base_url to the local oe URL printed by "agentengine dev up".
memory = Memory(base_url="http://localhost:<oe-port>")
# Bind conversation identity.
session = memory.bind(
    MemoryRequestContext(
        user_id="user_123",
        session_id="session_456",
    )
)
# Record a turn.
session.record_turn(role="user", content="I prefer window seats on flights.")
# Build context.
context = session.build_context(
    query="What seat preferences are known?",
    enabled_sources={"stm", "semantic", "episodic"},
)
print(context.formatted_context)