Skip to content

Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.

feat: add async support for tools and agent executor; improve typing and docs

Greyson LaLonde633e279b51a0
diff --git a/lib/crewai/src/crewai/agents/crew_agent_executor.py b/lib/crewai/src/crewai/agents/crew_agent_executor.py
index 5286c532e..580119a99 100644
--- a/lib/crewai/src/crewai/agents/crew_agent_executor.py
+++ b/lib/crewai/src/crewai/agents/crew_agent_executor.py
@@ -28,6 +28,7 @@ from crewai.hooks.llm_hooks import (
get_before_llm_call_hooks,
)
from crewai.utilities.agent_utils import (
+ aget_llm_response,
enforce_rpm_limit,
format_message_for_llm,
get_llm_response,
@@ -43,7 +44,10 @@ from crewai.utilities.agent_utils import (
from crewai.utilities.constants import TRAINING_DATA_FILE
from crewai.utilities.i18n import I18N, get_i18n
from crewai.utilities.printer import Printer
-from crewai.utilities.tool_utils import execute_tool_and_check_finality
+from crewai.utilities.tool_utils import (
+ aexecute_tool_and_check_finality,
+ execute_tool_and_check_finality,
+)
from crewai.utilities.training_handler import CrewTrainingHandler
@@ -134,8 +138,8 @@ class CrewAgentExecutor(CrewAgentExecutorMixin):
self.messages: list[LLMMessage] = []
self.iterations = 0
self.log_error_after = 3
- self.before_llm_call_hooks: list[Callable] = []
- self.after_llm_call_hooks: list[Callable] = []
+ self.before_llm_call_hooks: list[Callable[..., Any]] = []
+ self.after_llm_call_hooks: list[Callable[..., Any]] = []
self.before_llm_call_hooks.extend(get_before_llm_call_hooks())
self.after_llm_call_hooks.extend(get_after_llm_call_hooks())
if self.llm:
@@ -312,6 +316,154 @@ class CrewAgentExecutor(CrewAgentExecutorMixin):
self._show_logs(formatted_answer)
return formatted_answer
+ async def ainvoke(self, inputs: dict[str, Any]) -> dict[str, Any]:
+ """Execute the agent asynchronously with given inputs.
+
+ Args:
+ inputs: Input dictionary containing prompt variables.
+
+ Returns:
+ Dictionary with agent output.
+ """
+ if "system" in self.prompt:
+ system_prompt = self._format_prompt(
+ cast(str, self.prompt.get("system", "")), inputs
+ )
+ user_prompt = self._format_prompt(
+ cast(str, self.prompt.get("user", "")), inputs
+ )
+ self.messages.append(format_message_for_llm(system_prompt, role="system"))
+ self.messages.append(format_message_for_llm(user_prompt))
+ else:
+ user_prompt = self._format_prompt(self.prompt.get("prompt", ""), inputs)
+ self.messages.append(format_message_for_llm(user_prompt))
+
+ self._show_start_logs()
+
+ self.ask_for_human_input = bool(inputs.get("ask_for_human_input", False))
+
+ try:
+ formatted_answer = await self._ainvoke_loop()
+ except AssertionError:
+ self._printer.print(
+ content="Agent failed to reach a final answer. This is likely a bug - please report it.",
+ color="red",
+ )
+ raise
+ except Exception as e:
+ handle_unknown_error(self._printer, e)
+ raise
+
+ if self.ask_for_human_input:
+ formatted_answer = self._handle_human_feedback(formatted_answer)
+
+ self._create_short_term_memory(formatted_answer)
+ self._create_long_term_memory(formatted_answer)
+ self._create_external_memory(formatted_answer)
+ return {"output": formatted_answer.output}
+
+ async def _ainvoke_loop(self) -> AgentFinish:
+ """Execute agent loop asynchronously until completion.
+
+ Returns:
+ Final answer from the agent.
+ """
+ formatted_answer = None
+ while not isinstance(formatted_answer, AgentFinish):
+ try:
+ if has_reached_max_iterations(self.iterations, self.max_iter):
+ formatted_answer = handle_max_iterations_exceeded(
+ formatted_answer,
+ printer=self._printer,
+ i18n=self._i18n,
+ messages=self.messages,
+ llm=self.llm,
+ callbacks=self.callbacks,
+ )
+ break
+
+ enforce_rpm_limit(self.request_within_rpm_limit)
+
+ answer = await aget_llm_response(
+ llm=self.llm,
+ messages=self.messages,
+ callbacks=self.callbacks,
+ printer=self._printer,
+ from_task=self.task,
+ from_agent=self.agent,
+ response_model=self.response_model,
+ executor_context=self,
+ )
+ formatted_answer = process_llm_response(answer, self.use_stop_words) # type: ignore[assignment]
+
+ if isinstance(formatted_answer, AgentAction):
+ fingerprint_context = {}
+ if (
+ self.agent
+ and hasattr(self.agent, "security_config")
+ and hasattr(self.agent.security_config, "fingerprint")
+ ):
+ fingerprint_context = {
+ "agent_fingerprint": str(
+ self.agent.security_config.fingerprint
+ )
+ }
+
+ tool_result = await aexecute_tool_and_check_finality(
+ agent_action=formatted_answer,
+ fingerprint_context=fingerprint_context,
+ tools=self.tools,
+ i18n=self._i18n,
+ agent_key=self.agent.key if self.agent else None,
+ agent_role=self.agent.role if self.agent else None,
+ tools_handler=self.tools_handler,
+ task=self.task,
+ agent=self.agent,
+ function_calling_llm=self.function_calling_llm,
+ crew=self.crew,
+ )
+ formatted_answer = self._handle_agent_action(
+ formatted_answer, tool_result
+ )
+
+ self._invoke_step_callback(formatted_answer) # type: ignore[arg-type]
+ self._append_message(formatted_answer.text) # type: ignore[union-attr,attr-defined]
+
+ except OutputParserError as e:
+ formatted_answer = handle_output_parser_exception( # type: ignore[assignment]
+ e=e,
+ messages=self.messages,
+ iterations=self.iterations,
+ log_error_after=self.log_error_after,
+ printer=self._printer,
+ )
+
+ except Exception as e:
+ if e.__class__.__module__.startswith("litellm"):
+ raise e
+ if is_context_length_exceeded(e):
+ handle_context_length(
+ respect_context_window=self.respect_context_window,
+ printer=self._printer,
+ messages=self.messages,
+ llm=self.llm,
+ callbacks=self.callbacks,
+ i18n=self._i18n,
+ )
+ continue
+ handle_unknown_error(self._printer, e)
+ raise e
+ finally:
+ self.iterations += 1
+
+ if not isinstance(formatted_answer, AgentFinish):
+ raise RuntimeError(
+ "Agent execution ended without reaching a final answer. "
+ f"Got {type(formatted_answer).__name__} instead of AgentFinish."
+ )
+ self._show_logs(formatted_answer)
+ return formatted_answer
+
def _handle_agent_action(
self, formatted_answer: AgentAction, tool_result: ToolResult
) -> AgentAction | AgentFinish:
diff --git a/lib/crewai/src/crewai/utilities/agent_utils.py b/lib/crewai/src/crewai/utilities/agent_utils.py
index 18f939425..3e90ef991 100644
--- a/lib/crewai/src/crewai/utilities/agent_utils.py
+++ b/lib/crewai/src/crewai/utilities/agent_utils.py
@@ -242,17 +242,17 @@ def get_llm_response(
"""Call the LLM and return the response, handling any invalid responses.
Args:
- llm: The LLM instance to call
- messages: The messages to send to the LLM
- callbacks: List of callbacks for the LLM call
- printer: Printer instance for output
- from_task: Optional task context for the LLM call
- from_agent: Optional agent context for the LLM call
- response_model: Optional Pydantic model for structured outputs
- executor_context: Optional executor context for hook invocation
+ llm: The LLM instance to call.
+ messages: The messages to send to the LLM.
+ callbacks: List of callbacks for the LLM call.
+ printer: Printer instance for output.
+ from_task: Optional task context for the LLM call.
+ from_agent: Optional agent context for the LLM call.
+ response_model: Optional Pydantic model for structured outputs.
+ executor_context: Optional executor context for hook invocation.
Returns:
- The response from the LLM as a string
+ The response from the LLM as a string.
Raises:
Exception: If an error occurs.
@@ -284,6 +284,60 @@ def get_llm_response(
return _setup_after_llm_call_hooks(executor_context, answer, printer)
+async def aget_llm_response(
+ llm: LLM | BaseLLM,
+ messages: list[LLMMessage],
+ callbacks: list[TokenCalcHandler],
+ printer: Printer,
+ from_task: Task | None = None,
+ from_agent: Agent | LiteAgent | None = None,
+ response_model: type[BaseModel] | None = None,
+ executor_context: CrewAgentExecutor | None = None,
+) -> str:
+ """Call the LLM asynchronously and return the response.
+
+ Args:
+ llm: The LLM instance to call.
+ messages: The messages to send to the LLM.
+ callbacks: List of callbacks for the LLM call.
+ printer: Printer instance for output.
+ from_task: Optional task context for the LLM call.
+ from_agent: Optional agent context for the LLM call.
+ response_model: Optional Pydantic model for structured outputs.
+ executor_context: Optional executor context for hook invocation.
+
+ Returns:
+ The response from the LLM as a string.
+
+ Raises:
+ Exception: If an error occurs.
+ ValueError: If the response is None or empty.
+ """
+ if executor_context is not None:
+ if not _setup_before_llm_call_hooks(executor_context, printer):
+ raise ValueError("LLM call blocked by before_llm_call hook")
+ messages = executor_context.messages
+
+ try:
+ answer = await llm.acall(
+ messages,
+ callbacks=callbacks,
+ from_task=from_task,
+ from_agent=from_agent, # type: ignore[arg-type]
+ response_model=response_model,
+ )
+ except Exception as e:
+ raise e
+ if not answer:
+ printer.print(
+ content="Received None or empty response from LLM call.",
+ color="red",
+ )
+ raise ValueError("Invalid response from LLM call - None or empty.")
+
+ return _setup_after_llm_call_hooks(executor_context, answer, printer)
+
+
def process_llm_response(
answer: str, use_stop_words: bool
) -> AgentAction | AgentFinish:
diff --git a/lib/crewai/tests/agents/test_async_agent_executor.py b/lib/crewai/tests/agents/test_async_agent_executor.py
new file mode 100644
index 000000000..bfed955de
--- /dev/null
+++ b/lib/crewai/tests/agents/test_async_agent_executor.py
@@ -0,0 +1,345 @@
+"""Tests for async agent executor functionality."""
+
+import asyncio
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from crewai.agents.crew_agent_executor import CrewAgentExecutor
+from crewai.agents.parser import AgentAction, AgentFinish
+from crewai.tools.tool_types import ToolResult
+
+
+def mock_llm() -> MagicMock:
+ """Create a mock LLM for testing."""
+ llm = MagicMock()
+ llm.supports_stop_words.return_value = True
+ llm.stop = []
+ return llm
+
+
+def mock_agent() -> MagicMock:
+ """Create a mock agent for testing."""
+ agent = MagicMock()
+ agent.role = "Test Agent"
+ agent.key = "test_agent_key"
+ agent.verbose = False
+ agent.id = "test_agent_id"
+ return agent
+
+
+def mock_task() -> MagicMock:
+ """Create a mock task for testing."""
+ task = MagicMock()
+ task.description = "Test task description"
+ return task
+
+
+def mock_crew() -> MagicMock:
+ """Create a mock crew for testing."""
+ crew = MagicMock()
+ crew.verbose = False
+ crew._train = False
+ return crew
+
+
+def mock_tools_handler() -> MagicMock:
+ """Create a mock tools handler."""
+ return MagicMock()
+
+
+def executor(
+ mock_llm: MagicMock,
+ mock_agent: MagicMock,
+ mock_task: MagicMock,
+ mock_crew: MagicMock,
+ mock_tools_handler: MagicMock,
+) -> CrewAgentExecutor:
+ """Create a CrewAgentExecutor instance for testing."""
+ return CrewAgentExecutor(
+ llm=mock_llm,
+ task=mock_task,
+ crew=mock_crew,
+ agent=mock_agent,
+ prompt={"prompt": "Test prompt {input} {tool_names} {tools}"},
+ max_iter=5,
+ tools=[],
+ tools_names="",
+ stop_words=["Observation:"],
+ tools_description="",
+ tools_handler=mock_tools_handler,
+ )
+
+
+class TestAsyncAgentExecutor:
+ """Tests for async agent executor methods."""
+
+ @pytest.mark.asyncio
+ async def test_ainvoke_returns_output(self, executor: CrewAgentExecutor) -> None:
+ """Test that ainvoke returns the expected output."""
+ expected_output = "Final answer from agent"
+
+ with patch.object(
+ executor,
+ "_ainvoke_loop",
+ new_callable=AsyncMock,
+ return_value=AgentFinish(
+ thought="Done", output=expected_output, text="Final Answer: Done"
+ ),
+ ):
+ with patch.object(executor, "_show_start_logs"):
+ with patch.object(executor, "_create_short_term_memory"):
+ with patch.object(executor, "_create_long_term_memory"):
+ with patch.object(executor, "_create_external_memory"):
+ result = await executor.ainvoke(
+ {
+ "input": "test input",
+ "tool_names": "",
+ "tools": "",
+ }
+ )
+
+ assert result == {"output": expected_output}
+
+ @pytest.mark.asyncio
+ async def test_ainvoke_loop_calls_aget_llm_response(
+ self, executor: CrewAgentExecutor
+ ) -> None:
+ """Test that _ainvoke_loop calls aget_llm_response."""
+ with patch(
+ "crewai.agents.crew_agent_executor.aget_llm_response",
+ new_callable=AsyncMock,
+ return_value="Thought: I know the answer\nFinal Answer: Test result",
+ ) as mock_aget_llm:
+ with patch.object(executor, "_show_logs"):
+ result = await executor._ainvoke_loop()
+
+ mock_aget_llm.assert_called_once()
+ assert isinstance(result, AgentFinish)
+
+ @pytest.mark.asyncio
+ async def test_ainvoke_loop_handles_tool_execution(
+ self,
+ executor: CrewAgentExecutor,
+ ) -> None:
+ """Test that _ainvoke_loop handles tool execution asynchronously."""
+ call_count = 0
+
+ async def mock_llm_response(*args: Any, **kwargs: Any) -> str:
+ nonlocal call_count
+ call_count += 1
+ if call_count == 1:
+ return (
+ "Thought: I need to use a tool\n"
+ "Action: test_tool\n"
+ 'Action Input: {"arg": "value"}'
+ )
+ return "Thought: I have the answer\nFinal Answer: Tool result processed"
+
+ with patch(
+ "crewai.agents.crew_agent_executor.aget_llm_response",
+ new_callable=AsyncMock,
+ side_effect=mock_llm_response,
+ ):
+ with patch(
+ "crewai.agents.crew_agent_executor.aexecute_tool_and_check_finality",
+ new_callable=AsyncMock,
+ return_value=ToolResult(result="Tool executed", result_as_answer=False),
+ ) as mock_tool_exec:
+ with patch.object(executor, "_show_logs"):
+ with patch.object(executor, "_handle_agent_action") as mock_handle:
+ mock_handle.return_value = AgentAction(
+ text="Tool result",
+ tool="test_tool",
+ tool_input='{"arg": "value"}',
+ thought="Used tool",
+ result="Tool executed",
+ )
+ result = await executor._ainvoke_loop()
+
+ assert mock_tool_exec.called
+ assert isinstance(result, AgentFinish)
+
+ @pytest.mark.asyncio
+ async def test_ainvoke_loop_respects_max_iterations(
+ self, executor: CrewAgentExecutor
+ ) -> None:
+ """Test that _ainvoke_loop respects max iterations."""
+ executor.max_iter = 2
+
+ async def always_return_action(*args: Any, **kwargs: Any) -> str:
+ return (
+ "Thought: I need to think more\n"
+ "Action: some_tool\n"
+ "Action Input: {}"
+ )
+
+ with patch(
+ "crewai.agents.crew_agent_executor.aget_llm_response",
+ new_callable=AsyncMock,
+ side_effect=always_return_action,
+ ):
+ with patch(
+ "crewai.agents.crew_agent_executor.aexecute_tool_and_check_finality",
+ new_callable=AsyncMock,
+ return_value=ToolResult(result="Tool result", result_as_answer=False),
+ ):
+ with patch(
+ "crewai.agents.crew_agent_executor.handle_max_iterations_exceeded",
+ return_value=AgentFinish(
+ thought="Max iterations",
+ output="Forced answer",
+ text="Max iterations reached",
+ ),
+ ) as mock_max_iter:
+ with patch.object(executor, "_show_logs"):
+ with patch.object(executor, "_handle_agent_action") as mock_ha:
+ mock_ha.return_value = AgentAction(
+ text="Action",
+ tool="some_tool",
+ tool_input="{}",
+ thought="Thinking",
+ )
+ result = await executor._ainvoke_loop()
+
+ mock_max_iter.assert_called_once()
+ assert isinstance(result, AgentFinish)
+
+ @pytest.mark.asyncio
+ async def test_ainvoke_handles_exceptions(
+ self, executor: CrewAgentExecutor
+ ) -> None:
+ """Test that ainvoke properly propagates exceptions."""
+ with patch.object(executor, "_show_start_logs"):
+ with patch.object(
+ executor,
+ "_ainvoke_loop",
+ new_callable=AsyncMock,
+ side_effect=ValueError("Test error"),
+ ):
+ with pytest.raises(ValueError, match="Test error"):
+ await executor.ainvoke(
+ {"input": "test", "tool_names": "", "tools": ""}
+ )
+
+ @pytest.mark.asyncio
+ async def test_concurrent_ainvoke_calls(
+ self, mock_llm: MagicMock, mock_agent: MagicMock, mock_task: MagicMock,
+ mock_crew: MagicMock, mock_tools_handler: MagicMock
+ ) -> None:
+ """Test that multiple ainvoke calls can run concurrently."""
+
+ async def create_and_run_executor(executor_id: int) -> dict[str, Any]:
+ executor = CrewAgentExecutor(
+ llm=mock_llm,
+ task=mock_task,
+ crew=mock_crew,
+ agent=mock_agent,
+ prompt={"prompt": "Test {input} {tool_names} {tools}"},
+ max_iter=5,
+ tools=[],
+ tools_names="",
+ stop_words=["Observation:"],
+ tools_description="",
+ tools_handler=mock_tools_handler,
+ )
+
+ async def delayed_response(*args: Any, **kwargs: Any) -> str:
+ await asyncio.sleep(0.05)
+ return f"Thought: Done\nFinal Answer: Result from executor {executor_id}"
+
+ with patch(
+ "crewai.agents.crew_agent_executor.aget_llm_response",
+ new_callable=AsyncMock,
+ side_effect=delayed_response,
+ ):
+ with patch.object(executor, "_show_start_logs"):
+ with patch.object(executor, "_show_logs"):
+ with patch.object(executor, "_create_short_term_memory"):
+ with patch.object(executor, "_create_long_term_memory"):
+ with patch.object(executor, "_create_external_memory"):
+ return await executor.ainvoke(
+ {
+ "input": f"test {executor_id}",
+ "tool_names": "",
+ "tools": "",
+ }
+ )
+
+ import time
+
+ start = time.time()
+ results = await asyncio.gather(
+ create_and_run_executor(1),
+ create_and_run_executor(2),
+ create_and_run_executor(3),
+ )
+ elapsed = time.time() - start
+
+ assert len(results) == 3
+ assert all("output" in r for r in results)
+ assert elapsed < 0.15, f"Expected concurrent execution, took {elapsed}s"
+
+
+class TestAsyncLLMResponseHelper:
+ """Tests for aget_llm_response helper function."""
+
+ @pytest.mark.asyncio
+ async def test_aget_llm_response_calls_acall(self) -> None:
+ """Test that aget_llm_response calls llm.acall."""
+ from crewai.utilities.agent_utils import aget_llm_response
+ from crewai.utilities.printer import Printer
+
+ mock_llm = MagicMock()
+ mock_llm.acall = AsyncMock(return_value="LLM response")
+
+ result = await aget_llm_response(
+ llm=mock_llm,
+ messages=[{"role": "user", "content": "test"}],
+ callbacks=[],
+ printer=Printer(),
+ )
+
+ mock_llm.acall.assert_called_once()
+ assert result == "LLM response"
+
+ @pytest.mark.asyncio
+ async def test_aget_llm_response_raises_on_empty_response(self) -> None:
+ """Test that aget_llm_response raises ValueError on empty response."""
+ from crewai.utilities.agent_utils import aget_llm_response
+ from crewai.utilities.printer import Printer
+
+ mock_llm = MagicMock()
+ mock_llm.acall = AsyncMock(return_value="")
+
+ with pytest.raises(ValueError, match="Invalid response from LLM call"):
+ await aget_llm_response(
+ llm=mock_llm,
+ messages=[{"role": "user", "content": "test"}],
+ callbacks=[],
+ printer=Printer(),
+ )
+
+ @pytest.mark.asyncio
+ async def test_aget_llm_response_propagates_exceptions(self) -> None:
+ """Test that aget_llm_response propagates LLM exceptions."""
+ from crewai.utilities.agent_utils import aget_llm_response
+ from crewai.utilities.printer import Printer
+
+ mock_llm = MagicMock()
+ mock_llm.acall = AsyncMock(side_effect=RuntimeError("LLM error"))
+
+ with pytest.raises(RuntimeError, match="LLM error"):
+ await aget_llm_response(
+ llm=mock_llm,
+ messages=[{"role": "user", "content": "test"}],
+ callbacks=[],
+ printer=Printer(),
+ )
\ No newline at end of file