inputs.id에서 restore_from_state_id로 마이그레이션

개요

이전 실행에서 @persist 흐름을 하이드레이트하는 문서화된 방법은 해당 실행의 UUID를 inputs.id로 전달하는 것입니다. CrewAI는 이제 inputs 페이로드를 과부하하지 않고 동일한 하이드레이션을 수행하는 전용 필드인 restore_from_state_id를 제공합니다 — 그리고 하이드레이션 키를 새로운 실행의 정체성과 결합하지 않습니다.

마이그레이션

현재 inputs={"id": ...}로 @persist 흐름을 시작하는 경우:

# 더 이상 지원되지 않음
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")

두 모드는 서로 다른 계보 의미론을 가지고 있습니다:

inputs={"id": <uuid>} (더 이상 지원되지 않음) — 재개: 제공된 id 아래에 기록이 작성되어 동일한 flow_uuid 이력이 확장됩니다.
restore_from_state_id=<uuid> — 분기: 스냅샷에서 상태를 하이드레이트한 후 새로운 state.id 아래에 기록합니다. 원본 흐름의 이력은 보존됩니다.

대부분의 프로덕션 시나리오에서는 — 이전 상태에서 시드된 흐름을 다시 실행하는 경우 — 분기가 필요합니다. 전체 정신 모델은 Flow State 마스터링을 참조하십시오.

CrewAI AMP REST API를 통해 흐름을 시작하는 경우, 아래 AMP에서 동일한 페이로드 마이그레이션을 참조하십시오.

왜 `@persist`에 대해 `inputs.id`를 더 이상 지원하지 않습니까?

inputs.id는 현재 이전 실행에서 @persist 흐름을 재개하는 문서화된 방법입니다. 문제는 동일한 UUID가 두 가지 작업을 동시에 수행한다는 것입니다:

어떤 스냅샷에서 @persist가 하이드레이트되는지를 선택합니다 — 해당 UUID 아래에 저장된 상태를 로드합니다.
새 실행의 흐름 실행 ID가 됩니다 (state.id는 SDK에서; 일부 컨텍스트에서는 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에 배포하는 경우, 마이그레이션은 배포된 팀에 전송되는 시작 페이로드로 확장되며, inputs.id를 재사용하는 가시적인 증상은 배포 대시보드에 나타납니다. 아래 두 개의 하위 섹션이 이를 다룹니다.

시작 페이로드 마이그레이션

현재 inputs에 id를 포함하여 배포된 흐름을 시작하는 경우:

# 더 이상 지원되지 않음
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는 시작 페이로드에서 inputs 옆에 위치하며, 내부에 있지 않습니다. inputs 객체는 이제 흐름이 실제로 소비하는 값만 포함합니다.

`inputs.id`가 재사용될 때 발생하는 일

AMP가 기존 실행과 inputs.id가 일치하는 흐름의 시작을 수신하면, 새로운 기록을 생성하는 대신 기존 기록으로 해결됩니다. 배포 대시보드에서 다음을 확인할 수 있습니다:

실행 상태 — 새로운 실행의 상태가 이전 실행의 상태를 덮어씁니다. 완료된 실행은 다시 실행 중으로 전환되거나, 완료된 실행은 새로운 시작이 실패할 경우 오류로 전환될 수 있습니다 — 어쨌든 대시보드는 더 이상 원래 실행을 반영하지 않습니다.
추적 — OTel 추적이 시작 간에 쌓이기 때문에 동일한 실행 id를 공유합니다; 이전 실행의 추적은 새로운 실행의 추적과 교체되거나 혼합됩니다. 단계별 재생은 더 이상 단일 실행에 해당하지 않습니다.
실행 목록 — 별도의 행으로 나타나야 할 시작이 단일 항목으로 축소되어 이력을 숨깁니다.

restoreFromStateId로 마이그레이션하면 모든 시작이 자체 실행으로 유지됩니다 — 각자의 상태, 추적 및 목록의 행을 가지며 — 여전히 이전 실행에서 상태를 하이드레이트합니다.

도움이 필요하신가요?

흐름이 어떤 모드가 필요한지 확실하지 않거나 마이그레이션 중 문제가 발생하면 지원 팀에 문의하십시오.