Pipelines de memória dos agentes

Importante

Esse recurso está em Beta.

Um pipeline de memória constrói memória de longo prazo a partir das conversas passadas do seu agente. Ele lê o histórico de conversas de um armazenamento de sessões e destila memórias de longo prazo, como fatos, preferências e procedimentos, em um armazenamento de memórias. Seu agente então recorda essas memórias em conversas posteriores, da mesma forma que recorda as memórias que salvou a si mesmo.

Um agente que salva memórias durante uma conversa as escreve uma conversa de cada vez, com apenas o contexto dessa conversa. Ao longo de muitas conversas, sua memória coleta entradas sobrepostas e conflitantes, e fatos que o agente não pensou em salvar não chegam à memória. Um pipeline de memória funciona depois do fato, com todas as conversas e memória existente de um ator à vista, para capturar o que o agente deixou passar e manter a memória consolidada.

Use o pipeline de memória quando quiser:

Construa memória de longo prazo a partir das conversas sem adicionar ferramentas de gravação de memória ao seu agente.
Preenche retroativamente a memória a partir do histórico de conversas que um armazenamento de sessões já guarda.
Mantenha a memória organizada ao longo do tempo, mesclando entradas sobrepostas e dividindo as de grande tamanho.

Você pode usar um pipeline de memória sozinho ou junto com ferramentas de memória que seu agente chama durante uma conversa.

Note

As execuções do pipeline de memória utilizam preços gerais de computação serverless para o trabalho e preços Foundation Model Serving para chamadas de modelo.

Requirements

Um armazenamento de sessão que guarda as conversas do seu agente e um armazenamento de memórias para escrever memórias.
Acesso a ambos os armazenamentos para a identidade que cria o pipeline, incluindo permissão para criar tabelas no banco de dados do armazenamento de memória. Execuções de pipeline usam essa identidade.
Permissão para consultar o modelo que o pipeline usa para destilação. Sem ele, as execuções do pipeline falham.
Para usar a CLI, instale databricks-agentbricks 0.6.0 e posterior. Você também pode chamar a API REST diretamente em qualquer linguagem de programação.

Como funcionam os pipelines de memória

Um pipeline de memória é um recurso de memória de agente que conecta um armazenamento de sessão a um único armazenamento de memória. Não está relacionado aos pipelines do Lakeflow. Um armazenamento de sessão pode alimentar mais de um armazenamento de memória, mas cada par de armazenamento de sessão e armazenamento de memória pode ter apenas um pipeline.

Chamadas de modelo por meio do Unity Gateway: O pipeline chama seu modelo de destilação por meio do Unity Gateway.
Sua escolha de modelo: Você escolhe o modelo ao criar um pipeline e pode mudá-lo depois. Se você não escolher um, o pipeline usa um modelo padrão.
Execuções manuais ou programadas em computação serverless: Você inicia as execuções por conta própria, ou configura o pipeline para rodar em um cronograma aproximadamente a cada 24 horas. De qualquer forma, cada execução é executada como um trabalho em computação serverless, usando a identidade que criou o pipeline.

Cada execução do pipeline processa cada ator no armazenamento de sessão separadamente:

Destilar: O pipeline lê as novas conversas do ator e usa um LLM para extrair fatos duradouros delas.
Mesclagem: O pipeline desduplica os novos fatos e os mescla em entradas de memória baseadas em tópicos na mesma actor_id no armazenamento de memória.
Mantenha: O pipeline reorganiza a memória do ator. Ela funde entradas que se sobrepõem e divide entradas que crescem demais.

As execuções do pipeline de memória mantêm um checkpoint para cada ID de ator. Uma execução processa todas as sessões de um ator desde a última execução bem-sucedida desse ator, então a primeira execução processa todo o histórico do ator. Se uma execução falhar para um ator, ela continua com os outros atores, e a próxima tenta novamente o ator falhado a partir do ponto de verificação.

O actor_id conecta as duas lojas. Um pipeline processa apenas atores que têm sessões no armazenamento de sessões, e ele grava as memórias de cada ator sob o mesmo actor_id que as sessões do ator usam. Por padrão, um pipeline roda apenas quando você inicia uma execução. Você também pode executá-lo de forma agendada.

Note

A manutenção se aplica a todas as entradas de memória de um ator, incluindo entradas que seu agente salvou diretamente. Um pipeline pode reescrever, mesclar, dividir ou excluir qualquer entrada em um actor_id que ele processa.

O que um pipeline mantém

Um pipeline extrai fatos individuais e duradouros das conversas. Ele foi projetado para manter:

Fatos que o usuário declara explicitamente e preferências que expressa, sem inferir além do que a conversa diz.
Correções e feedback explícito, como qual fonte usar para obter os números de receita.
Conhecimento duradouro do domínio, como fontes autoritativas, definições de métricas, terminologia e convenções de equipe, além de fluxos de trabalho e projetos em andamento.

Ele foi projetado para ignorar:

Valores de fontes em tempo real que mudam ao longo do tempo, como a contagem atual de linhas de uma tabela. Ele registra como encontrar ou calcular o valor em vez disso.
Detalhes que o agente pode consultar com suas ferramentas, como o esquema de uma tabela.
Segredos, como senhas, chaves API e tokens.

Introdução

Esses exemplos criam um pipeline de memória para a sessão e os armazenamentos de memória de um agente de suporte, iniciam uma execução e verificam seu resultado. Identifique cada loja pelo seu ID, pelo identificador escolhido ao criar a loja ou pelo nome do recurso, como memory-stores/support-agent-memory. Escolha o cliente que se encaixe no seu projeto.

Bricks do Agente

O Agent Bricks CLI usa seu perfil salvo do Databricks CLI para autenticar.

Instale a CLI do Agent Bricks ou atualize-a para a versão 0.6.0 ou superior:
```
pip install --upgrade databricks-agentbricks
```
Crie um pipeline que condense o armazenamento de sessão support-agent-sessions no armazenamento de memória support-agent-memory --model é opcional. Se você omiti-la, o pipeline usa um modelo padrão:
```
agentbricks memory pipeline create \
  --session-store support-agent-sessions \
  --memory-store support-agent-memory \
  --model system.ai.claude-sonnet-5
```
O comando retorna o nome do recurso do pipeline, na forma memory-pipelines/<pipeline-id>.
Inicie uma execução do pipeline:
```
agentbricks memory pipeline run <pipeline-id>
```
O comando retorna o nome do recurso da execução, na forma memory-pipelines/<pipeline-id>/runs/<run-id>, e seu RUNNING estado.

O CLI não reporta o resultado de uma execução. Para verificar, defina DATABRICKS_HOST como o nome do host do seu espaço de trabalho, gere um token OAuth e chame a API REST:

export DATABRICKS_TOKEN=$(databricks auth token --profile <profile> | jq -r .access_token)
curl "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines/<pipeline-id>/runs/<run-id>" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

API REST

A CLI chama a API REST por baixo de /api/2.0/agents/memory-pipelines. Chamá-lo diretamente de qualquer linguagem.

Gerar um token OAuth com a CLI do Databricks:

databricks auth login --host ${DATABRICKS_HOST}
export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)

Crie um pipeline que destile memórias de support-agent-sessions e as salve em support-agent-memory. dreamer_policy.model é opcional. Se você omiti-la, o pipeline usa um modelo padrão:

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"session_store": "support-agent-sessions", "memory_store": "support-agent-memory", "dreamer_policy": {"model": "system.ai.claude-sonnet-5"}}'

O campo da name resposta contém o nome do recurso do pipeline, na forma memory-pipelines/<pipeline-id>.

Inicie uma execução do pipeline:

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines/<pipeline-id>/run" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{}'

O campo da name resposta contém o nome do recurso da execução, na forma memory-pipelines/<pipeline-id>/runs/<run-id>.

Confira o resultado da execução:

curl "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines/<pipeline-id>/runs/<run-id>" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Após uma execução bem-sucedida, seu agente pode consultar as novas memórias com as operações de listagem e busca do armazenamento de memória. Consulte Memória do agente.

Monitorar execuções de pipeline

O state de uma execução é um dos seguintes:

State	Meaning
`RUNNING`	A execução está pendente ou em andamento.
`SUCCEEDED`	A execução processou todos os atores com sucesso.
`FAILED`	A execução terminou com um erro para um ou mais atores. O `error` campo descreve a falha.
`CANCELLED`	A execução foi cancelada antes de ser concluída.

Orientar a destilação com instruções

Instruções dizem ao pipeline o que manter e como organizá-lo. Pipeline aplica isso em todas as etapas. Utilize-os para orientações de alto nível, como:

Os tópicos a serem focados, como preferências dos clientes e detalhes da conta.
O conteúdo a ser pulado, como etapas pontuais de solução de problemas.
Os caminhos sob os quais organizar as entradas.

Sem instruções de layout, o pipeline segue o layout das entradas existentes da loja ou deriva um layout baseado em tópicos quando a loja está vazia. Ele não renomeia entradas existentes para combinar com um novo layout. Para alterar uma entrada específica, edite-a com a operação de atualização do armazenamento de memória em vez de usar instruções.

Você pode definir instruções ao criar um pipeline e alterá-las depois. A próxima execução usa as novas instruções.

Bricks do Agente

Para definir instruções ao criar um pipeline, passe --instructions:

agentbricks memory pipeline create \
  --session-store support-agent-sessions \
  --memory-store support-agent-memory \
  --instructions "Focus on durable customer preferences and account details. Ignore one-off troubleshooting steps. Organize entries under /preferences/ and /account/."

Para carregar instruções mais longas de um arquivo UTF-8, passe --instructions @<path-to-file> em vez disso.

Para alterar as instruções de um pipeline existente, execute o seguinte:

agentbricks memory pipeline update <pipeline-id> \
  --instructions "Keep only durable customer preferences."

API REST

Na API REST, o objeto dreamer_policy de um pipeline mantém suas configurações de destilação: instructions, trigger e model. Para definir instruções ao criar um pipeline, inclua-as em dreamer_policy.instructions:

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"session_store": "support-agent-sessions", "memory_store": "support-agent-memory", "dreamer_policy": {"instructions": "Focus on durable customer preferences and account details. Ignore one-off troubleshooting steps. Organize entries under /preferences/ and /account/."}}'

Para alterar as instruções de um pipeline existente, atualize dreamer_policy.instructions:

curl -X PATCH "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines/<pipeline-id>?update_mask=dreamer_policy.instructions" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"dreamer_policy": {"instructions": "Keep only durable customer preferences."}}'

Execute um pipeline de forma agendada

Um pipeline agendado roda automaticamente a cada 24 horas. Você pode definir o gatilho ao criar um pipeline, ou mudá-lo depois. O escalonador escolhe quando a primeira execução agendada começa. Para resumir as conversas anteriores imediatamente, comece uma execução manualmente.

Bricks do Agente

Para criar um pipeline programado, passe --trigger scheduled. O padrão é --trigger manual:

agentbricks memory pipeline create \
  --session-store support-agent-sessions \
  --memory-store support-agent-memory \
  --trigger scheduled

Para alterar o gatilho de um pipeline existente, execute o seguinte:

agentbricks memory pipeline update <pipeline-id> --trigger scheduled

Se você tem um pipeline agendado, pode pausá-lo:

agentbricks memory pipeline pause <pipeline-id>

Para reiniciar as execuções agendadas, retome-a:

agentbricks memory pipeline resume <pipeline-id>

API REST

Para criar um pipeline agendado, defina dreamer_policy.trigger para SCHEDULED:

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"session_store": "support-agent-sessions", "memory_store": "support-agent-memory", "dreamer_policy": {"trigger": "SCHEDULED"}}'

Para alterar o gatilho de um pipeline existente, atualize dreamer_policy.trigger para SCHEDULED ou MANUAL_ONLY:

curl -X PATCH "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines/<pipeline-id>?update_mask=dreamer_policy.trigger" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"dreamer_policy": {"trigger": "SCHEDULED"}}'

Você também pode iniciar manualmente uma execução de um pipeline agendado, desde que nenhuma outra execução esteja em andamento.

Gerenciar pipelines

Os seguintes comandos listam, inspecionam, atualizam e excluem pipelines. Cada comando CLI aceita ou o ID do pipeline ou seu nome completo do recurso memory-pipelines/<pipeline-id>.

Tarefa	CLI do Agente Bricks	API REST
Listar pipelines	`agentbricks memory pipeline list`	`GET /api/2.0/agents/memory-pipelines`
Obtenha um pipeline	`agentbricks memory pipeline get <pipeline-id>`	`GET /api/2.0/agents/memory-pipelines/<pipeline-id>`
Atualizar um pipeline	`agentbricks memory pipeline update <pipeline-id>` com `--display-name`, `--model`, `--trigger`, ou `--instructions`	`PATCH /api/2.0/agents/memory-pipelines/<pipeline-id>` com um `update_mask` de `display_name`, `dreamer_policy.model`, `dreamer_policy.trigger`, ou `dreamer_policy.instructions`
Excluir um pipeline	`agentbricks memory pipeline delete <pipeline-id>`	`DELETE /api/2.0/agents/memory-pipelines/<pipeline-id>`

Se você não definir um nome de exibição, o pipeline recebe um baseado nos nomes do armazenamento de sessão e do armazenamento de memória. Para voltar um pipeline ao modelo padrão, atualize seu modelo para um valor vazio, como --model "". Mudanças no modelo e nas instruções se aplicam à próxima execução.

Deletar um pipeline elimina o job associado e interrompe execuções futuras. Uma sequência que já está em andamento continua até o fim. Entradas de memória que o pipeline já escreveu permanecem no armazenamento de memória.

Limitações

O armazenamento de sessão e o armazenamento de memória são corrigidos quando você cria um pipeline. Para mudar qualquer um deles, exclua o pipeline e crie um novo. Um novo pipeline não reutiliza os checkpoints do pipeline antigo, então sua primeira execução processa o histórico completo de cada ator, mesmo para o mesmo par de stores.
Se um pipeline já conecta o mesmo armazenamento de sessão e armazenamento de memória, criar outro falha com ALREADY_EXISTS.
Um pipeline tem uma execução em andamento por vez. Iniciar uma execução enquanto outra está em andamento resulta em um erro ABORTED.
Pipelines programados rodam a cada 24 horas. Você não pode definir um intervalo diferente ou um agendamento cron.
Um pipeline processa apenas atores que possuem sessões na loja de sessões. As entradas de memória para atores sem sessões permanecem inalteradas.
Se o armazenamento de sessões tiver mais de cerca de 1.200 atores com IDs UUID de ator, a execução falha. O limite é de 48 KiB de IDs de atores serializados, então IDs mais curtos permitem mais atores.

Recursos adicionais

Comentários

Esta página foi útil?

Última atualização em 2026-10-17