Skip to main content
梦境(Dreaming)会在指定条件满足时创建一个普通会话,由配置的智能体读取并修改原记忆库中的文件。 梦境策略由平台管理的触发器执行,结果直接写回原记忆库,不会创建新的记忆库。
梦境失败时不会自动回滚已经写入的内容。 梦境可能修改多个文件,恢复时需要逐个文件处理,不能一次性恢复整个记忆库。

配置自动梦境

使用已有的记忆库 ID,选中需要更新的记忆库。 配置执行梦境的智能体时,agent_id 可以省略,省略后使用平台默认的 Dream Agent。 每次更新都要同时传入完整的 activityschedule 对象,代表执行梦境的活动条件或定时条件。 两个条件相互独立,任一条件满足都会触发梦境。 两个条件启用任意一个,就必须提供执行环境 ID。 下面的示例请求同时启用活动条件和定时条件。 MEMORY_STORE_IDENVIRONMENT_ID 和可选的 agent_id 应替换为已有资源的 ID。
活动条件会统计绑定该记忆库的会话中,自上次触发梦境(或启用该条件)以来发生变化的会话数量。 会话数量达到 min_changed_sessions 后,平台会触发一次梦境。 梦境创建的普通会话不会再次触发该条件。 定时条件表示,梦境每天在指定的本地时间触发一次。 触发时,即使没有新的会话,平台也会创建一次梦境运行,让智能体检查是否需要更新记忆库。 local_time 使用 HH:mm 格式,timezone 使用 IANA 时区名称。 如果只需要其中一个条件,需要将另一个条件的 enabled 设置为 false,但仍然要传入完整的条件对象。

关闭自动梦境

将两个条件的 enabled 都设置为 false,即可关闭自动梦境。 关闭时不需要提供 environment_id。 先将当前策略响应中的 agent_id 保存为 DREAM_AGENT_ID,这样可以保留当前使用的 Dream Agent。 如果当前使用的是平台默认的 Dream Agent,可以将 DREAM_AGENT_ID 设置为 agent_dream
省略 agent_id 会选择平台默认的 Dream Agent。

查看当前策略

更新后查询 Dream Policy,并保存响应中的 trigger_id trigger_id 标识 Dream Policy 管理的触发器。 触发器(Trigger)是一条按照条件启动智能体会话的规则。 活动条件或定时条件满足时,平台会通过这条触发器创建一次梦境会话。 查询代码:
响应示例:
保存响应中的 trigger_id,将它设置为 TRIGGER_ID。 后续手动运行梦境和查询运行记录时需要使用这个值。 触发器由 Dream Policy 接口统一管理,不能通过触发器接口更新、暂停、恢复或归档。 需要调整触发条件或关闭自动梦境时,继续使用 Dream Policy 接口。 如果要立即运行一次梦境,可以调用这个触发器的运行接口。

手动运行梦境

Dream Policy 没有单独的立即运行接口。 调用触发器的运行接口即可手动触发一次梦境。
响应示例:
运行接口会同步执行本次触发,响应直接返回终态的运行记录(completedfailedskipped)。 响应中的 id 是本次 TriggerRun 的 ID。 将它保存为 TRIGGER_RUN_ID,用于查询本次运行状态。

查看触发记录

TriggerRun 是一次运行记录,用于记录梦境的执行状态和关联会话。 使用上一步得到的 TRIGGER_RUN_ID 查询本次运行的最新状态。
响应示例:
运行状态包括 runningcompletedfailedskipped。 其中,running 表示会话正在启动,failed 表示运行失败(详见 error),skipped 表示触发时触发器不在活跃状态。 completed 只表示平台已经创建会话,并且接受了会话的初始事件,不表示梦境已经完成记忆整理。 需要继续查看 session_id 对应的会话事件和记忆库版本,确认梦境的实际执行结果。 如果运行记录还没有 session_id,说明本次运行还没有创建或关联会话,此时不能查询对应会话。 如果需要查看历史运行记录,可以列出该触发器的所有 TriggerRun:

查看关联会话

获取运行记录中的 session_id 后,使用该值查询本次运行创建的会话。
SESSION_ID 应替换为 TriggerRun 响应中的 session_id。 查看会话事件可以了解梦境的执行过程:
如果需要持续接收执行过程中的状态和输出,请参阅 事件流

检查记忆库的修改

梦境可能修改记忆库中的多个文件。 先列出文件,选择需要检查的文件 ID:
将上一步文件列表中目标文件的 id 保存为 MEMORY_ID,查询该文件的版本列表。版本按时间从新到旧排列:
梦境创建的普通会话使用 source: "session"source_id 是本次梦境会话的 ID。 sourceapi 表示通过 API 直接写入;通过 API 恢复文件产生的版本也是 api。 先将 TriggerRun 响应中的 session_id 保存后,在版本列表中筛选 sourcesessionsource_id 等于该会话 ID 的版本,就能定位本次梦境产生的所有变更。 再结合 operationpathcreated_at,判断本次运行对该文件执行了创建、修改、重命名还是删除(重命名通过比较相邻版本的 path 判断)。 需要读取正文时,选择 operation 不是 "deleted" 且没有 redacted_at 的版本,将它的 id 保存为 VERSION_ID
返回的 content 是 Base64 编码。 operation"deleted" 的版本只是删除标记,没有正文;已经 redacted_at 的版本正文已被清除。恢复被删除的文件时,应使用该文件删除前最近一个可读版本,而不是删除标记本身。 梦境失败时可能已经留下部分文件变更,因此需要逐个检查受影响的文件。

恢复文件

恢复文件就是把某个历史版本的正文写回当前文件。 上一节已经取得历史版本响应中的 content,将它保存为 HISTORICAL_CONTENT 恢复前,重新读取当前文件,取得最新的 content_sha256
将当前文件响应中的 content_sha256 保存为 CONTENT_SHA256。 这里只需要保存 content_sha256,当前文件响应中的 content 不用于本次恢复。 CONTENT_SHA256 必须直接使用接口返回的值,不能自行填写或修改。 然后,将历史版本的正文写回当前文件:
更新成功后,平台会返回更新后的文件;内容发生变化时,会为这次恢复生成一个新的文件版本,写入与当前内容相同的内容则不生成新版本。 后续再次更新该文件时,应使用响应中的新 content_sha256 如果当前文件在读取后已经被其他操作修改,旧的 content_sha256 与当前值不匹配,更新会返回 409,平台不会覆盖新的内容。 此时应重新读取当前文件,取得新的 content_sha256,再决定是否继续恢复。 恢复多个文件时,需要为每个文件分别读取最新的 content_sha256 并执行更新。 恢复多个文件时,平台会分别更新每个文件。如果某个文件更新失败,之前已经恢复成功的文件不会自动撤销,因此需要逐个确认恢复结果。

相关资源

记忆库

创建记忆库、绑定会话并管理记忆版本。

会话

了解会话的创建方式和记忆库绑定配置。

智能体

配置执行梦境的智能体。