Pular para o conteúdo principal
Última atualização em

Pipelines de memória do agente

info

Beta

Esse recurso está na versão Beta.

Um pipeline de memória cria memória de longo prazo a partir das conversas anteriores do seu agente. Ele lê a história de conversas de um repositório de sessão e destila memórias de longo prazo, como fatos, preferências e procedimentos, em um repositório de memória. Seu agente então recupera essas memórias em conversas posteriores da mesma forma que recupera as memórias que ele próprio salvou.

Um agente que salva memórias durante uma conversa as registra uma conversa por vez, usando apenas o contexto dessa conversa. Ao longo de muitas conversas, sua memória acumula 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 posteriormente, com todas as conversas de um ator e a memória existente em view, para que possa capturar o que o agente deixou passar e manter a memória consolidada.

Use um pipeline de memória quando quiser:

  • Crie memória de longo prazo a partir de conversas sem adicionar ferramentas de gravação de memória ao seu agente.
  • Preencha retroativamente a memória com base no história da conversa que um armazenamento de sessão já mantém.
  • Mantenha a memória organizada ao longo do tempo mesclando entradas sobrepostas e dividindo as que forem grandes demais.

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

nota

As execuções de pipeline de memória usam os preços de compute geral Serverless para o Job e os preços do Model Serving de modelos básicos para chamadas de modelo.

Requisitos​

  • Um repositório de sessões que armazena as conversas do seu agente e um repositório de memória para gravar 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 em memória. As execuções do pipeline usam essa identidade.
  • Permissão para query o modelo que o pipeline usa para destilação.
  • Para usar a CLI, instale databricks-agentbricks 0.5.0 ou acima. Também é possível chamar a API REST diretamente de qualquer linguagem.

Como funcionam os pipelines de memória​

Um pipeline de memória é um recurso de memória de agente que conecta um repositório de sessões a um repositório de memória. Não está relacionado ao LakeFlow Pipelines. Um repositório de sessões pode alimentar mais de um repositório de memória, mas cada par de repositório de sessões e repositório de memória pode ter apenas um pipeline.

  • Chamadas de modelo pelo Unity Gateway: o pipeline chama seu modelo de destilação pelo Unity Gateway.
  • Sua escolha de modelo: Você escolhe o modelo ao criar um pipeline e pode alterá-lo posteriormente. Se você não escolher um, o pipeline usará um modelo default.
  • Execuções manuais ou programadas em compute Serverless: Você começa as execuções por conta própria ou configura o pipeline para ser executado em uma programação com intervalos de aproximadamente 24 horas. De qualquer forma, cada execução ocorre como um job em compute Serverless, usando a identidade que criou o pipeline.

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

  1. Destilar: O pipeline lê as novas conversas do ator e usa um LLM para extrair delas fatos duradouros.
  2. Merge: O pipeline elimina duplicatas dos novos fatos e faz merge deles em entradas de memória baseadas em tópicos sob o mesmo actor_id no armazenamento de memória.
  3. Manter: O pipeline reorganiza a memória do ator. Ele faz merge das entradas que se sobrepõem e divide as entradas que ficam grandes 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, portanto, a primeira execução processa toda a história do ator. Se uma execução falhar para um ator, ela continuará com os outros atores, e a próxima execução tentará novamente o ator com falha a partir do checkpoint.

O actor_id Link os dois armazenamentos. Um pipeline processa apenas os atores que têm sessões no armazenamento de sessões e grava as memórias de cada ator sob o mesmo actor_id usado pelas sessões do ator. Por default, um pipeline só é executado quando você começa uma execução. Você também pode programá-lo para execução.

nota

A manutenção se aplica a todas as entradas de memória de um ator, incluindo as entradas que seu agente salvou diretamente. Um pipeline pode reescrever, fazer merge, dividir ou excluir qualquer entrada em um actor_id que 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 os valores de receita.
  • Conhecimento de domínio duradouro, como fontes autorizadas, definições de métricas, terminologia e convenções da equipe, bem como fluxos de trabalho e projetos em andamento.

Ele foi projetado para ignorar:

  • Valores de fontes ativas que mudam ao longo do tempo, como a contagem atual de linhas de uma tabela. Em vez disso, ele registra como encontrar ou compute o valor.
  • Detalhes que o agente pode consultar com suas ferramentas, como o esquema de uma tabela.
  • Segredos, como senhas, key de API e tokens.

começar​

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

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

  1. Instale a CLI do Agent Bricks ou atualize-a para a versão 0.5.0 ou acima:

    Bash
    pip install --upgrade databricks-agentbricks

  2. Crie um pipeline que destila o armazenamento de sessão support-agent-sessions no armazenamento de memória support-agent-memory. --model é opcional. Se você omitir, o pipeline usará um modelo default:

    Bash
    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, no formato memory-pipelines/<pipeline-id>.

  3. Comece uma execução do pipeline:

    Bash
    agentbricks memory pipeline run <pipeline-id>

    O comando retorna o nome do recurso da execução, no formato memory-pipelines/<pipeline-id>/runs/<run-id>, e seu estado RUNNING.

  4. A CLI não informa o resultado de uma execução. Para verificar isso, defina DATABRICKS_HOST como o hostname do seu workspace, gere um token OAuth e chame a API REST:

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

Após a execução ser bem-sucedida, o agente pode recuperar as novas memórias com as operações de lista e pesquisa do armazenamento de memória. Veja Memória do agente.

Monitorar execuções do pipeline​

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

Status

Significado

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 campo error descreve a falha.

CANCELLED

A execução foi cancelada antes de ser concluída.

Status

Significado

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 campo error descreve a falha.

CANCELLED

A execução foi cancelada antes de ser concluída.

Oriente a destilação com instruções​

As instruções informam ao pipeline o que manter e como organizar. O pipeline as aplica em cada estágio. Use-as como orientações de alto nível, como:

  • Os tópicos em que se concentrar, como preferências dos clientes e detalhes da account.
  • O conteúdo a ser ignorado, como os passos pontuais de solução de problemas.
  • Os caminhos sob os quais organizar as entradas.

Sem instruções de disposição, o pipeline segue a disposição das entradas existentes do armazenamento ou deriva uma disposição baseada em tópicos quando o armazenamento está vazio. Ele não renomeia as entradas existentes para corresponder a uma nova disposição. Para alterar uma entrada específica, edite-a usando 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 posteriormente. A próxima execução usa as novas instruções.

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

Bash
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:

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

execução um pipeline de forma programar​

Um pipeline programado faz uma execução automaticamente a cada 24 horas, aproximadamente. Você pode definir o Trigger ao criar um pipeline ou alterá-lo posteriormente. O programador escolhe quando começa a primeira execução programada. Para destilar conversas existentes imediatamente, começar uma execução manualmente.

Para criar um pipeline agendado, passe --trigger scheduled. O default é --trigger manual:

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

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

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

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

Gerenciar pipelines​

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

Tarefa

CLI do Agent Bricks

API REST

Listar pipelines

agentbricks memory pipeline list

GET /api/2.0/agents/memory-pipelines

Obter 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, 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>

Tarefa

CLI do Agent Bricks

API REST

Listar pipelines

agentbricks memory pipeline list

GET /api/2.0/agents/memory-pipelines

Obter 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, 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 receberá um com base nos nomes do armazenamento de sessão e do armazenamento de memória. Para voltar ao modelo default, atualize o modelo do pipeline para um valor vazio, como --model "". As alterações no modelo e nas instruções serão aplicadas à próxima execução.

Excluir um pipeline exclui o job subjacente e interrompe as execuções futuras. Uma execução que já está em andamento continua até ser concluída. As entradas de memória que o pipeline já gravou permanecem no armazenamento de memória.

Limitações​

  • O armazenamento de sessão e o armazenamento de memória são fixos quando você cria um pipeline. Para alterar qualquer um deles, exclua o pipeline e crie um novo.
  • Se um pipeline já conecta o mesmo armazenamento de sessão e o mesmo armazenamento de memória, a criação de outro falha com ALREADY_EXISTS.
  • Um pipeline só pode ter uma execução em andamento por vez. Iniciar uma execução enquanto outra está em andamento resulta em um erro ABORTED.
  • Os pipelines programados têm execução aproximadamente a cada 24 horas. Não é possível definir um intervalo diferente nem programar cron.
  • Um pipeline processa apenas atores que têm sessões no armazenamento de sessões. As entradas de memória de atores sem sessões permanecem inalteradas.
  • Se o armazenamento de sessões tiver mais de aproximadamente 1.200 atores com IDs de ator UUID, a execução falhará. O limite é de 48 KiB de IDs de ator serializados, portanto IDs mais curtos permitem mais atores.

Outros recursos​

Nesta página