refactor: improve type hints and add docstrings to agent adapters

src/crewai/agents/agent_adapters/base_agent_adapter.py

@@ -1,10 +1,41 @@
-from abc import ABC, abstractmethod
-from typing import Any, Dict, List, Optional
+"""Base adapter for integrating external agent implementations with CrewAI."""
 
-from pydantic import PrivateAttr
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import Any, TypedDict, Unpack
+
+from pydantic import ConfigDict, PrivateAttr
 
 from crewai.agent import BaseAgent
+from crewai.knowledge.knowledge import Knowledge
+from crewai.knowledge.source.base_knowledge_source import BaseKnowledgeSource
+from crewai.security.security_config import SecurityConfig
 from crewai.tools import BaseTool
+from crewai.utilities import I18N
+
+
+class AgentKwargs(TypedDict, total=False):
+    """TypedDict for BaseAgent initialization arguments."""
+
+    role: str
+    goal: str
+    backstory: str
+    config: dict[str, Any] | None
+    cache: bool
+    verbose: bool
+    max_rpm: int | None
+    allow_delegation: bool
+    tools: list[BaseTool] | None
+    max_iter: int
+    llm: Any
+    crew: Any
+    i18n: I18N
+    max_tokens: int | None
+    knowledge: Knowledge | None
+    knowledge_sources: list[BaseKnowledgeSource] | None
+    knowledge_storage: Any
+    security_config: SecurityConfig
+    callbacks: list[Callable[..., Any]]
 
 
 class BaseAgentAdapter(BaseAgent, ABC):
@@ -16,22 +47,31 @@ class BaseAgentAdapter(BaseAgent, ABC):
     """
 
     adapted_structured_output: bool = False
-    _agent_config: Optional[Dict[str, Any]] = PrivateAttr(default=None)
+    _agent_config: dict[str, Any] | None = PrivateAttr(default=None)
 
-    model_config = {"arbitrary_types_allowed": True}
+    model_config = ConfigDict(arbitrary_types_allowed=True)
 
-    def __init__(self, agent_config: Optional[Dict[str, Any]] = None, **kwargs: Any):
+    def __init__(
+        self,
+        agent_config: dict[str, Any] | None = None,
+        **kwargs: Unpack[AgentKwargs],
+    ) -> None:
+        """Initialize the base agent adapter.
+
+        Args:
+            agent_config: Optional configuration dictionary for the adapted agent.
+            **kwargs: BaseAgent initialization arguments (role, goal, backstory, etc).
+        """
         super().__init__(adapted_agent=True, **kwargs)
         self._agent_config = agent_config
 
     @abstractmethod
-    def configure_tools(self, tools: Optional[List[BaseTool]] = None) -> None:
+    def configure_tools(self, tools: list[BaseTool] | None = None) -> None:
         """Configure and adapt tools for the specific agent implementation.
 
         Args:
             tools: Optional list of BaseTool instances to be configured
         """
-        pass
 
     def configure_structured_output(self, structured_output: Any) -> None:
         """Configure the structured output for the specific agent implementation.
@@ -39,4 +79,3 @@ class BaseAgentAdapter(BaseAgent, ABC):
         Args:
             structured_output: The structured output to be configured
         """
-        pass

src/crewai/agents/agent_adapters/base_tool_adapter.py

@@ -1,5 +1,7 @@
+"""Base adapter for tool conversions across different agent frameworks."""
+
 from abc import ABC, abstractmethod
-from typing import Any, List, Optional
+from typing import Any
 
 from crewai.tools.base_tool import BaseTool
 
@@ -12,26 +14,39 @@ class BaseToolAdapter(ABC):
     different frameworks and platforms.
     """
 
-    original_tools: List[BaseTool]
-    converted_tools: List[Any]
+    def __init__(self, tools: list[BaseTool] | None = None) -> None:
+        """Initialize the tool adapter.
 
-    def __init__(self, tools: Optional[List[BaseTool]] = None):
-        self.original_tools = tools or []
-        self.converted_tools = []
+        Args:
+            tools: Optional list of BaseTool instances to be adapted.
+        """
+        self.original_tools: list[BaseTool] = tools or []
+        self.converted_tools: list[Any] = []
 
     @abstractmethod
-    def configure_tools(self, tools: List[BaseTool]) -> None:
+    def configure_tools(self, tools: list[BaseTool]) -> None:
         """Configure and convert tools for the specific implementation.
 
         Args:
-            tools: List of BaseTool instances to be configured and converted
+            tools: List of BaseTool instances to be configured and converted.
         """
-        pass
 
-    def tools(self) -> List[Any]:
-        """Return all converted tools."""
+    def tools(self) -> list[Any]:
+        """Return all converted tools.
+
+        Returns:
+            List of tools converted to the target framework format.
+        """
         return self.converted_tools
 
+    @abstractmethod
     def sanitize_tool_name(self, tool_name: str) -> str:
-        """Sanitize tool name for API compatibility."""
+        """Sanitize tool name for API compatibility.
+
+        Args:
+            tool_name: Original tool name that may contain spaces or special characters.
+
+        Returns:
+            Sanitized tool name with underscores replacing spaces.
+        """
         return tool_name.replace(" ", "_")