Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
Add single agent action to Flow definitions (#6226)
Vinicius Brasilbc2c2a858c5a
diff --git a/lib/crewai/src/crewai/flow/flow_definition.py b/lib/crewai/src/crewai/flow/flow_definition.pyindex 853dd3b77..a566fcadd 100644--- a/lib/crewai/src/crewai/flow/flow_definition.py+++ b/lib/crewai/src/crewai/flow/flow_definition.py@@ -28,7 +28,7 @@ from crewai.flow.conversational_definition import (FlowConversationalRouterDefinition,)from crewai.flow.expressions import ExpressionData-from crewai.project.crew_definition import CrewDefinition+from crewai.project.crew_definition import AgentDefinition, CrewDefinitionlogger = logging.getLogger(__name__)@@ -40,6 +40,7 @@ _EACH_STEP_CEL_ROOTS = frozenset({"item", "outputs", "state"})__all__ = ["FlowActionDefinition",+ "FlowAgentActionDefinition","FlowAtomicActionDefinition","FlowCodeActionDefinition","FlowConfigDefinition",@@ -435,6 +436,33 @@ class FlowCrewActionDefinition(BaseModel):)+class FlowAgentActionDefinition(BaseModel):+ """A Flow method action that builds and kicks off a CrewAI agent."""++ model_config = ConfigDict(+ populate_by_name=True,+ extra="forbid",+ )++ call: Literal["agent"] = Field(+ description="Action discriminator. Use agent to run an inline Agent definition.",+ examples=["agent"],+ )+ with_: AgentDefinition = Field(+ alias="with",+ description="Inline Agent definition to load and execute for this action.",+ examples=[+ {+ "role": "Analyst",+ "goal": "Answer user questions",+ "backstory": "Precise and concise.",+ "settings": {"llm": "openai/gpt-4o-mini"},+ "input": "${state.question}",+ }+ ],+ )++class FlowExpressionActionDefinition(BaseModel):"""A Flow method action that evaluates a CEL expression."""@@ -481,6 +509,7 @@ FlowAtomicActionDefinition: TypeAlias = Annotated[FlowCodeActionDefinition| FlowToolActionDefinition| FlowCrewActionDefinition+ | FlowAgentActionDefinition| FlowExpressionActionDefinition| FlowScriptActionDefinition,Field(discriminator="call"),@@ -573,6 +602,7 @@ FlowActionDefinition: TypeAlias = (FlowCodeActionDefinition| FlowToolActionDefinition| FlowCrewActionDefinition+ | FlowAgentActionDefinition| FlowExpressionActionDefinition| FlowScriptActionDefinition| FlowEachActionDefinition@@ -802,6 +832,13 @@ def _validate_action_cel()return+ if isinstance(action, FlowAgentActionDefinition):+ Expression(cast(ExpressionData, action.with_.input)).validate_template(+ allowed_roots=allowed_roots,+ source=f"{path}.with.input",+ )+ return+if isinstance(action, FlowEachActionDefinition):Expression(action.in_).validate_expression(allowed_roots=_BASE_CEL_ROOTS,@@ -821,6 +858,14 @@ def _validate_action_cel()return+ if isinstance(action, FlowScriptActionDefinition):+ return++ raise TypeError(+ f"no CEL validation defined for action type {type(action).__name__} at "+ f"{path}; add a branch to _validate_action_cel for it."+ )+def log_flow_definition_issues(definition: FlowDefinition) -> None:for method_name, method in definition.methods.items():diff --git a/lib/crewai/src/crewai/flow/runtime/_actions.py b/lib/crewai/src/crewai/flow/runtime/_actions.pyindex 79944c43e..c437e274b 100644--- a/lib/crewai/src/crewai/flow/runtime/_actions.py+++ b/lib/crewai/src/crewai/flow/runtime/_actions.py@@ -13,6 +13,7 @@ from typing import TYPE_CHECKING, Any, Protocol, castfrom crewai.flow.expressions import Expression, ExpressionDatafrom crewai.flow.flow_definition import (FlowActionDefinition,+ FlowAgentActionDefinition,FlowCodeActionDefinition,FlowCrewActionDefinition,FlowEachActionDefinition,@@ -140,6 +141,35 @@ class CrewAction:return await crew.kickoff_async(inputs=inputs)+class AgentAction:+ definition_type = FlowAgentActionDefinition++ def __init__(self, flow: Flow[Any], definition: FlowAgentActionDefinition) -> None:+ self.flow = flow+ self.definition = definition++ async def run(self, *_args: Any, **kwargs: Any) -> Any:+ from crewai.project.json_loader import load_agent_from_definition++ local_context = _pop_local_context(kwargs)+ rendered_input = Expression.from_flow(+ cast(ExpressionData, self.definition.with_.input),+ self.flow,+ local_context=local_context,+ ).render_template()+ if not isinstance(rendered_input, str):+ raise ValueError("agent input must render to a string")++ agent, response_format = load_agent_from_definition(+ self.definition.with_,+ source="agent action",+ )+ return await agent.kickoff_async(+ rendered_input,+ response_format=response_format,+ )++class ExpressionAction:definition_type = FlowExpressionActionDefinition@@ -284,6 +314,7 @@ _ACTION_TYPES: tuple[_ActionType, ...] = (EachAction,CodeAction,ToolAction,+ AgentAction,CrewAction,ExpressionAction,ScriptAction,diff --git a/lib/crewai/src/crewai/project/__init__.py b/lib/crewai/src/crewai/project/__init__.pyindex 151b616f9..cc9286596 100644--- a/lib/crewai/src/crewai/project/__init__.py+++ b/lib/crewai/src/crewai/project/__init__.py@@ -15,16 +15,22 @@ from crewai.project.annotations import ()from crewai.project.crew_base import CrewBasefrom crewai.project.crew_definition import (+ AgentDefinition,CrewAgentDefinition,CrewDefinition,CrewTaskDefinition,PythonReferenceDefinition,)from crewai.project.crew_loader import load_crew, load_crew_and_kickoff-from crewai.project.json_loader import load_agent, strip_jsonc_comments+from crewai.project.json_loader import (+ load_agent,+ load_agent_from_definition,+ strip_jsonc_comments,+)__all__ = [+ "AgentDefinition","CrewAgentDefinition","CrewBase","CrewDefinition",@@ -38,6 +44,7 @@ __all__ = ["crew","llm","load_agent",+ "load_agent_from_definition","load_crew","load_crew_and_kickoff","output_json",diff --git a/lib/crewai/src/crewai/project/crew_definition.py b/lib/crewai/src/crewai/project/crew_definition.pyindex 059878b5c..9e88c2ad6 100644--- a/lib/crewai/src/crewai/project/crew_definition.py+++ b/lib/crewai/src/crewai/project/crew_definition.py@@ -8,6 +8,7 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_valida__all__ = [+ "AgentDefinition","CrewAgentDefinition","CrewDefinition","CrewTaskDefinition",@@ -53,6 +54,20 @@ class CrewAgentDefinition(BaseModel):return value or {}+class AgentDefinition(CrewAgentDefinition):+ """Inline agent definition used by a Flow agent action."""++ input: str+ response_format: PythonReferenceDefinition | None = None++ @field_validator("input", mode="before")+ @classmethod+ def _validate_input(cls, value: Any) -> Any:+ if not isinstance(value, str):+ raise ValueError("agent.input must be a string")+ return value++class CrewTaskDefinition(BaseModel):"""Task definition used by a crew definition."""diff --git a/lib/crewai/src/crewai/project/json_loader.py b/lib/crewai/src/crewai/project/json_loader.pyindex 107eb8c0c..0c6d7cbba 100644--- a/lib/crewai/src/crewai/project/json_loader.py+++ b/lib/crewai/src/crewai/project/json_loader.py@@ -207,19 +207,18 @@ def load_jsonc_file(source: str | Path) -> Any:return parse_jsonc(path.read_text(encoding="utf-8"), source=path)-def load_agent(source: str | Path) -> Any:- """Load an existing ``Agent`` from a ``.json`` / ``.jsonc`` definition file."""- path = Path(source)- defn = _expect_object(load_jsonc_file(path), path)- root = path.parent.parent if path.parent.name == "agents" else path.parent+def _instantiate_agent_from_data(+ defn: dict[str, Any], source_label: str, root: Path+) -> Any:+ """Resolve the agent class and kwargs from definition data and instantiate it."""agent_class = _agent_class_from_definition(defn,- f"{path}: type",+ f"{source_label}: type",project_root=root,)agent_kwargs = _agent_kwargs_from_definition(defn,- path,+ source_label,agent_class=agent_class,project_root=root,)@@ -227,9 +226,50 @@ def load_agent(source: str | Path) -> Any:try:return agent_class(**agent_kwargs)except ValidationError as exc:- raise JSONProjectError(_format_validation_error(path, exc)) from exc+ raise JSONProjectError(_format_validation_error(source_label, exc)) from excexcept Exception as exc:- raise JSONProjectError(f"{path}: failed to load agent: {exc}") from exc+ raise JSONProjectError(f"{source_label}: failed to load agent: {exc}") from exc+++def load_agent(source: str | Path) -> Any:+ """Load an existing ``Agent`` from a ``.json`` / ``.jsonc`` definition file."""+ path = Path(source)+ defn = _expect_object(load_jsonc_file(path), path)+ root = path.parent.parent if path.parent.name == "agents" else path.parent+ return _instantiate_agent_from_data(defn, str(path), root)+++def load_agent_from_definition(+ definition: dict[str, Any] | Any,+ *,+ source: str | Path = "<inline agent>",+ project_root: str | Path | None = None,+) -> tuple[Any, type[BaseModel] | None]:+ """Load an ``Agent`` and optional kickoff response model from an inline definition."""+ from crewai.project.crew_definition import AgentDefinition++ root = Path(project_root) if project_root is not None else Path.cwd()+ source_label = str(source)+ agent_definition = (+ definition+ if isinstance(definition, AgentDefinition)+ else AgentDefinition.model_validate(definition)+ )+ definition_data = agent_definition.model_dump(mode="python", exclude_none=True)+ response_format_ref = definition_data.pop("response_format", None)+ definition_data.pop("input", None)++ agent = _instantiate_agent_from_data(definition_data, source_label, root)++ response_format = None+ if response_format_ref is not None:+ response_format = _resolve_model_class(+ response_format_ref,+ f"{source_label}: response_format",+ root,+ )++ return agent, response_formatdef validate_crew_project(diff --git a/lib/crewai/tests/project/test_json_loader.py b/lib/crewai/tests/project/test_json_loader.pyindex 3acfabf5d..a5a8f85fa 100644--- a/lib/crewai/tests/project/test_json_loader.py+++ b/lib/crewai/tests/project/test_json_loader.py@@ -7,6 +7,7 @@ from pathlib import Pathimport sysimport pytest+from pydantic import BaseModelfrom crewai.llms.base_llm import BaseLLMfrom crewai.project.json_loader import (@@ -14,6 +15,7 @@ from crewai.project.json_loader import (_looks_like_windows_absolute_path,find_json_project_file,load_agent,+ load_agent_from_definition,strip_jsonc_comments,)@@ -358,6 +360,30 @@ class TestLoadAgent:load_agent(Path("/nonexistent/agent.json"))+class TestLoadAgentFromDefinition:+ def test_resolves_response_format_from_project_module(self, tmp_path: Path):+ (tmp_path / "models.py").write_text(+ "from pydantic import BaseModel\n"+ "class AnswerModel(BaseModel):\n"+ " answer: str\n"+ )++ _, response_format = load_agent_from_definition(+ {+ "role": "Analyst",+ "goal": "Analyze data",+ "backstory": "Data expert.",+ "input": "Summarize this",+ "response_format": {"python": "models.AnswerModel"},+ },+ source="agent action",+ project_root=tmp_path,+ )++ assert issubclass(response_format, BaseModel)+ assert response_format.__name__ == "AnswerModel"++class TestResolveTools:def test_unknown_tool_raises_with_guidance(self):from crewai.project.json_loader import JSONProjectError, _resolve_toolsdiff --git a/lib/crewai/tests/test_flow_definition.py b/lib/crewai/tests/test_flow_definition.pyindex 73120e7db..4b5b8d37b 100644--- a/lib/crewai/tests/test_flow_definition.py+++ b/lib/crewai/tests/test_flow_definition.py@@ -37,6 +37,7 @@ def test_flow_public_exports_are_explicit():}assert set(flow_definition.__all__) == {"FlowActionDefinition",+ "FlowAgentActionDefinition","FlowAtomicActionDefinition","FlowCodeActionDefinition","FlowConfigDefinition",@@ -80,6 +81,10 @@ def test_flow_definition_json_schema_carries_reference_descriptions():assert "not interpolated" in script_properties["code"]["description"]assert "not sandboxed" in script_properties["code"]["description"]+ agent_properties = defs["FlowAgentActionDefinition"]["properties"]+ assert "Inline Agent definition" in agent_properties["with"]["description"]+ assert "run an inline Agent" in agent_properties["call"]["description"]+state_schema = next(branchfor branch in schema["properties"]["state"]["anyOf"]@@ -122,6 +127,7 @@ def test_flow_definition_json_schema_carries_field_examples_only():"FlowDefinition","FlowCodeActionDefinition","FlowToolActionDefinition",+ "FlowAgentActionDefinition","FlowCrewActionDefinition","FlowExpressionActionDefinition","FlowScriptActionDefinition",@@ -157,6 +163,10 @@ def test_flow_definition_json_schema_carries_field_examples_only():]assert action_properties["with"]["examples"] == [{"topic": "${state.topic}"}]+ agent_properties = defs["FlowAgentActionDefinition"]["properties"]+ assert agent_properties["call"]["examples"] == ["agent"]+ assert agent_properties["with"]["examples"][0]["input"] == "${state.question}"+each_properties = defs["FlowEachActionDefinition"]["properties"]assert each_properties["in"]["examples"] == ["state.rows"]assert each_properties["do"]["examples"][0][0]["name"] == "clean"diff --git a/lib/crewai/tests/test_flow_from_definition.py b/lib/crewai/tests/test_flow_from_definition.pyindex 67fa7b843..1ed8dbcf9 100644--- a/lib/crewai/tests/test_flow_from_definition.py+++ b/lib/crewai/tests/test_flow_from_definition.py@@ -811,6 +811,166 @@ methods:)+def test_agent_action_runs_inline_yaml_definition(monkeypatch: pytest.MonkeyPatch):+ from crewai import Agent++ async def fake_kickoff_async(+ self: Agent, messages: str, **_kwargs: Any+ ) -> dict[str, Any]:+ return {"agent": self.role, "input": messages}++ monkeypatch.setattr(Agent, "kickoff_async", fake_kickoff_async)++ yaml_str = """+schema: crewai.flow/v1+name: AgentFlow+methods:+ answer:+ do:+ call: agent+ with:+ role: Analyst+ goal: Answer questions+ backstory: Knows things.+ input: "${state.question}"+ start: true+"""++ flow = Flow.from_definition(FlowDefinition.from_yaml(yaml_str))++ assert flow.kickoff(inputs={"question": "What is CrewAI?"}) == {+ "agent": "Analyst",+ "input": "What is CrewAI?",+ }+++def test_agent_action_runs_inside_each(monkeypatch: pytest.MonkeyPatch):+ from crewai import Agent++ async def fake_kickoff_async(+ self: Agent, messages: str, **_kwargs: Any+ ) -> str:+ return f"{self.role}:{messages}"++ monkeypatch.setattr(Agent, "kickoff_async", fake_kickoff_async)++ yaml_str = """+schema: crewai.flow/v1+name: AgentEachFlow+methods:+ answer_each:+ do:+ call: each+ in: state.questions+ do:+ - name: answer+ action:+ call: agent+ with:+ role: Analyst+ goal: Answer questions+ backstory: Knows things.+ input: "${item}"+ start: true+"""++ flow = Flow.from_definition(FlowDefinition.from_yaml(yaml_str))++ assert flow.kickoff(inputs={"questions": ["one", "two"]}) == [+ "Analyst:one",+ "Analyst:two",+ ]+++def test_agent_action_round_trips_with_inline_definition():+ definition = FlowDefinition.from_dict(+ {+ "schema": "crewai.flow/v1",+ "name": "AgentFlow",+ "methods": {+ "answer": {+ "start": True,+ "do": {+ "call": "agent",+ "with": {+ "role": "Analyst",+ "goal": "Answer questions",+ "backstory": "Knows things.",+ "settings": {"verbose": True},+ "input": "${state.question}",+ },+ },+ }+ },+ }+ )++ round_trip = FlowDefinition.from_yaml(definition.to_yaml())+ action = round_trip.to_dict()["methods"]["answer"]["do"]++ assert action["call"] == "agent"+ assert action["with"]["role"] == "Analyst"+ assert action["with"]["input"] == "${state.question}"+ assert action["with"]["settings"] == {"verbose": True}+++def test_agent_action_json_schema_describes_inline_agent_definitions():+ schema_defs = FlowDefinition.json_schema()["$defs"]++ assert set(schema_defs["AgentDefinition"]["properties"]) >= {+ "role",+ "goal",+ "backstory",+ "settings",+ "input",+ "response_format",+ }+++def test_agent_action_rejects_non_string_input_in_definition():+ with pytest.raises(ValidationError, match="agent.input must be a string"):+ FlowDefinition.from_dict(+ {+ "schema": "crewai.flow/v1",+ "name": "AgentFlow",+ "methods": {+ "answer": {+ "start": True,+ "do": {+ "call": "agent",+ "with": {+ "role": "Analyst",+ "goal": "Answer questions",+ "backstory": "Knows things.",+ "input": 123,+ },+ },+ }+ },+ }+ )+++def test_agent_action_reports_invalid_cel_expression():+ yaml_str = """+schema: crewai.flow/v1+name: AgentFlow+methods:+ answer:+ do:+ call: agent+ with:+ role: Analyst+ goal: Answer questions+ backstory: Knows things.+ input: "${state.}"+ start: true+"""++ with pytest.raises(ValidationError, match="invalid CEL expression"):+ FlowDefinition.from_yaml(yaml_str)++def test_crew_action_runs_inline_yaml_definition(monkeypatch: pytest.MonkeyPatch):from crewai import Crew