从 inputs.id 迁移到 restore_from_state_id

概述

文档中规定的、从先前执行中 hydrate @persist flow 的方式，是将该次执行的 UUID 作为 inputs.id 传入。CrewAI 现在提供了一个专用字段 restore_from_state_id，它可以完成同样的 hydration，但不会让 inputs 负载承担双重职责，也不会把 hydration 键与新执行的身份耦合在一起。

迁移

如果你当前是用 inputs={"id": ...} 来 kickoff 一个 @persist flow：

# 已弃用
flow = CounterFlow()
flow.kickoff(inputs={"id": "abcd1234-5678-90ef-ghij-klmnopqrstuv"})

请改用 restore_from_state_id：

# 受支持
flow = CounterFlow()
flow.kickoff(restore_from_state_id="abcd1234-5678-90ef-ghij-klmnopqrstuv")

这两种模式的 lineage 语义不同：

inputs={"id": <uuid>}（已弃用） - resume：写入会落到所提供的 id 下，从而延续同一个 flow_uuid 历史。
restore_from_state_id=<uuid> - fork：从快照 hydrate 状态，然后写入到一个新的 state.id 下。源 flow 的历史会被保留。

对于大多数生产场景 - 也就是基于先前状态重新运行 flow - 你想要的是 fork。完整心智模型请参见掌握 Flow 状态管理。

如果你通过 CrewAI AMP REST API kickoff flow，请参见下方 AMP，了解等价的负载迁移方式。

为什么要废弃 `@persist` 里的 `inputs.id`

当前，inputs.id 是从先前执行中恢复 @persist flow 的文档方式。问题在于，同一个 UUID 同时承担了两种职责：

它决定 @persist 从哪个快照 hydrate - 加载保存在该 UUID 下的状态。
它还会成为新执行的 Flow Execution ID（SDK 中的 state.id；在某些场景中显示为 flow_id）- 本次 kickoff 的每一次 @persist 写入也都会落到同一个 UUID 下。

这种双重角色正是本指南所描述问题的根源。因为所传入的 UUID 同时也是新执行的 id，所以两个传入相同 inputs.id 的 kickoff 并不是两个独立执行 - 它们共享一个 id、共享一条持久化记录，而且在 AMP 上还会共享 executions 列表中的同一行。你无法在不拆分这两个职责的情况下，说出“从这个快照 hydrate，但把这次运行单独记录”。

restore_from_state_id 就是这种拆分。它告诉 @persist 要从哪个快照 hydrate，同时让新执行自由获得一个新的 state.id。hydration 来源和被记录的运行不再是同一个 UUID - 这也正是大多数生产场景真正需要的行为。

移除时间线

@persist hydration 中的 inputs.id 计划在 CrewAI 的未来版本中移除。不会立刻硬切断 - 现有 flow 仍然可以工作 - 但一旦你升级到 v1.14.5 或更高版本，新代码应使用 restore_from_state_id，而现有 flow 也应在下一个合适时机迁移。

AMP

如果你将 flow 部署到 CrewAI AMP，迁移也会延伸到发送给已部署 crew 的 kickoff 负载中，而重复使用 inputs.id 的可见症状会出现在部署面板上。下面两个小节分别说明这两部分。

迁移 kickoff 负载

如果你当前是通过把 id 嵌入 inputs 来 kickoff 已部署的 flow：

# 已弃用
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_CREW_TOKEN" \
  -d '{"inputs": {"id": "abcd1234-5678-90ef-ghij-klmnopqrstuv", "topic": "AI Agent Frameworks"}}' \
  https://your-crew-url.crewai.com/kickoff

把 UUID 移到顶层的 restoreFromStateId 字段：

# 受支持
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_CREW_TOKEN" \
  -d '{
        "inputs": {"topic": "AI Agent Frameworks"},
        "restoreFromStateId": "abcd1234-5678-90ef-ghij-klmnopqrstuv"
      }' \
  https://your-crew-url.crewai.com/kickoff

restoreFromStateId 位于 kickoff 负载中的 inputs 旁边，而不是放在它里面。现在 inputs 对象只携带你的 flow 实际消费的值。

当重复使用 `inputs.id` 时会发生什么

当 AMP 收到一个 kickoff，且该 flow 的 inputs.id 与已有执行匹配时，它会解析为已有记录，而不是创建新记录。在部署面板中你会看到：

执行状态 - 新运行的状态会覆盖前一次运行的状态。一个已完成的执行可能会回退为 running，或者一个 completed 运行在新 kickoff 失败时变成 error - 无论哪种情况，面板都不再反映原始运行。
Traces - 由于共享同一个 execution id，OTel traces 会在多次 kickoff 之间堆叠；前一次运行的 traces 可能被新运行替换，或与新运行混在一起。逐步回放将不再对应单个执行。
Executions 列表 - 原本应显示为多行的 kickoff 会坍缩成单个条目，从而隐藏历史记录。

迁移到 restoreFromStateId 后，每次 kickoff 都会保持为独立执行 - 各自拥有自己的状态、traces 和列表行 - 同时仍然可以从先前运行中 hydrate 状态。

需要帮助？

如果你不确定 flow 需要哪种模式，或者在迁移过程中遇到问题，请联系支持团队。