Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
Make declarative refs work across flows and crews (#6326)
Vinicius Brasil7738a1d30ca2
diff --git a/lib/crewai/src/crewai/flow/runtime/__init__.py b/lib/crewai/src/crewai/flow/runtime/__init__.pyindex 24f863c4e..4bb67a269 100644--- a/lib/crewai/src/crewai/flow/runtime/__init__.py+++ b/lib/crewai/src/crewai/flow/runtime/__init__.py@@ -123,7 +123,6 @@ from crewai.flow.human_feedback import (from crewai.flow.input_provider import InputProviderfrom crewai.flow.persistence.base import FlowPersistencefrom crewai.flow.runtime._actions import FlowScriptExecutionDisabledError, build_action-from crewai.flow.runtime._refs import resolve_instance_ref, resolve_reffrom crewai.flow.types import (FlowExecutionData,FlowMethodName,@@ -137,6 +136,7 @@ from crewai.state.checkpoint_config import (_coerce_checkpoint,apply_checkpoint,)+from crewai.utilities.declarative_refs import InvalidRefError, resolve_refif TYPE_CHECKING:@@ -289,6 +289,18 @@ def _resolve_persistence(value: Any) -> Any:return value+def _resolve_instance_ref(ref: str, *, field: str) -> Any:+ target = resolve_ref(ref, field=field)+ if not inspect.isclass(target):+ return target+ try:+ return target()+ except Exception as e:+ raise InvalidRefError(+ f"cannot instantiate {field} ref {ref!r} without arguments: {e}"+ ) from e++def _serialize_persistence(value: Any) -> dict[str, Any] | None:if value is None:return None@@ -304,7 +316,7 @@ def _validate_input_provider(value: Any) -> Any:if value is None or isinstance(value, InputProvider):return valueif isinstance(value, str) and ":" in value:- resolved = resolve_instance_ref(value, field="input_provider")+ resolved = _resolve_instance_ref(value, field="input_provider")else:from crewai.types.callback import _dotted_path_to_instance@@ -3605,7 +3617,7 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):) -> Any:provider = feedback_definition.providerif isinstance(provider, str):- provider = resolve_instance_ref(provider, field="human_feedback.provider")+ provider = _resolve_instance_ref(provider, field="human_feedback.provider")if provider is None:from crewai.flow.flow_config import flow_configdiff --git a/lib/crewai/src/crewai/flow/runtime/_actions.py b/lib/crewai/src/crewai/flow/runtime/_actions.pyindex c8f118775..9b5c8831f 100644--- a/lib/crewai/src/crewai/flow/runtime/_actions.py+++ b/lib/crewai/src/crewai/flow/runtime/_actions.py@@ -24,7 +24,11 @@ from crewai.flow.flow_definition import (FlowToolActionDefinition,)from crewai.flow.runtime._outputs import outputs_by_name-from crewai.flow.runtime._refs import InvalidRefError, resolve_ref+from crewai.utilities.declarative_refs import (+ InvalidRefError,+ resolve_class_ref,+ resolve_ref,+)if TYPE_CHECKING:@@ -103,16 +107,17 @@ class ToolAction:)def _build_tool(self) -> Any:- target = resolve_ref(self.definition.ref, field="do")from crewai.tools import BaseTool- if not (inspect.isclass(target) and issubclass(target, BaseTool)):- raise InvalidRefError(- f"invalid tool ref {self.definition.ref!r}; expected a BaseTool class"- )-+ tool_cls = cast(+ Callable[[], BaseTool],+ resolve_class_ref(+ self.definition.ref,+ field="do",+ base_class=BaseTool,+ ),+ )try:- tool_cls = cast(Callable[[], BaseTool], target)return tool_cls()except Exception as e:raise InvalidRefError(diff --git a/lib/crewai/src/crewai/flow/runtime/_refs.py b/lib/crewai/src/crewai/flow/runtime/_refs.pydeleted file mode 100644index 23ddafadb..000000000--- a/lib/crewai/src/crewai/flow/runtime/_refs.py+++ /dev/null@@ -1,38 +0,0 @@-"""Resolution of ``module:qualname`` refs into live Python objects."""--from __future__ import annotations--import importlib-import inspect-from operator import attrgetter-from typing import Any---class InvalidRefError(ValueError):- """A definition ref that cannot be resolved to a live object."""---def resolve_ref(ref: str, *, field: str) -> Any:- """Import the object a definition's `module:qualname` ref points to."""- module_name, _, qualname = ref.partition(":")- if "<" in ref or not module_name or not qualname:- raise InvalidRefError(- f"invalid {field} ref {ref!r}; expected 'module:qualname'"- )- try:- return attrgetter(qualname)(importlib.import_module(module_name))- except (ImportError, AttributeError) as e:- raise InvalidRefError(f"unresolvable {field} ref {ref!r}") from e---def resolve_instance_ref(ref: str, *, field: str) -> Any:- """Resolve a ref, auto-instantiating a no-arg class into an instance."""- target = resolve_ref(ref, field=field)- if not inspect.isclass(target):- return target- try:- return target()- except Exception as e:- raise InvalidRefError(- f"cannot instantiate {field} ref {ref!r} without arguments: {e}"- ) from ediff --git a/lib/crewai/src/crewai/project/json_loader.py b/lib/crewai/src/crewai/project/json_loader.pyindex 0c6d7cbba..2c2a229fb 100644--- a/lib/crewai/src/crewai/project/json_loader.py+++ b/lib/crewai/src/crewai/project/json_loader.py@@ -16,6 +16,8 @@ from urllib.parse import unquote, urlparsefrom pydantic import BaseModel, ValidationError+from crewai.utilities.declarative_refs import InvalidRefError, resolve_class_ref+logger = logging.getLogger(__name__)@@ -1820,6 +1822,9 @@ def _resolve_tools(tool_defs: list[Any], project_root: Path | None = None) -> liif tool_def.startswith("custom:"):tools.append(_resolve_custom_tool(tool_def[7:], project_root=project_root))continue+ if ":" in tool_def:+ tools.append(_instantiate_tool_import_ref(tool_def))+ continuetry:tool_cls = _find_tool_class(tool_def)except Exception as e:@@ -1827,8 +1832,10 @@ def _resolve_tools(tool_defs: list[Any], project_root: Path | None = None) -> liif tool_cls is None:raise JSONProjectError(f"Unknown tool '{tool_def}'. Tool names must match a class from "- f"the 'crewai_tools' package (e.g. 'SerperDevTool') or use the "- f"'custom:<name>' prefix for a tool defined in tools/<name>.py."+ f"the 'crewai_tools' package (e.g. 'SerperDevTool'), use a "+ f"'module:ClassName' import ref (e.g. 'crewai_tools:SerperDevTool'), "+ f"or use the 'custom:<name>' prefix for a tool defined in "+ f"tools/<name>.py.")try:tools.append(tool_cls())@@ -1839,6 +1846,32 @@ def _resolve_tools(tool_defs: list[Any], project_root: Path | None = None) -> lireturn tools+def _instantiate_tool_import_ref(ref: str) -> Any:+ from crewai.tools import BaseTool++ try:+ tool_cls = cast(+ Callable[[], BaseTool],+ resolve_class_ref(ref, field="tool", base_class=BaseTool),+ )+ except InvalidRefError as e:+ message = str(e)+ if (+ message.startswith("unresolvable ")+ or "expected 'module:qualname'" in message+ ):+ raise JSONProjectError(str(e)) from e+ raise JSONProjectError(+ f"invalid tool ref {ref!r}; expected a BaseTool class"+ ) from e+ try:+ return tool_cls()+ except Exception as e:+ raise JSONProjectError(+ f"cannot instantiate tool ref {ref!r} without arguments: {e}"+ ) from e++_tool_class_cache: dict[str, type | None] = {}diff --git a/lib/crewai/src/crewai/utilities/declarative_refs.py b/lib/crewai/src/crewai/utilities/declarative_refs.pynew file mode 100644index 000000000..5779fe129--- /dev/null+++ b/lib/crewai/src/crewai/utilities/declarative_refs.py@@ -0,0 +1,69 @@+"""Resolve Python refs used in project definitions.++A ref must use this form: ``module:qualname``. ``module`` must name a Python+module we can import. ``qualname`` must name something inside that module. For+example, ``crewai_tools:SerperDevTool`` imports ``crewai_tools`` and returns+``SerperDevTool`` from it. Dots in ``qualname`` mean nested attributes.++Examples:++- ``crewai_tools:SerperDevTool`` imports ``crewai_tools`` and returns+ ``SerperDevTool``.+- ``my_app.tools:Factory.build`` imports ``my_app.tools``, gets ``Factory``,+ then gets ``build`` from ``Factory``.+- ``crewai_tools`` is invalid because it has no ``:``.+- ``crewai_tools:`` is invalid because it has no ``qualname``.++These helpers are the shared contract for YAML/JSON definitions:++- ``resolve_ref()`` checks the ref, imports the module, and returns the symbol+ as-is.+- ``resolve_class_ref()`` does the same work, then checks that the symbol is a+ class. It can also check that the class extends a base class. It does not+ create an object.++These helpers import user code. Code that must avoid that should check the raw+string shape instead.+"""++from __future__ import annotations++import importlib+import inspect+from operator import attrgetter+from typing import Any+++class InvalidRefError(ValueError):+ """A definition ref that cannot be resolved to a live Python symbol."""+++def resolve_ref(ref: str, *, field: str) -> Any:+ """Return the Python symbol named by a project definition field."""+ module_name, _, qualname = ref.partition(":")+ if "<" in ref or not module_name or not qualname:+ raise InvalidRefError(+ f"invalid {field} ref {ref!r}; expected 'module:qualname'"+ )+ try:+ return attrgetter(qualname)(importlib.import_module(module_name))+ except (ImportError, AttributeError) as e:+ raise InvalidRefError(f"unresolvable {field} ref {ref!r}") from e+++def resolve_class_ref(+ ref: str,+ *,+ field: str,+ base_class: type[Any] | None = None,+) -> type[Any]:+ """Return the named class, with an optional base class check."""+ target = resolve_ref(ref, field=field)+ if not inspect.isclass(target):+ raise InvalidRefError(f"invalid {field} ref {ref!r}; expected a class")+ if base_class is not None and not issubclass(target, base_class):+ raise InvalidRefError(+ f"invalid {field} ref {ref!r}; expected a subclass of "+ f"{base_class.__module__}.{base_class.__name__}"+ )+ return targetdiff --git a/lib/crewai/tests/project/test_json_loader.py b/lib/crewai/tests/project/test_json_loader.pyindex a5a8f85fa..ff2d5d48c 100644--- a/lib/crewai/tests/project/test_json_loader.py+++ b/lib/crewai/tests/project/test_json_loader.py@@ -385,12 +385,52 @@ class TestLoadAgentFromDefinition:class TestResolveTools:+ def test_import_ref_tool_resolves(self, tmp_path, monkeypatch):+ from crewai.project.json_loader import _resolve_tools++ (tmp_path / "project_tools.py").write_text(+ "from crewai.tools.base_tool import BaseTool\n"+ "\n"+ "class LookupTool(BaseTool):\n"+ " name: str = 'lookup'\n"+ " description: str = 'lookup input'\n"+ "\n"+ " def _run(self, text: str) -> str:\n"+ " return text\n"+ )+ monkeypatch.syspath_prepend(str(tmp_path))++ tools = _resolve_tools(["project_tools:LookupTool"])++ assert len(tools) == 1+ assert tools[0].name == "lookup"+def test_unknown_tool_raises_with_guidance(self):from crewai.project.json_loader import JSONProjectError, _resolve_toolswith pytest.raises(JSONProjectError, match="Unknown tool 'NotARealToolXYZ'"):_resolve_tools(["NotARealToolXYZ"])+ def test_import_ref_tool_must_resolve_to_basetool_class(+ self, tmp_path, monkeypatch+ ):+ from crewai.project.json_loader import JSONProjectError, _resolve_tools++ (tmp_path / "not_tools.py").write_text(+ "class NotATool:\n"+ " pass\n"+ )+ monkeypatch.syspath_prepend(str(tmp_path))++ with pytest.raises(JSONProjectError, match="expected a BaseTool class"):+ _resolve_tools(["not_tools:NotATool"])++ def test_unresolvable_import_ref_tool_raises_guidance(self):+ from crewai.project.json_loader import JSONProjectError, _resolve_tools++ with pytest.raises(JSONProjectError, match="unresolvable tool ref"):+ _resolve_tools(["not_a_real_module:MissingTool"])+def test_missing_custom_tool_raises(self, tmp_path, monkeypatch):from crewai.project.json_loader import JSONProjectError, _resolve_tools@@ -505,6 +545,30 @@ class TestValidationDoesNotExecuteTools:assert not sentinel.exists(), "validation must not import Python refs"+ def test_validate_does_not_import_tool_refs(+ self, tmp_path, monkeypatch: pytest.MonkeyPatch+ ):+ from crewai.project.json_loader import validate_crew_project++ sentinel = tmp_path / "tool_ref_executed.txt"+ (tmp_path / "project_tools.py").write_text(+ "from pathlib import Path\n"+ f"Path({str(sentinel)!r}).write_text('boom')\n"+ "from crewai.tools.base_tool import BaseTool\n"+ "class LookupTool(BaseTool):\n"+ " name: str = 'lookup'\n"+ " description: str = 'lookup input'\n"+ " def _run(self, text: str) -> str:\n"+ " return text\n"+ )+ monkeypatch.syspath_prepend(str(tmp_path))+ sys.modules.pop("project_tools", None)+ crew_path = self._write_project(tmp_path, tool_line='"project_tools:LookupTool"')++ validate_crew_project(crew_path, tmp_path / "agents")++ assert not sentinel.exists(), "validation must not import tool refs"+def test_validate_reports_missing_custom_tool_file(self, tmp_path):from crewai.project.json_loader import (JSONProjectValidationError,