智能体记忆管道

Important

此功能在 Beta 版中。

记忆管道会根据智能体过去的对话构建长期记忆。 它读取 会话存储中的对话历史,并将长期记忆(如事实、偏好和操作流程)提炼为 记忆存储。 你的代理人随后在后续对话中回忆那些记忆,就像回忆它保存的记忆一样。

在对话中保存记忆的代理,一次只会按一段对话写入这些记忆,且仅使用该次对话的上下文。 在多次对话中,它的记忆会收集重叠和冲突的条目,而智能体没想到要保存的事实也无法进入记忆。 记忆管道在工作完成后运行,可查看某个参与者的所有对话和现有记忆,因此能够捕获智能体遗漏的内容并保持记忆的整合性。

当你想要使用内存管道时:

  • 从对话中建立长期记忆,而无需为你的智能体添加记忆写入工具。
  • 用会话存储中已有的对话历史回填记忆。
  • 通过合并重叠条目和拆分过大的条目,使记忆随着时间的推移保持井然有序。

你可以单独使用内存流水线,也可以配合代理在对话中调用的 内存工具 。

Note

内存流水线运行对作业使用 无服务器通用计算定价 ,对模型调用采用 基础模型服务定价 。

要求

  • 一个会话存储,用于保存你的代理的对话,以及一个用于写入记忆的记忆存储。
  • 创建流水线的身份对两个存储的访问权限,包括在内存存储数据库中创建表的权限。 管道运行使用该身份。
  • 允许查询管道用于蒸馏的模型。 没有它,管道的运行就会失败。
  • 要使用CLI,安装 databricks-agentbricks 0.6.0及以上版本。 你也可以使用任何编程语言直接调用REST API。

内存流水线的工作原理

内存流水线是一种代理内存资源,用于将一个会话存储连接到一个内存存储。 这和Lakeflow管道无关。 会话存储可以向多个内存存储提供数据,但每对会话存储和内存存储只能有一个流水线。

  • 通过Unity Gateway调用模型: 流水线通过 Unity Gateway调用其蒸馏模型。
  • 你的模型选择: 你在创建流水线时选择模型,之后可以更改。 如果你没有选择其中一个,流水线会使用默认模型。
  • 在无服务器计算上手动或按计划运行:您可以自行启动运行,也可以将管道配置为大约每 24 小时按计划运行一次。 无论哪种方式,每次运行都是作为无服务器计算的作业执行,使用创建流水线的身份。

流水线的每一次运行分别处理会话存储中的每个参与者:

  1. 提炼: 流水线读取智能体的新对话,并利用大型语言模型从中提取持久事实。
  2. 合并: 流水线会对新事实去重,并将其合并到内存存储中同一 actor_id 下按主题划分的内存条目。
  3. 维护:管道会重新组织该参与者的记忆。 它合并重叠的条目,并拆分变得过大的条目。

内存流水线运行会为每个参与者 ID 保留一个检查点。 一次运行会处理该参与者自上次成功运行以来的所有会话,因此第一次运行处理的是该参与者的完整历史。 如果一个actor的运行失败,则该运行继续进行其他actor的运行,下一次运行则从检查点重新尝试失败的actor。

actor_id 将两个存储关联起来。 管道仅处理在会话存储中具有会话的参与者,并将每个参与者的记忆写入该参与者的会话所使用的同一 actor_id 下。 默认情况下,管道只有在你开始运行时才会运行。 你也可以按计划运行它。

Note

维护适用于某个参与者的所有记忆条目,包括您的智能体直接保存的条目。 流水线可以重写、合并、拆分或删除其处理的 actor_id 下的任何条目。

管道会保留哪些内容

管道会从对话中提取独立的、持久的事实。 它旨在保留:

  • 用户明确陈述的事实及其表达的偏好,而不会推断超出对话内容的信息。
  • 更正和明确反馈,比如收入数据应使用哪个来源。
  • 持久的领域知识,如权威来源、度量定义、术语和团队惯例,以及工作流程和正在进行的项目。

它设计成跳过:

  • 来自实时源的值随时间变化,例如表当前行数。 它会改为记录如何查找或计算该值。
  • 代理可以用工具查找的细节,比如表的架构。
  • 机密信息,比如密码、API 密钥和令牌。

开始

这些示例为支持代理的会话和内存存储创建内存流水线,启动运行并检查结果。 通过每个商店的 ID、创建商店时选择的标识符或资源名称来识别,例如 memory-stores/support-agent-memory。 选择最适合你项目的客户。

Agent Bricks

Agent Bricks CLI 会使用你保存的 Databricks CLI 配置档案来进行身份验证。

  1. 安装 Agent Bricks CLI,或升级到 0.6.0 及以上版本:

    pip install --upgrade databricks-agentbricks
    
  2. 创建一个将 support-agent-sessions 会话存储提取并存入 support-agent-memory 内存存储的管道。 --model 是可选的。 如果省略了它,流水线将使用默认模型:

    agentbricks memory pipeline create \
      --session-store support-agent-sessions \
      --memory-store support-agent-memory \
      --model system.ai.claude-sonnet-5
    

    该命令返回管道的资源名称,形式为 memory-pipelines/<pipeline-id>。

  3. 启动一次管道运行:

    agentbricks memory pipeline run <pipeline-id>
    

    该命令返回该运行的资源名称,形式为 memory-pipelines/<pipeline-id>/runs/<run-id>,并返回其 RUNNING 状态。

  4. CLI不会报告某次运行的结果。 要检查它,请将 DATABRICKS_HOST 设置为您的工作区主机名,生成 OAuth 令牌,然后调用 REST API:

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

REST API

CLI 调用 /api/2.0/agents/memory-pipelines 下的 REST API。 可从任何语言直接调用它。

  1. 使用 Databricks CLI 生成 OAuth 令牌:

    databricks auth login --host ${DATABRICKS_HOST}
    export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)
    
  2. 创建一个管道,从 support-agent-sessions 中提取记忆并将其保存到 support-agent-memory。 dreamer_policy.model 是可选的。 如果省略了它,流水线将使用默认模型:

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

    响应的 name 字段中保存流水线的资源名称,格式为 memory-pipelines/<pipeline-id>。

  3. 启动一次管道运行:

    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 '{}'
    

    响应的 name 字段中包含运行的资源名称,形式为 memory-pipelines/<pipeline-id>/runs/<run-id>。

  4. 查看本次运行结果:

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

运行成功后,你的代理可以使用记忆存储的列表和搜索操作检索新记忆。 请参阅智能体记忆。

监视管道运行

一次运行的 state 是以下之一:

State Meaning
RUNNING 该运行处于待处理状态或正在进行中。
SUCCEEDED 该次运行成功处理了每个参与者。
FAILED 该次运行在一个或多个参与者上出错而结束。 error字段描述了该失败。
CANCELLED 该次运行在完成之前被取消。

通过指令引导蒸馏

指令告诉管道要保留哪些内容以及如何组织这些内容。 管道会在每个阶段应用这些指令。 使用它们进行高级指导,例如:

  • 需要关注的主题,比如客户偏好和账户详情。
  • 可以跳过的内容,比如一次性的故障排除步骤。
  • 用于归类条目的路径。

没有布局指令时,流水线会遵循商店现有条目的布局,或者在商店为空时推导出基于主题的布局。 它不会重新命名现有条目以匹配新的布局。 要更改特定条目,使用内存存储的更新操作编辑,而非使用指令。

你可以在创建管道时设置指令,之后再修改它们。 下一次运行使用了新指令。

Agent Bricks

创建管道时要设置指令,传入 --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/."

要从 UTF-8 文件加载更长的指令,请改为传入 --instructions @<path-to-file>。

要更改现有管道的指令,请运行以下内容:

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

REST API

在 REST API 中,流水线的 dreamer_policy 对象保存其蒸馏设置:instructions、trigger 和 model。 要在创建管道时设置指令,请将其包含在 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/."}}'

要更改现有管道的指令,请更新 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."}}'

按计划运行管道

按计划运行的管道大约每 24 小时自动运行一次。 你可以在创建管道时设置触发条件,或者以后更改。 调度程序决定首次计划运行何时开始。 要立即提炼现有对话,手动启动一次运行。

Agent Bricks

要创建定时管道,传递 --trigger scheduled。 默认值为 --trigger manual:

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

要更改现有管道的触发条件,请执行以下操作:

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

如果你有预定的管道,可以将其暂停:

agentbricks memory pipeline pause <pipeline-id>

要重新开始计划运行,请恢复该管道:

agentbricks memory pipeline resume <pipeline-id>

REST API

要创建调度管道,请将dreamer_policy.trigger设置为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"}}'

要更改现有流水线的触发条件,请更新 dreamer_policy.trigger 为 SCHEDULED 或 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"}}'

你也可以手动启动定时的流水线运行,只要没有其他运行正在进行中。

管理管道

以下命令用于列出、检查、更新和删除管道。 每个CLI命令接受流水线ID或其完整 memory-pipelines/<pipeline-id> 资源名称。

任务 Agent Bricks CLI REST API
列出管道 agentbricks memory pipeline list GET /api/2.0/agents/memory-pipelines
创建流水线 agentbricks memory pipeline get <pipeline-id> GET /api/2.0/agents/memory-pipelines/<pipeline-id>
更新管道 agentbricks memory pipeline update <pipeline-id> 使用 --display-name、--model、--trigger 或 --instructions PATCH /api/2.0/agents/memory-pipelines/<pipeline-id> 具有值为 display_name、dreamer_policy.model、dreamer_policy.trigger 或 dreamer_policy.instructions 的 update_mask
删除管道 agentbricks memory pipeline delete <pipeline-id> DELETE /api/2.0/agents/memory-pipelines/<pipeline-id>

如果你不设置显示名,流水线会根据会话存储和内存存储名获得显示名。 要将流水线切换回默认模型,将其模型更新为空值,例如 --model ""。 模型和指令的变更会应用于下一次运行。

删除流水线会删除其底层支撑作业,并停止后续运行。 已经进行中的运行会一直持续到完成。 流水线已经写入的内存条目会保留在内存存储中。

Limitations

  • 会话存储和内存存储在创建流水线时是固定的。 要更改其中任何一项,请删除该管道并创建一个新的管道。 新管道不会重复使用旧管道的检查点,因此其首次运行会处理每个参与者的完整历史记录,即使对于同一对存储也是如此。
  • 如果某个管道已连接相同的会话存储和记忆存储,则再创建一个会失败并返回 ALREADY_EXISTS。
  • 一个管道一次只能有一个正在进行的运行。 在另一个运行正在进行时启动新的运行会失败并返回 ABORTED 错误。
  • 按计划运行的管道大约每 24 小时运行一次。 你不能设置不同的间隔或cron时间表。
  • 流水线只处理在会话存储中有会话的参与者。 没有会话的参与者的记忆条目保持不变。
  • 如果会话存储中使用 UUID 作为 actor ID 的 actor 超过约 1,200 个,运行将失败。 序列化的参与者ID上限为 48 KiB,因此较短的ID允许更多参与者。

其他资源