Pipelines de memória do agente

Importante

Este recurso está em versão Beta.

Um pipeline de memória constrói memória de longo prazo a partir das conversas passadas do seu agente. Lê o histórico de conversas de um armazenamento de sessões e destila memórias de longo prazo, como factos, preferências e procedimentos, num armazenamento de memórias. O teu agente depois recorda essas memórias em conversas posteriores da mesma forma que recorda memórias que guardou ele próprio.

Um agente que guarda memórias durante uma conversa escreve-as uma conversa de cada vez, apenas com o contexto dessa conversa. Ao longo de muitas conversas, a sua memória recolhe entradas sobrepostas e contraditórias, e factos que o agente não pensou em guardar não chegam à memória. Um pipeline de memória funciona depois do facto, com todas as conversas e memória existente de um ator à vista, para poder capturar o que o agente perdeu e manter a memória consolidada.

Utilize um pipeline de memória quando quiser:

  • Construa memória de longo prazo a partir das conversas sem adicionar ferramentas de escrita de memória ao seu agente.
  • Preenche 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, fundindo entradas sobrepostas e dividindo entradas sobredimensionadas.

Pode usar um pipeline de memória sozinho ou juntamente com ferramentas de memória que o seu agente chama durante uma conversa.

Note

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

Requirements

  • Um armazenamento de sessões 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 na base de dados do armazenamento de memória. As execuções de pipeline usam essa identidade.
  • Permissão para consultar o modelo que o pipeline utiliza para destilação. Sem ele, as execuções do pipeline falham.
  • Para usar a CLI, instale databricks-agentbricks versão 0.6.0 e superior. Também pode chamar a API REST diretamente a partir de qualquer linguagem de programação.

Como funcionam os pipelines da memória

Uma canalização de memória é um recurso de memória de agente que liga um armazenamento de sessão a um único armazenamento de memória. Não está relacionado com os pipelines Lakeflow. Um armazenamento de sessões pode alimentar mais do que um armazenamento de memória, mas cada par de armazenamento de sessões e armazenamento de memória pode ter apenas um pipeline.

  • Chamadas de modelo através do Unity Gateway: O pipeline chama o seu modelo de destilação através do Unity Gateway.
  • A sua escolha de modelo: Escolhe o modelo quando cria um pipeline e pode alterá-lo mais tarde. Se não escolheres um, o pipeline usa um modelo predefinido.
  • Execuções manuais ou agendadas em computação serverless: Inicia as execuções ou configura o pipeline para correr num horário de cerca de 24 em 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:

  1. Destilar: O pipeline lê as novas conversas do ator e usa um LLM para extrair factos duradouros delas.
  2. Fusão: O pipeline desduplica os novos factos e funde-os em entradas de memória baseadas em tópicos sob o mesmo actor_id no armazenamento de memória.
  3. Manutenção: O pipeline reorganiza a memória do ator. Ela funde entradas que se sobrepõem e divide as entradas que ficam demasiado grandes.

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, por isso a primeira execução processa todo o histórico do ator. Se uma execução falhar para um ator, continua com os outros atores, e na execução seguinte tenta novamente o ator falhado no seu ponto de controlo.

O/A actor_id liga as duas lojas. Um pipeline processa apenas os atores que têm sessões na loja de sessões e escreve as memórias de cada ator sob o mesmo actor_id que as sessões do ator utilizam. Por predefinição, um pipeline só é executado quando iniciar uma execução. Também podes executá-lo de forma agendada.

Note

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

O que um pipeline retém

Um pipeline extrai factos individuais e duradouros das conversas. Foi concebido para manter:

  • Factos que o utilizador declara explicitamente e preferências que expressa, sem inferir para além do que a conversa diz.
  • Correções e feedback explícito, como qual fonte usar para os valores de receita.
  • Conhecimento duradouro do domínio, como fontes autoritativas, definições métricas, terminologia e convenções de equipa, bem como fluxos de trabalho e projetos em curso.

Foi concebido para ignorar:

  • Valores provenientes de fontes ativas que mudam ao longo do tempo, como a contagem atual de linhas de uma tabela. Regista como encontrar ou calcular o valor em vez.
  • Detalhes que o agente pode consultar com as suas ferramentas, como o esquema de uma tabela.
  • Segredos, como palavras-passe, chaves API e tokens.

Introdução

Estes 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 o seu resultado. Identifique cada loja pelo seu ID, pelo identificador que escolheu ao criar a loja, ou pelo nome do seu recurso, como memory-stores/support-agent-memory. Escolha o cliente que se encaixe no seu projeto.

Agente Bricks

O Agent Bricks CLI utiliza o seu perfil guardado da CLI Databricks para autenticar.

  1. Instale a CLI do Agent Bricks, ou atualize-a para a 0.6.0 e superior:

    pip install --upgrade databricks-agentbricks

  2. Crie um pipeline que condense o support-agent-sessions armazenamento de sessão no support-agent-memory armazenamento de memória. --model é opcional. Se o omitir, 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 devolve o nome do recurso do pipeline, na forma memory-pipelines/<pipeline-id>.

  3. Inicie uma execução do pipeline:

    agentbricks memory pipeline run <pipeline-id>

    O comando devolve o nome do recurso do run, na forma memory-pipelines/<pipeline-id>/runs/<run-id>, e o seu estado RUNNING.

  4. A CLI não reporta o resultado de uma execução. Para verificar, defina DATABRICKS_HOST como o nome de 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 através de /api/2.0/agents/memory-pipelines. Chame-o diretamente de qualquer língua.

  1. Gerar um token de OAuth com a CLI do Databricks:

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

  2. Crie um pipeline que destile memórias de support-agent-sessions e as guarde em support-agent-memory. dreamer_policy.model é opcional. Se o omitir, 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 resposta name contém o nome do recurso do pipeline, na forma memory-pipelines/<pipeline-id>.

  3. 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 name da resposta contém o nome do recurso da execução, na forma memory-pipelines/<pipeline-id>/runs/<run-id>.

  4. Veja 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}"

Depois de uma execução ser bem-sucedida, o seu agente pode aceder às novas memórias com as operações de listagem e pesquisa do armazenamento de memórias. Consulte a memória do agente.

Monitorizar Execução de Pipeline

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

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

Orientar a destilação com instruções

As instruções dizem ao pipeline o que manter e como organizá-lo. O pipeline aplica-os em todas as fases. Use-os para orientação de alto nível, como:

  • Os temas em que se deve focar, como as preferências dos clientes e os detalhes da conta.
  • O conteúdo a ignorar, como passos pontuais de resoluçã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. Não renomeia entradas existentes para corresponder a 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 com instruções.

Podes definir instruções quando crias um pipeline e alterá-las mais tarde. A próxima execução usa as novas instruções.

Agente Bricks

Para definir instruções quando 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 a partir de um ficheiro 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 as suas definiçõ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."}}'

Executar um pipeline de forma agendada

Um pipeline programado é executado automaticamente cerca de 24 em 24 horas. Podes definir o gatilho quando criares um pipeline, ou alterá-lo mais tarde. O agendador escolhe quando começa a primeira execução agendada. Para resumir imediatamente as conversas existentes, inicie uma execução manualmente.

Agente Bricks

Para criar um pipeline agendado, 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 tiver 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"}}'

Também podes iniciar manualmente uma execução de um pipeline agendado, desde que não haja outra execução em curso.

Gerir canalizações

Os seguintes comandos listam, inspecionam, atualizam e eliminam pipelines. Cada comando CLI aceita ou o ID do pipeline ou o 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
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, dreamer_policy.model, dreamer_policy.trigger, ou dreamer_policy.instructions
Eliminar um pipeline agentbricks memory pipeline delete <pipeline-id> DELETE /api/2.0/agents/memory-pipelines/<pipeline-id>

Se não definires um nome a apresentar, o pipeline recebe um com base nos nomes dos seus armazenamentos de sessão e de memória. Para repor um pipeline no modelo padrão, atualize o seu modelo para um valor vazio, como --model "". Alterações no modelo e nas instruções aplicam-se à execução seguinte.

Eliminar um pipeline elimina a sua tarefa subjacente e impede futuras execuções. Uma execução já em curso continua até à conclusão. As entradas de memória que o pipeline já escreveu permanecem no armazenamento de memória.

Limitations

  • O armazenamento de sessões e o armazenamento de memória ficam definidos quando crias um pipeline. Para alterar qualquer um deles, apague o pipeline e crie um novo. Um novo pipeline não reutiliza os checkpoints do pipeline antigo, por isso a sua primeira execução processa o histórico completo de cada ator, mesmo para o mesmo par de stores.
  • Se um pipeline já liga o mesmo armazenamento de sessão e armazenamento de memória, criar outro falha com ALREADY_EXISTS.
  • Um pipeline tem uma execução em curso de cada vez. Iniciar uma execução enquanto outra está em curso falha com um erro ABORTED.
  • As canalizações programadas são executadas aproximadamente a cada 24 horas. Não podes definir um intervalo diferente ou um cron schedule.
  • Um pipeline processa apenas os atores que têm 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 de ator UUID, a execução falha. O limite é de 48 KiB de IDs de atores serializados, por isso IDs mais curtos permitem mais atores.

Recursos adicionais

  • Última atualização a