refactor(agents): default Agent.executor_class to AgentExecutor

[carladams1299-lab]

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 [BUG] Two parallel agent executors (CrewAgentExecutor vs experimental AgentExecutor) cover the same responsibility — pick a winner #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

File	Change
lib/crewai/src/crewai/agent/core.py	Default executor_class flipped; field description + Agent docstring + create_agent_executor docstring updated
lib/crewai/src/crewai/agents/agent_builder/base_agent.py	Stale agent_executor description corrected
lib/crewai/src/crewai/agents/crew_agent_executor.py	DeprecationWarning added in __init__; import warnings added

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.

[carladams1299-lab]

Hi, @greysonlalonde ,
Could you please review my PR?