perf: lazy-load MCP SDK and event types to reduce cold start by ~29% (#5584)

* perf: defer MCP SDK import by fixing import path in agent/core.py

- Change 'from crewai.mcp import MCPServerConfig' to direct path
  'from crewai.mcp.config import MCPServerConfig' to avoid triggering
  mcp/__init__.py which eagerly loads the full mcp SDK (~300-400ms)
- Move MCPToolResolver import into get_mcp_tools() method body since
  it's only used at runtime, not in type annotations

Saves ~200ms on 'import crewai' cold start.

* perf: lazy-load heavy MCP imports in mcp/__init__.py

MCPClient, MCPToolResolver, BaseTransport, and TransportType now use
__getattr__ lazy loading. These pull in the full mcp SDK (~400ms) but
are only needed at runtime when agents actually connect to MCP servers.

Lightweight config and filter types remain eagerly imported.

* perf: lazy-load all event type modules in events/__init__.py

Previously only agent_events were lazy-loaded; all other event type
modules (crew, flow, knowledge, llm, guardrail, logging, mcp, memory,
reasoning, skill, task, tool_usage) were eagerly imported at package
init time. Since events/__init__.py runs whenever ANY crewai.events.*
submodule is accessed, this loaded ~12 Pydantic model modules
unnecessarily.

Now all event types use the same __getattr__ lazy-loading pattern,
with TYPE_CHECKING imports preserved for IDE/type-checker support.

Saves ~550ms on 'import crewai' cold start.

* chore: remove UNKNOWN.egg-info from version control

* fix: add MCPToolResolver to TYPE_CHECKING imports

Fixes F821 (ruff) and name-defined (mypy) from lazy-loading the
MCP import. The type annotation on _mcp_resolver needs the name
available at type-check time.

* fix: bump lxml to >=5.4.0 for GHSA-vfmq-68hx-4jfw

lxml 5.3.2 has a known vulnerability. Bump to 5.4.0+ which
includes the fix (libxml2 2.13.8). The previous <5.4.0 pin
was for etree import issues that have since been resolved.

* fix: bump exclude-newer to 2026-04-22 for lxml 6.1.0 resolution

lxml 6.1.0 (GHSA fix) was released April 17 but the exclude-newer
date was set to April 17, missing it by timestamp. Bump to April 22.

* perf: add import time benchmark script

scripts/benchmark_import_time.py measures import crewai cold start
in fresh subprocesses. Supports --runs, --json (for CI), and
--threshold (fail if median exceeds N seconds).

The companion GitHub Action workflow needs to be pushed separately
(requires workflow scope).

* new action

* Potential fix for pull request finding 'CodeQL / Workflow does not contain permissions'

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

---------

Co-authored-by: Joao Moura <joaomdmoura@gmail.com>
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

lib/crewai-tools/pyproject.toml

@@ -112,7 +112,7 @@ github = [
 ]
 rag = [
     "python-docx>=1.1.0",
-    "lxml>=5.3.0,<5.4.0",  # Pin to avoid etree import issues in 5.4.0
+    "lxml>=6.1.0,<7",  # 6.1.0+ required for GHSA-vfmq-68hx-4jfw (XXE in iterparse)
 ]
 xml = [
     "unstructured[local-inference, all-docs]>=0.17.2"

lib/crewai/src/crewai/agent/core.py

@@ -78,8 +78,7 @@ from crewai.knowledge.knowledge import Knowledge
 from crewai.knowledge.source.base_knowledge_source import BaseKnowledgeSource
 from crewai.lite_agent_output import LiteAgentOutput
 from crewai.llms.base_llm import BaseLLM
-from crewai.mcp import MCPServerConfig
-from crewai.mcp.tool_resolver import MCPToolResolver
+from crewai.mcp.config import MCPServerConfig
 from crewai.rag.embeddings.types import EmbedderConfig
 from crewai.security.fingerprint import Fingerprint
 from crewai.skills.loader import activate_skill, discover_skills
@@ -119,6 +118,7 @@ if TYPE_CHECKING:
 
     from crewai.a2a.config import A2AClientConfig, A2AConfig, A2AServerConfig
     from crewai.agents.agent_builder.base_agent import PlatformAppOrAction
+    from crewai.mcp.tool_resolver import MCPToolResolver
     from crewai.task import Task
     from crewai.tools.base_tool import BaseTool
     from crewai.tools.structured_tool import CrewStructuredTool
@@ -1120,6 +1120,8 @@ class Agent(BaseAgent):
         Delegates to :class:`~crewai.mcp.tool_resolver.MCPToolResolver`.
         """
         self._cleanup_mcp_clients()
+        from crewai.mcp.tool_resolver import MCPToolResolver
+
         self._mcp_resolver = MCPToolResolver(agent=self, logger=self._logger)
         return self._mcp_resolver.resolve(mcps)
 

lib/crewai/src/crewai/events/__init__.py

@@ -6,112 +6,20 @@ This module provides the event infrastructure that allows users to:
 - Build custom logging and analytics
 - Extend CrewAI with custom event handlers
 - Declare handler dependencies for ordered execution
+
+Event type classes are lazy-loaded on first access to avoid importing
+~12 Pydantic model modules (and their transitive deps) at package init time.
 """
 
 from __future__ import annotations
 
+import importlib
 from typing import TYPE_CHECKING, Any
 
 from crewai.events.base_event_listener import BaseEventListener
 from crewai.events.depends import Depends
 from crewai.events.event_bus import crewai_event_bus
 from crewai.events.handler_graph import CircularDependencyError
-from crewai.events.types.crew_events import (
-    CrewKickoffCompletedEvent,
-    CrewKickoffFailedEvent,
-    CrewKickoffStartedEvent,
-    CrewTestCompletedEvent,
-    CrewTestFailedEvent,
-    CrewTestResultEvent,
-    CrewTestStartedEvent,
-    CrewTrainCompletedEvent,
-    CrewTrainFailedEvent,
-    CrewTrainStartedEvent,
-)
-from crewai.events.types.flow_events import (
-    FlowCreatedEvent,
-    FlowEvent,
-    FlowFinishedEvent,
-    FlowPlotEvent,
-    FlowStartedEvent,
-    HumanFeedbackReceivedEvent,
-    HumanFeedbackRequestedEvent,
-    MethodExecutionFailedEvent,
-    MethodExecutionFinishedEvent,
-    MethodExecutionStartedEvent,
-)
-from crewai.events.types.knowledge_events import (
-    KnowledgeQueryCompletedEvent,
-    KnowledgeQueryFailedEvent,
-    KnowledgeQueryStartedEvent,
-    KnowledgeRetrievalCompletedEvent,
-    KnowledgeRetrievalStartedEvent,
-    KnowledgeSearchQueryFailedEvent,
-)
-from crewai.events.types.llm_events import (
-    LLMCallCompletedEvent,
-    LLMCallFailedEvent,
-    LLMCallStartedEvent,
-    LLMStreamChunkEvent,
-)
-from crewai.events.types.llm_guardrail_events import (
-    LLMGuardrailCompletedEvent,
-    LLMGuardrailStartedEvent,
-)
-from crewai.events.types.logging_events import (
-    AgentLogsExecutionEvent,
-    AgentLogsStartedEvent,
-)
-from crewai.events.types.mcp_events import (
-    MCPConfigFetchFailedEvent,
-    MCPConnectionCompletedEvent,
-    MCPConnectionFailedEvent,
-    MCPConnectionStartedEvent,
-    MCPToolExecutionCompletedEvent,
-    MCPToolExecutionFailedEvent,
-    MCPToolExecutionStartedEvent,
-)
-from crewai.events.types.memory_events import (
-    MemoryQueryCompletedEvent,
-    MemoryQueryFailedEvent,
-    MemoryQueryStartedEvent,
-    MemoryRetrievalCompletedEvent,
-    MemoryRetrievalFailedEvent,
-    MemoryRetrievalStartedEvent,
-    MemorySaveCompletedEvent,
-    MemorySaveFailedEvent,
-    MemorySaveStartedEvent,
-)
-from crewai.events.types.reasoning_events import (
-    AgentReasoningCompletedEvent,
-    AgentReasoningFailedEvent,
-    AgentReasoningStartedEvent,
-    ReasoningEvent,
-)
-from crewai.events.types.skill_events import (
-    SkillActivatedEvent,
-    SkillDiscoveryCompletedEvent,
-    SkillDiscoveryStartedEvent,
-    SkillEvent,
-    SkillLoadFailedEvent,
-    SkillLoadedEvent,
-)
-from crewai.events.types.task_events import (
-    TaskCompletedEvent,
-    TaskEvaluationEvent,
-    TaskFailedEvent,
-    TaskStartedEvent,
-)
-from crewai.events.types.tool_usage_events import (
-    ToolExecutionErrorEvent,
-    ToolSelectionErrorEvent,
-    ToolUsageErrorEvent,
-    ToolUsageEvent,
-    ToolUsageFinishedEvent,
-    ToolUsageStartedEvent,
-    ToolValidateInputErrorEvent,
-)
-
 
 if TYPE_CHECKING:
     from crewai.events.types.agent_events import (
@@ -125,6 +33,223 @@ if TYPE_CHECKING:
         LiteAgentExecutionErrorEvent,
         LiteAgentExecutionStartedEvent,
     )
+    from crewai.events.types.crew_events import (
+        CrewKickoffCompletedEvent,
+        CrewKickoffFailedEvent,
+        CrewKickoffStartedEvent,
+        CrewTestCompletedEvent,
+        CrewTestFailedEvent,
+        CrewTestResultEvent,
+        CrewTestStartedEvent,
+        CrewTrainCompletedEvent,
+        CrewTrainFailedEvent,
+        CrewTrainStartedEvent,
+    )
+    from crewai.events.types.flow_events import (
+        FlowCreatedEvent,
+        FlowEvent,
+        FlowFinishedEvent,
+        FlowPlotEvent,
+        FlowStartedEvent,
+        HumanFeedbackReceivedEvent,
+        HumanFeedbackRequestedEvent,
+        MethodExecutionFailedEvent,
+        MethodExecutionFinishedEvent,
+        MethodExecutionStartedEvent,
+    )
+    from crewai.events.types.knowledge_events import (
+        KnowledgeQueryCompletedEvent,
+        KnowledgeQueryFailedEvent,
+        KnowledgeQueryStartedEvent,
+        KnowledgeRetrievalCompletedEvent,
+        KnowledgeRetrievalStartedEvent,
+        KnowledgeSearchQueryFailedEvent,
+    )
+    from crewai.events.types.llm_events import (
+        LLMCallCompletedEvent,
+        LLMCallFailedEvent,
+        LLMCallStartedEvent,
+        LLMStreamChunkEvent,
+    )
+    from crewai.events.types.llm_guardrail_events import (
+        LLMGuardrailCompletedEvent,
+        LLMGuardrailStartedEvent,
+    )
+    from crewai.events.types.logging_events import (
+        AgentLogsExecutionEvent,
+        AgentLogsStartedEvent,
+    )
+    from crewai.events.types.mcp_events import (
+        MCPConfigFetchFailedEvent,
+        MCPConnectionCompletedEvent,
+        MCPConnectionFailedEvent,
+        MCPConnectionStartedEvent,
+        MCPToolExecutionCompletedEvent,
+        MCPToolExecutionFailedEvent,
+        MCPToolExecutionStartedEvent,
+    )
+    from crewai.events.types.memory_events import (
+        MemoryQueryCompletedEvent,
+        MemoryQueryFailedEvent,
+        MemoryQueryStartedEvent,
+        MemoryRetrievalCompletedEvent,
+        MemoryRetrievalFailedEvent,
+        MemoryRetrievalStartedEvent,
+        MemorySaveCompletedEvent,
+        MemorySaveFailedEvent,
+        MemorySaveStartedEvent,
+    )
+    from crewai.events.types.reasoning_events import (
+        AgentReasoningCompletedEvent,
+        AgentReasoningFailedEvent,
+        AgentReasoningStartedEvent,
+        ReasoningEvent,
+    )
+    from crewai.events.types.skill_events import (
+        SkillActivatedEvent,
+        SkillDiscoveryCompletedEvent,
+        SkillDiscoveryStartedEvent,
+        SkillEvent,
+        SkillLoadFailedEvent,
+        SkillLoadedEvent,
+    )
+    from crewai.events.types.task_events import (
+        TaskCompletedEvent,
+        TaskEvaluationEvent,
+        TaskFailedEvent,
+        TaskStartedEvent,
+    )
+    from crewai.events.types.tool_usage_events import (
+        ToolExecutionErrorEvent,
+        ToolSelectionErrorEvent,
+        ToolUsageErrorEvent,
+        ToolUsageEvent,
+        ToolUsageFinishedEvent,
+        ToolUsageStartedEvent,
+        ToolValidateInputErrorEvent,
+    )
+
+# Map every event class name → its module path for lazy loading
+_LAZY_EVENT_MAPPING: dict[str, str] = {
+    # agent_events
+    "AgentEvaluationCompletedEvent": "crewai.events.types.agent_events",
+    "AgentEvaluationFailedEvent": "crewai.events.types.agent_events",
+    "AgentEvaluationStartedEvent": "crewai.events.types.agent_events",
+    "AgentExecutionCompletedEvent": "crewai.events.types.agent_events",
+    "AgentExecutionErrorEvent": "crewai.events.types.agent_events",
+    "AgentExecutionStartedEvent": "crewai.events.types.agent_events",
+    "LiteAgentExecutionCompletedEvent": "crewai.events.types.agent_events",
+    "LiteAgentExecutionErrorEvent": "crewai.events.types.agent_events",
+    "LiteAgentExecutionStartedEvent": "crewai.events.types.agent_events",
+    # crew_events
+    "CrewKickoffCompletedEvent": "crewai.events.types.crew_events",
+    "CrewKickoffFailedEvent": "crewai.events.types.crew_events",
+    "CrewKickoffStartedEvent": "crewai.events.types.crew_events",
+    "CrewTestCompletedEvent": "crewai.events.types.crew_events",
+    "CrewTestFailedEvent": "crewai.events.types.crew_events",
+    "CrewTestResultEvent": "crewai.events.types.crew_events",
+    "CrewTestStartedEvent": "crewai.events.types.crew_events",
+    "CrewTrainCompletedEvent": "crewai.events.types.crew_events",
+    "CrewTrainFailedEvent": "crewai.events.types.crew_events",
+    "CrewTrainStartedEvent": "crewai.events.types.crew_events",
+    # flow_events
+    "FlowCreatedEvent": "crewai.events.types.flow_events",
+    "FlowEvent": "crewai.events.types.flow_events",
+    "FlowFinishedEvent": "crewai.events.types.flow_events",
+    "FlowPlotEvent": "crewai.events.types.flow_events",
+    "FlowStartedEvent": "crewai.events.types.flow_events",
+    "HumanFeedbackReceivedEvent": "crewai.events.types.flow_events",
+    "HumanFeedbackRequestedEvent": "crewai.events.types.flow_events",
+    "MethodExecutionFailedEvent": "crewai.events.types.flow_events",
+    "MethodExecutionFinishedEvent": "crewai.events.types.flow_events",
+    "MethodExecutionStartedEvent": "crewai.events.types.flow_events",
+    # knowledge_events
+    "KnowledgeQueryCompletedEvent": "crewai.events.types.knowledge_events",
+    "KnowledgeQueryFailedEvent": "crewai.events.types.knowledge_events",
+    "KnowledgeQueryStartedEvent": "crewai.events.types.knowledge_events",
+    "KnowledgeRetrievalCompletedEvent": "crewai.events.types.knowledge_events",
+    "KnowledgeRetrievalStartedEvent": "crewai.events.types.knowledge_events",
+    "KnowledgeSearchQueryFailedEvent": "crewai.events.types.knowledge_events",
+    # llm_events
+    "LLMCallCompletedEvent": "crewai.events.types.llm_events",
+    "LLMCallFailedEvent": "crewai.events.types.llm_events",
+    "LLMCallStartedEvent": "crewai.events.types.llm_events",
+    "LLMStreamChunkEvent": "crewai.events.types.llm_events",
+    # llm_guardrail_events
+    "LLMGuardrailCompletedEvent": "crewai.events.types.llm_guardrail_events",
+    "LLMGuardrailStartedEvent": "crewai.events.types.llm_guardrail_events",
+    # logging_events
+    "AgentLogsExecutionEvent": "crewai.events.types.logging_events",
+    "AgentLogsStartedEvent": "crewai.events.types.logging_events",
+    # mcp_events
+    "MCPConfigFetchFailedEvent": "crewai.events.types.mcp_events",
+    "MCPConnectionCompletedEvent": "crewai.events.types.mcp_events",
+    "MCPConnectionFailedEvent": "crewai.events.types.mcp_events",
+    "MCPConnectionStartedEvent": "crewai.events.types.mcp_events",
+    "MCPToolExecutionCompletedEvent": "crewai.events.types.mcp_events",
+    "MCPToolExecutionFailedEvent": "crewai.events.types.mcp_events",
+    "MCPToolExecutionStartedEvent": "crewai.events.types.mcp_events",
+    # memory_events
+    "MemoryQueryCompletedEvent": "crewai.events.types.memory_events",
+    "MemoryQueryFailedEvent": "crewai.events.types.memory_events",
+    "MemoryQueryStartedEvent": "crewai.events.types.memory_events",
+    "MemoryRetrievalCompletedEvent": "crewai.events.types.memory_events",
+    "MemoryRetrievalFailedEvent": "crewai.events.types.memory_events",
+    "MemoryRetrievalStartedEvent": "crewai.events.types.memory_events",
+    "MemorySaveCompletedEvent": "crewai.events.types.memory_events",
+    "MemorySaveFailedEvent": "crewai.events.types.memory_events",
+    "MemorySaveStartedEvent": "crewai.events.types.memory_events",
+    # reasoning_events
+    "AgentReasoningCompletedEvent": "crewai.events.types.reasoning_events",
+    "AgentReasoningFailedEvent": "crewai.events.types.reasoning_events",
+    "AgentReasoningStartedEvent": "crewai.events.types.reasoning_events",
+    "ReasoningEvent": "crewai.events.types.reasoning_events",
+    # skill_events
+    "SkillActivatedEvent": "crewai.events.types.skill_events",
+    "SkillDiscoveryCompletedEvent": "crewai.events.types.skill_events",
+    "SkillDiscoveryStartedEvent": "crewai.events.types.skill_events",
+    "SkillEvent": "crewai.events.types.skill_events",
+    "SkillLoadFailedEvent": "crewai.events.types.skill_events",
+    "SkillLoadedEvent": "crewai.events.types.skill_events",
+    # task_events
+    "TaskCompletedEvent": "crewai.events.types.task_events",
+    "TaskEvaluationEvent": "crewai.events.types.task_events",
+    "TaskFailedEvent": "crewai.events.types.task_events",
+    "TaskStartedEvent": "crewai.events.types.task_events",
+    # tool_usage_events
+    "ToolExecutionErrorEvent": "crewai.events.types.tool_usage_events",
+    "ToolSelectionErrorEvent": "crewai.events.types.tool_usage_events",
+    "ToolUsageErrorEvent": "crewai.events.types.tool_usage_events",
+    "ToolUsageEvent": "crewai.events.types.tool_usage_events",
+    "ToolUsageFinishedEvent": "crewai.events.types.tool_usage_events",
+    "ToolUsageStartedEvent": "crewai.events.types.tool_usage_events",
+    "ToolValidateInputErrorEvent": "crewai.events.types.tool_usage_events",
+}
+
+_extension_exports: dict[str, Any] = {}
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import for event types and registered extensions."""
+    if name in _LAZY_EVENT_MAPPING:
+        module_path = _LAZY_EVENT_MAPPING[name]
+        module = importlib.import_module(module_path)
+        val = getattr(module, name)
+        globals()[name] = val  # cache for subsequent access
+        return val
+
+    if name in _extension_exports:
+        value = _extension_exports[name]
+        if isinstance(value, str):
+            module_path, _, attr_name = value.rpartition(".")
+            if module_path:
+                module = importlib.import_module(module_path)
+                return getattr(module, attr_name)
+            return importlib.import_module(value)
+        return value
+
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)
 
 
 __all__ = [
@@ -214,42 +339,3 @@ __all__ = [
     "_extension_exports",
     "crewai_event_bus",
 ]
-
-_AGENT_EVENT_MAPPING = {
-    "AgentEvaluationCompletedEvent": "crewai.events.types.agent_events",
-    "AgentEvaluationFailedEvent": "crewai.events.types.agent_events",
-    "AgentEvaluationStartedEvent": "crewai.events.types.agent_events",
-    "AgentExecutionCompletedEvent": "crewai.events.types.agent_events",
-    "AgentExecutionErrorEvent": "crewai.events.types.agent_events",
-    "AgentExecutionStartedEvent": "crewai.events.types.agent_events",
-    "LiteAgentExecutionCompletedEvent": "crewai.events.types.agent_events",
-    "LiteAgentExecutionErrorEvent": "crewai.events.types.agent_events",
-    "LiteAgentExecutionStartedEvent": "crewai.events.types.agent_events",
-}
-
-_extension_exports: dict[str, Any] = {}
-
-
-def __getattr__(name: str) -> Any:
-    """Lazy import for agent events and registered extensions."""
-    if name in _AGENT_EVENT_MAPPING:
-        import importlib
-
-        module_path = _AGENT_EVENT_MAPPING[name]
-        module = importlib.import_module(module_path)
-        return getattr(module, name)
-
-    if name in _extension_exports:
-        import importlib
-
-        value = _extension_exports[name]
-        if isinstance(value, str):
-            module_path, _, attr_name = value.rpartition(".")
-            if module_path:
-                module = importlib.import_module(module_path)
-                return getattr(module, attr_name)
-            return importlib.import_module(value)
-        return value
-
-    msg = f"module {__name__!r} has no attribute {name!r}"
-    raise AttributeError(msg)

lib/crewai/src/crewai/mcp/__init__.py

@@ -2,9 +2,17 @@
 
 This module provides native MCP client functionality, allowing CrewAI agents
 to connect to any MCP-compliant server using various transport types.
+
+Heavy imports (MCPClient, MCPToolResolver, BaseTransport, TransportType) are
+lazy-loaded on first access to avoid pulling in the ``mcp`` SDK (~400ms)
+when only lightweight config/filter types are needed.
 """
 
-from crewai.mcp.client import MCPClient
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
 from crewai.mcp.config import (
     MCPServerConfig,
     MCPServerHTTP,
@@ -18,8 +26,28 @@ from crewai.mcp.filters import (
     create_dynamic_tool_filter,
     create_static_tool_filter,
 )
-from crewai.mcp.tool_resolver import MCPToolResolver
-from crewai.mcp.transports.base import BaseTransport, TransportType
+
+if TYPE_CHECKING:
+    from crewai.mcp.client import MCPClient
+    from crewai.mcp.tool_resolver import MCPToolResolver
+    from crewai.mcp.transports.base import BaseTransport, TransportType
+
+_LAZY: dict[str, tuple[str, str]] = {
+    "MCPClient": ("crewai.mcp.client", "MCPClient"),
+    "MCPToolResolver": ("crewai.mcp.tool_resolver", "MCPToolResolver"),
+    "BaseTransport": ("crewai.mcp.transports.base", "BaseTransport"),
+    "TransportType": ("crewai.mcp.transports.base", "TransportType"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name in _LAZY:
+        mod_path, attr = _LAZY[name]
+        mod = importlib.import_module(mod_path)
+        val = getattr(mod, attr)
+        globals()[name] = val  # cache for subsequent access
+        return val
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
 __all__ = [