Allow Flow initialization with required BaseModel fields via kwargs

[visalvo]

Related Issues
Closes #3629

Changes
This PR fixes the initialization issue when using Pydantic BaseModel with required fields as Flow state by enabling kwargs to be passed during state creation.

What Changed

• Modified _create_initial_state() method signature

  • Added kwargs: dict[str, Any] | None = None parameter
  • Pass kwargs when instantiating BaseModel classes
  • Merge kwargs into dictionary states

• Updated __init__() method

  • Pass kwargs to _create_initial_state()
  • Removed redundant _initialize_state(kwargs) call from init since kwargs are now handled during state creation

Files Changed

• src/crewai/flow/flow.py

Why This Solution

• Minimal changes: Only modifies the initialization flow, no breaking changes
• Reuses existing logic: Leverages Pydantic's built-in validation with kwargs
• Backwards compatible: Existing code without kwargs continues to work
• Type safe: Pydantic validates kwargs against the model schema
• Consistent: All state types (dict, BaseModel, FlowState) handle kwargs uniformly

Additional Notes
The _initialize_state() method remains unchanged and continues to be used by kickoff_async() for runtime state updates. This separation of concerns maintains clarity:

• _create_initial_state(): Creates the initial state during Flow instantiation
• _initialize_state(): Updates state during Flow execution (kickoff)

---

Note

Enable passing kwargs to initialize Flow state (dict, BaseModel, FlowState), merging them during construction while preserving auto-generated id; add comprehensive tests.

• Flow core:
  • State initialization: _create_initial_state(kwargs) now accepts kwargs and merges them into state for FlowState, BaseModel, and dict types; prevents overriding auto-generated id.
  • Constructor: __init__ passes kwargs to _create_initial_state (removes separate _initialize_state(kwargs) during init).
• Tests:
  • Add tests for initializing with required Pydantic fields, FlowState subclass, kickoff input overrides, ignoring id in kwargs, and no-initial-state dict behavior.
  • Minor updates to imports and event assertions (noqa annotations).

^{Written by Cursor Bugbot for commit 08b19e3. This will update automatically on new commits. Configure here.}

[visalvo]

Hi crewAI team! 👋

I've opened this PR to address issue #3629, which adds support for Flow initialization with Pydantic models that have required fields.

Summary of changes:

• Modified _create_initial_state() to accept kwargs during state instantiation
• Updated __init__() to pass kwargs to state creation
• Added comprehensive tests covering BaseModel, FlowState, and dict state types
• Maintained backward compatibility with existing Flow usage

I'd really appreciate any feedback or suggestions from the maintainers on:

• The approach taken (passing kwargs during state creation vs. post-initialization)
• Test coverage adequacy
• Any edge cases I might have missed

This change would enable much better type safety when using Flows with strongly-typed Pydantic models. Happy to make any adjustments based on your feedback!

Thanks for your time! 🙏