[EPD-197] Warn locally when a persisted flow gets a non-UUID id input (AMP parity)

[joaomdmoura]

• CrewAI AMP deployments reject non-UUID inputs.id values with HTTP 422, but the OSS library accepts any string locally, so kickoff(inputs={"id": "session-1"}) works in dev and fails on first AMP contact.
• Adds a one-time UserWarning at kickoff when a flow with persistence active receives a non-UUID id input, telling the user AMP rejects such ids with 422 and to use a UUID (e.g. str(uuid4())).
• Non-breaking: local behavior is unchanged — non-UUID ids keep working exactly as before; the warning only fires when persistence is active (when id is meaningful for state) and once per kickoff.
• New tests in lib/crewai/tests/test_flow_id_format_warning.py: non-UUID id + persistence warns once and still runs; valid UUID id does not warn; non-UUID id without persistence does not warn. test_flow_persistence.py still passes.
• Linear: https://linear.app/crewai/issue/EPD-197

🤖 Generated with Claude Code

---

Note

Low Risk
Adds a non-breaking UserWarning at kickoff with no change to flow execution or persistence semantics; scope is limited to id validation messaging.

Overview
Persisted flows that receive a non-UUID inputs["id"] at kickoff now emit a one-time UserWarning explaining that CrewAI AMP returns HTTP 422 for those ids, while OSS still accepts any string. Execution and persistence behavior are unchanged.

The warning runs only when persistence is considered active—instance/class backend, flow-level persist, or method-level @persist (via new _has_active_persistence()), not for flows with no persistence. Tests in test_flow_id_format_warning.py cover warn-once-still-runs, valid UUID silent, method-only persist, and no-persistence no warn.

^{Reviewed by Cursor Bugbot for commit 406b265. Bugbot is set up for automated code reviews on this repo. Configure here.}

[linear]

EPD-197

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

Flow ID warning parity

Layer / File(s)	Summary
Persisted kickoff validation lib/crewai/src/crewai/flow/runtime/__init__.py	Flow kickoff detects instance, flow-level, and method-level persistence, then warns when inputs["id"] cannot be coerced to a UUID.
Warning behavior coverage lib/crewai/tests/test_flow_id_format_warning.py	Tests cover non-UUID warnings, valid UUIDs, method-level persistence, state persistence, execution, and non-persisted flows.

Sequence Diagram(s)

sequenceDiagram
  participant Flow as Flow.kickoff_async
  participant Persistence as _has_active_persistence
  participant Validator as _warn_if_non_uuid_flow_state_id
  Flow->>Persistence: Check active persistence
  Persistence-->>Flow: Return persistence status
  Flow->>Validator: Validate inputs["id"]
  Validator-->>Flow: Emit UserWarning for non-UUID

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 55.56% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main change: warning locally for non-UUID persisted flow IDs for AMP parity.
Description check	✅ Passed	The description is directly related to the changeset and accurately describes the warning behavior and tests.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch joao/epd-197-amp-non-uuid-id-input-rejected-with-422-on-amp-undocumented

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 450a4de. Configure here.}