PR #5737: refactor(agents): default Agent.executor_class to AgentExecutor

• Repository: crewAIInc/crewAI
• Author: carladams1299-lab
• State: open | merged: False
• Link: https://github.com/crewAIInc/crewAI/pull/5737

Description (problem / solution / changelog)

Closes #5736.

Summary

Two parallel agent executors currently coexist:

• crewai.agents.crew_agent_executor.CrewAgentExecutor (1,615 lines, the historical default for Agent.execute_task())
• crewai.experimental.agent_executor.AgentExecutor (2,963 lines, a Flow[AgentExecutorState], used unconditionally by Agent.kickoff() and exported from crewai/__init__.py)

Both subclass BaseAgentExecutor, expose invoke(), register the same hooks, and reuse the helpers in crewai.utilities.agent_utils. A single Agent instance can flow through either, depending on entry point — and _is_resuming_agent_executor() only works when agent_executor is an AgentExecutor, so checkpoint resume is silently broken under the current default.

This PR consolidates the runtime default without removing the legacy class:

• Agent.executor_class now defaults to AgentExecutor. Agent.kickoff() and Agent.execute_task() go through the same executor by default.
• CrewAgentExecutor.__init__ emits a DeprecationWarning pointing to #5736.
• Stale "instance of the CrewAgentExecutor class" docstrings updated.

Out of scope (follow-ups)

• Moving AgentExecutor out of crewai.experimental.* into crewai.agents.*. Touches ~27 files of imports and is mechanical — separate PR.
• Deleting CrewAgentExecutor. Needs at least one minor release of deprecation runway.
• Merging tests/agents/test_agent_executor.py and tests/agents/test_async_agent_executor.py along sync/async lines instead of legacy/experimental.
• Reasoning consolidation: handle_reasoning (crewai/agent/utils.py) and AgentExecutor.generate_plan() are intentional duals — both still work, the legacy helper is gated by if self.executor_class is not AgentExecutor (agent/core.py:515). Left alone here; they can converge after the legacy class is removed.

Files changed

Diff size: +15 / -7. No public API removed; existing user code that explicitly opts into executor_class=CrewAgentExecutor keeps working (with a warning).

Test plan

I was unable to run the test suite locally (no resolved venv on the dev machine). Reviewers should confirm:

• uv run pytest lib/crewai/tests/agents/ -x -q
• uv run pytest lib/crewai/tests/agents/test_async_agent_executor.py -x -q -W "default::DeprecationWarning" — this file directly instantiates CrewAgentExecutor and will now emit warnings; confirm none are promoted to errors elsewhere
• uv run pytest lib/crewai/tests/agents/test_agent.py -x -q
• uv run mypy lib/crewai/src/crewai/agent/core.py lib/crewai/src/crewai/agents/
• Spot-check that any test asserting executor_class == CrewAgentExecutor is either removed or updated (none found in a grep, but worth double-checking)

Risks I'm aware of:

• Downstream code that subclasses CrewAgentExecutor will now see a warning at instantiation. If their CI treats DeprecationWarning as an error, they'll need filterwarnings. The repo itself has no such global filter, so internal tests should be unaffected.
• Behavior change: Agent.execute_task() now runs through the Flow-based executor by default. The Flow path stores the plan in state.plan instead of mutating task.description (an intentional improvement noted in the source), but consumers that read task.description post-execution to recover the plan text will need to read agent_executor._state.plan instead.

Changed files

• lib/crewai/src/crewai/agent/core.py (modified, +5/-5)
• lib/crewai/src/crewai/agents/agent_builder/base_agent.py (modified, +2/-2)
• lib/crewai/src/crewai/agents/crew_agent_executor.py (modified, +8/-0)

PR #5738: Fix issue #5736: Agent.kickoff() must honor executor_class

• Repository: crewAIInc/crewAI
• Author: devin-ai-integration[bot]
• State: open | merged: False
• Link: https://github.com/crewAIInc/crewAI/pull/5738

Description (problem / solution / changelog)

Summary

Fixes #5736.

The two parallel agent-executor implementations — CrewAgentExecutor (legacy, default for Agent.executor_class) and the experimental AgentExecutor — had drifted enough that the Agent class silently routed kickoff() and execute_task() to different executors:

• Agent.execute_task() instantiated self.executor_class (default CrewAgentExecutor).
• Agent.kickoff() hard-coded AgentExecutor and ignored executor_class entirely.
• The reasoning-gate guard if self.executor_class is not AgentExecutor: handle_reasoning(...) coupled feature behavior to literal class identity, so any subclass of either executor that opted into or out of internal planning was handled incorrectly.

This PR replaces both class-identity checks with two ClassVar capability flags on BaseAgentExecutor:

• supports_internal_planning — whether the executor runs its own planning/replanning loop (and therefore should not have the external handle_reasoning step run before task execution).
• supports_kickoff — whether the executor implements the Flow-based Agent.kickoff() entry point.

AgentExecutor sets both to True; CrewAgentExecutor leaves both False (defaults from the base class). Agent now consults these flags:

• The reasoning gate is now if not getattr(self.executor_class, "supports_internal_planning", False): handle_reasoning(...).
• Agent.kickoff() routes through a new _resolve_kickoff_executor_class() helper. When the configured executor_class advertises supports_kickoff = True, that class is used verbatim. Otherwise — to preserve backwards compatibility for existing default-configured agents — the helper emits a DeprecationWarning and falls back to AgentExecutor. The warning message tells users how to silence it (executor_class=AgentExecutor).

A new test module lib/crewai/tests/agents/test_executor_consistency.py (12 tests) pins down the contract:

• Capability flags are correctly set on each executor class.
• Agent.kickoff() honors a kickoff-capable executor_class (including subclasses) without warning.
• Agent.kickoff() warns and falls back when executor_class does not opt into kickoff (default CrewAgentExecutor).
• Agent.execute_task() instantiates self.executor_class (regression guard for the existing path).
• The reasoning gate is driven by the capability flag, not class identity — so a CrewAgentExecutor subclass that opts into internal planning correctly skips handle_reasoning, and an AgentExecutor subclass that opts out correctly runs it.

Review & Testing Checklist for Human

• Confirm the deprecation-warning text is acceptable; in particular, confirm the wording ("The silent fallback will be removed in a future release.") aligns with the team's deprecation policy and target release.
• Decide whether Agent.kickoff() should eventually become a hard error when executor_class doesn't advertise supports_kickoff, or whether the deprecation-then-fallback approach is the long-term plan.
• Sanity-check that no downstream user-facing entry points other than kickoff() / execute_task() rely on the old self.executor_class is not AgentExecutor class-identity check (a repo-wide grep was clean, but a second pair of eyes is worth it).
• Run the recorded VCR test that exercises Agent.kickoff() with planning enabled to confirm the deprecation warning surfaces in real usage and that planning still produces a sensible plan when callers explicitly opt into executor_class=AgentExecutor.

Notes

• No changes to public AgentExecutor / CrewAgentExecutor constructor signatures or imports.
• The new _resolve_kickoff_executor_class() is private; the public surface stays the same.
• Lint (ruff check, ruff format --check) and mypy --strict pass on all touched source files. The full lib/crewai/tests/agents/ suite (108 tests across both executor paths) passes locally.

Link to Devin session: https://app.devin.ai/sessions/6be040b5f66d4cc797d36b5a7e144d59

Changed files

• lib/crewai/src/crewai/agent/core.py (modified, +37/-2)
• lib/crewai/src/crewai/agents/agent_builder/base_agent_executor.py (modified, +20/-1)
• lib/crewai/src/crewai/experimental/agent_executor.py (modified, +5/-1)
• lib/crewai/tests/agents/test_executor_consistency.py (added, +349/-0)