[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
Warning-only kickoff path change with no persistence or execution semantics altered; covered by dedicated tests.

Overview
Adds local AMP parity for persisted flows: when kickoff receives inputs["id"] that is not a valid UUID and the flow has any active persistence (instance backend, flow-level persist, or method-level @persist), the runtime emits a one-time UserWarning explaining that CrewAI AMP rejects such ids with HTTP 422 and suggesting str(uuid4()).

The check runs in kickoff_async after execution-start/input hooks so it validates the effective id. _has_active_persistence() centralizes detection so method-only @persist (where self.persistence stays None) still triggers the warning. Local behavior is unchanged—non-UUID ids still work in OSS; flows without persistence do not warn.

New tests in test_flow_id_format_warning.py cover warn-once-and-run, valid UUID silent, method-level persist only, and no persistence.

^{Reviewed by Cursor Bugbot for commit eb68217. 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 on non-UUID ids for persisted flows to match AMP behavior.
Description check	✅ Passed	The description is directly related to the changeset and accurately explains 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.}