Add unified declarative flow loading (#6308)

Add a single declaration loader shared by API and CLI callers.

- Add FlowDefinition.from_declaration for FlowDefinition instances, dictionaries, YAML/JSON strings, and file paths
- Add Flow.from_declaration to build runnable flows directly from the same inputs
- Route declarative flow CLI loading through Flow.from_declaration so path handling and validation stay centralized

```
# Load just the serializable definition when you do not need to run it yet.
definition = FlowDefinition.from_declaration(path="flows/research.crewai")
definition = FlowDefinition.from_declaration(contents=flow_yaml)
definition = FlowDefinition.from_declaration(contents=flow_dict)

# Build a runnable flow directly from the same declaration inputs.
flow = Flow.from_declaration(path="flows/research.crewai")
flow = Flow.from_declaration(contents=flow_yaml)
flow = Flow.from_declaration(contents=flow_dict)
flow = Flow.from_declaration(contents=definition)

# Run it like any other flow.
result = flow.kickoff(inputs={"topic": "AI agents"})

# The CLI now goes through the same path-based loader.
# crewai run --definition flows/research.crewai
```

lib/cli/src/crewai_cli/run_declarative_flow.py

@@ -6,6 +6,7 @@ import subprocess
 from typing import Any
 
 import click
+from pydantic import ValidationError
 
 from crewai_cli.utils import build_env_with_all_tool_credentials
 
@@ -65,7 +66,6 @@ def load_declarative_flow(definition: str) -> Any:
     """Load a declarative Flow instance from a definition path."""
     try:
         from crewai.flow.flow import Flow
-        from crewai.flow.flow_definition import FlowDefinition
     except ImportError as exc:
         click.echo(
             "Running declarative flows requires the full crewai package.",
@@ -74,14 +74,30 @@ def load_declarative_flow(definition: str) -> Any:
         raise SystemExit(1) from exc
 
     definition_path = Path(definition).expanduser()
-    definition_source = _read_declarative_flow_source(definition_path, definition)
+    try:
+        if not definition_path.is_file():
+            if definition_path.exists():
+                click.echo(
+                    f"Invalid --definition path: {definition} is not a file.",
+                    err=True,
+                )
+                raise SystemExit(1)
+            click.echo(
+                f"Invalid --definition path: {definition} does not exist.", err=True
+            )
+            raise SystemExit(1)
+    except OSError as exc:
+        click.echo(f"Invalid --definition path: {definition} ({exc})", err=True)
+        raise SystemExit(1) from exc
 
-    flow_definition = _parse_declarative_flow(
-        FlowDefinition,
-        definition_source,
-        source_path=definition_path,
-    )
-    return Flow.from_definition(flow_definition)
+    try:
+        return Flow.from_declaration(path=definition_path)
+    except (OSError, UnicodeError, ValueError, ValidationError) as exc:
+        click.echo(
+            f"Unable to read --definition path {definition_path}: {exc}",
+            err=True,
+        )
+        raise SystemExit(1) from exc
 
 
 def configured_project_declarative_flow(
@@ -154,53 +170,6 @@ def _parse_inputs(inputs: str | None) -> dict[str, Any] | None:
     return parsed
 
 
-def _read_declarative_flow_source(path: Path, definition: str) -> str:
-    try:
-        if path.is_file():
-            source = _read_declarative_flow_file(path)
-        elif path.exists():
-            click.echo(
-                f"Invalid --definition path: {definition} is not a file.", err=True
-            )
-            raise SystemExit(1)
-        else:
-            click.echo(
-                f"Invalid --definition path: {definition} does not exist.", err=True
-            )
-            raise SystemExit(1)
-    except OSError as exc:
-        click.echo(f"Invalid --definition path: {definition} ({exc})", err=True)
-        raise SystemExit(1) from exc
-
-    return source
-
-
-def _read_declarative_flow_file(path: Path) -> str:
-    try:
-        source = path.read_text(encoding="utf-8")
-    except (OSError, UnicodeError) as exc:
-        click.echo(
-            f"Unable to read --definition path {path}: {exc}",
-            err=True,
-        )
-        raise SystemExit(1) from exc
-    return source
-
-
-def _parse_declarative_flow(
-    flow_definition_cls: type[Any], source: str, *, source_path: Path
-) -> Any:
-    if _looks_like_json(source):
-        return flow_definition_cls.from_json(source, source_path=source_path)
-
-    return flow_definition_cls.from_yaml(source, source_path=source_path)
-
-
-def _looks_like_json(source: str) -> bool:
-    stripped = source.lstrip()
-    return stripped.startswith("{")
-
-
 def _format_result(result: Any) -> str:
     raw_result = getattr(result, "raw", result)
     if isinstance(raw_result, str):

lib/cli/tests/test_run_declarative_flow.py

@@ -60,6 +60,43 @@ def test_run_declarative_flow_reports_missing_file(
     )
 
 
+def test_run_declarative_flow_reports_empty_file(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    definition_path = tmp_path / "flow.yaml"
+    definition_path.write_text(" \n", encoding="utf-8")
+
+    with pytest.raises(SystemExit):
+        run_declarative_flow_module.run_declarative_flow(str(definition_path))
+
+    assert "Flow declaration file is empty" in capsys.readouterr().err
+
+
+@pytest.mark.parametrize(
+    "contents, expected_error",
+    [
+        ("[]\n", "Flow declaration must contain a mapping"),
+        ("schema: crewai.flow/v1\nmethods: {}\n", "Field required"),
+    ],
+)
+def test_load_declarative_flow_reports_invalid_declarations(
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+    contents: str,
+    expected_error: str,
+) -> None:
+    definition_path = tmp_path / "flow.yaml"
+    definition_path.write_text(contents, encoding="utf-8")
+
+    with pytest.raises(SystemExit) as exc_info:
+        run_declarative_flow_module.load_declarative_flow(str(definition_path))
+
+    assert exc_info.value.code == 1
+    stderr = capsys.readouterr().err
+    assert f"Unable to read --definition path {definition_path}:" in stderr
+    assert expected_error in stderr
+
+
 def test_run_declarative_flow_in_project_env_uses_uv(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None: