从 inputs.id 迁移到 restore_from_state_id

将 @persist 流程从已弃用的 inputs.id 状态恢复方式迁移到受支持的 restore_from_state_id 字段

WARNING

在 inputs 中传入 id 来恢复 @persist 流程的状态已被弃用，并计划在未来版本中移除。替代方案 restore_from_state_id 在 CrewAI v1.14.5 及更高版本中可用——你升级之后，下面的步骤即可适用。

概述

文档中记载的从先前的执行恢复 @persist 流程状态的方式，是将该次执行的 UUID 作为 inputs.id 传入。CrewAI 现在提供了一个专门的字段 restore_from_state_id，它执行同样的状态恢复，而无需在 inputs 载荷中额外承载——也不必把恢复用的键与新的执行身份耦合在一起。

迁移

如果你目前使用 inputs=""id": ..." 启动 @persist 流程：

python

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

改为使用 restore_from_state_id：

python

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

这两种模式具有不同的谱系语义：

inputs=""id": <uuid>"（已弃用）——续跑：写入落在所提供的 id 之下，延续同一个 flow_uuid 历史。
restore_from_state_id=<uuid>——分叉：从快照恢复状态，然后在新的 state.id 下写入。源流程的历史得以保留。

对于大多数生产场景——从先前的状态重新运行一个流程——分叉正是你想要的。完整的心智模型请参阅掌握流程状态。

如果你通过 CrewAI AMP REST API 启动流程，请参阅下方的 AMP，了解等价的载荷迁移方式。

为什么我们要为 `@persist` 弃用 `inputs.id`

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

它决定 @persist 从哪个快照恢复——加载在该 UUID 下保存的状态。
它会成为新执行的 Flow Execution ID（SDK 中的 state.id；在某些上下文中以 flow_id 呈现）——本次启动产生的每一次 @persist 写入也都会落在同一个 UUID 之下。

这种双重角色正是本指南所述问题的根源。由于所提供的 UUID 同时也是新执行的 id，两次传入相同 inputs.id 的启动就不再是两次不同的执行——它们共享一个 id、共享一条持久化记录，并且（在 AMP 上）共享执行列表中的同一行。如果不拆分这两项职责，就无法表达“从这个快照恢复状态，但将本次运行单独记录”。

restore_from_state_id 就是这种拆分。它告诉 @persist 从哪个快照恢复状态，同时让新的执行可以自由地获得一个新的 state.id。恢复来源与所记录的运行不再是同一个 UUID——而这正是大多数生产场景真正想要的。

移除时间表

用于 @persist 状态恢复的 inputs.id 计划在 CrewAI 的未来版本中移除。目前没有立即的硬性截止——现有流程仍可继续工作——但一旦你升级到 v1.14.5 或更高版本，新代码应使用 restore_from_state_id，现有流程也应在下一个方便的时候进行迁移。

AMP

如果你将流程部署到 CrewAI AMP，迁移还涉及发送到已部署团队的 kickoff 载荷，而复用 inputs.id 的可见症状会出现在部署仪表盘上。下面两个小节分别涵盖这两方面。

迁移 kickoff 载荷

如果你目前通过在 inputs 中内嵌 id 来启动已部署的流程：

bash

# Deprecated
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 字段：

bash

# Supported
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 对象现在只承载你的流程实际使用的值。

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

当 AMP 收到某个流程的 kickoff，而其 inputs.id 与现有执行匹配时，它会解析到现有记录，而不是创建新记录。在部署仪表盘上你会看到：

执行状态——新运行的状态会覆盖先前运行的状态。一个已完成的执行可能变回 running，或者一个 completed 的运行可能因新的 kickoff 失败而变为 error——无论哪种情况，仪表盘都不再反映最初的运行。
追踪——OTel 追踪会在多次 kickoff 之间堆叠，因为它们共享同一个执行 id；先前运行的追踪要么被新运行的追踪替换，要么与之混杂在一起。逐步回放不再对应单次执行。
执行列表——本应显示为独立行的多次 kickoff 会合并为单条记录，从而隐藏了历史。

迁移到 restoreFromStateId 后，每次 kickoff 都保留为独立执行——拥有自己的状态、追踪和列表中的行——同时仍从上一轮运行中填充状态。

Need Help?

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

从 inputs.id 迁移到 restore_from_state_id

概述

迁移

为什么我们要为 @persist 弃用 inputs.id

移除时间表

AMP

迁移 kickoff 载荷

复用 inputs.id 时会发生什么

友情链接

为什么我们要为 `@persist` 弃用 `inputs.id`

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