Adicionar memória ao seu agente

Crie uma pasta de espaço de trabalho dentro da raiz do projeto .

O exemplo seguinte cria uma pasta denominada my-workspace:

mkdir my-workspace

Mova seus arquivos do workspace para a nova pasta.

Execute os seguintes comandos para mover o arquivo agent.yaml, seus arquivos de origem do agente e o arquivo .env para a pasta do espaço de trabalho:

mv agent.yaml my-workspace/
mv .env my-workspace/

Crie um arquivo project-config.yaml na raiz do projeto .

O seguinte arquivo de amostra project-config.yaml mostra a configuração da seção memory::

memory:
  log_level: info
  voyage:
    model: "voyage-4-large"
    dimension: 1024
  short_term:
    embed_on_write: false
  extraction_llm:
    provider: openai
    model: null
    base_url: null
    api_key_secret: null

Confirme a estrutura atualizada.

Confirme que seu projeto corresponde à seguinte estrutura:

my-project/
├── project-config.yaml
└── my-workspace/
    └── agent.yaml

Inicie o ambiente local.

Execute o seguinte comando a partir da raiz do projeto:

agentengine dev up

Edite o bloco memory: no seu arquivo project-config.yaml.

Abra o project-config.yaml na raiz do projeto e defina as configurações de memória. Para visualizar as opções disponíveis, consulte Estrutura do projeto para memória.

Carregue os segredos necessários.

Execute os seguintes comandos para carregar os segredos e inclua o sinalizador --project-scope para segmentar segredos com escopo de projeto:

agentengine secret set VOYAGE_API_KEY --project-scope
agentengine secret set LLM_API_KEY --project-scope

Se você montou seu projeto com o comando agentic create --llm <provider> --memory e selecionou um provedor de LLM compatível, a CLI já adicionou extraction_llm.api_key_secret: LLM_API_KEY ao seu arquivo project-config.yaml. Este é o mesmo nome secreto que o arquivo .env do seu agente usa, portanto, carregá-lo uma vez fornece a chave para o agente e a extração da memória.

Armazene a configuração de memória.

Na raiz do projeto , execute o seguinte comando para carregar o bloco memory: do seu arquivo project-config.yaml para o Atlas Agent Engine:

agentengine memory configure

Implemente o agente.

Execute o seguinte comando para distribuir o agente e provisionar o servidor de memória :

agentengine deploy

O comando deployment sincroniza a configuração de memória pendente e provisiona o servidor de memória como parte do tempo de execução do projeto .

Edite o bloco memory: em seu arquivo project-config.yaml com suas novas configurações de memória.

Abra o project-config.yaml na raiz do projeto e defina as configurações de memória. Para visualizar as opções disponíveis, consulte Estrutura do projeto para memória.

Armazene a configuração atualizada.

Execute o seguinte comando a partir da raiz do seu projeto :

agentengine memory configure

Aplique a configuração.

agentengine memory apply

O comando agentengine memory apply reinicia o servidor de memória para que ele registre a nova configuração. A plataforma oferece alterações de configuração de forma assíncrona e as alterações entram em vigor quando o pod é reiniciado ou quando a configuração atualizada é aplicada na inicialização. Se a configuração armazenada ainda não estiver sincronizada, o comando agentengine deploy sincroniza a configuração como parte do próximo processo de sistema.

Declare seus tipos personalizados.

Adicione um bloco custom_memory_types: na seção memory: do seu arquivo project-config.yaml. O exemplo a seguir cria um tipo de customer_profile personalizado:

memory:
  custom_memory_types:           # Custom memory types (max 5)
    - name: customer_profile
      collection: profiles
      tags:
        - name: location
        - name: tier
        - name: profile.location  # One level of nested tag keys

Cada tipo de memória personalizado tem os seguintes campos:

• name: (obrigatório) o nome do tipo. O valor deve começar com uma letra minúscula e conter apenas letras minúsculas, números e sublinhados. Ele não pode usar nenhum dos nomes de tipo internos ou exceder 64 caracteres de comprimento.

• collection: (Obrigatório) A collection no banco de dados de memória do projeto que armazena os registros do tipo.

• tags: (Opcional) Chaves de tag filtráveis, até dez por tipo. Uma chave de tag pode usar notação de ponto para aninhar até um nível, como profile.location. Os valores da tag devem ser strings não vazias, números ou booleanos.

Provisione os novos tipos.

Execute os seguintes comandos para carregar a configuração atualizada e aplicá-la ao servidor de memória , que provisiona cada novo tipo:

agentengine memory configure
agentengine memory apply

Leia e grave registros de memória personalizados.

Em seu aplicação, use os métodos save() e retrieve() para escrever e ler registros de memória personalizados:

memory.save(
    memory_type="customer_profile",
    content="Prefers direct vendor onboarding contact.",
    tags={"tier": "gold"},
)
hits = memory.retrieve(
    memory_type="customer_profile",
    query="How should we onboard this customer?",
    tags={"tier": "gold"},
    top_k=5,
)