Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
chore: add type annotations and docstrings to openai agent adapters (#3505)
Greyson LaLonde45d0c9912c4d
diff --git a/src/crewai/agents/agent_adapters/openai_agents/openai_adapter.py b/src/crewai/agents/agent_adapters/openai_agents/openai_adapter.pyindex f8524b80b..d241d5c55 100644--- a/src/crewai/agents/agent_adapters/openai_agents/openai_adapter.py+++ b/src/crewai/agents/agent_adapters/openai_agents/openai_adapter.py@@ -1,78 +1,99 @@-from typing import Any, List, Optional+"""OpenAI agents adapter for CrewAI integration.-from pydantic import Field, PrivateAttr+This module contains the OpenAIAgentAdapter class that integrates OpenAI Assistants+with CrewAI's agent system, providing tool integration and structured output support.+"""++from typing import Any, cast++from pydantic import ConfigDict, Field, PrivateAttr+from typing_extensions import Unpackfrom crewai.agents.agent_adapters.base_agent_adapter import BaseAgentAdapter+from crewai.agents.agent_adapters.openai_agents.openai_agent_tool_adapter import (+ OpenAIAgentToolAdapter,+)+from crewai.agents.agent_adapters.openai_agents.protocols import (+ AgentKwargs,+ OpenAIAgentsModule,+)+from crewai.agents.agent_adapters.openai_agents.protocols import (+ OpenAIAgent as OpenAIAgentProtocol,+)from crewai.agents.agent_adapters.openai_agents.structured_output_converter import (OpenAIConverterAdapter,)from crewai.agents.agent_builder.base_agent import BaseAgent-from crewai.tools import BaseTool-from crewai.tools.agent_tools.agent_tools import AgentTools-from crewai.utilities import Loggerfrom crewai.events.event_bus import crewai_event_busfrom crewai.events.types.agent_events import (AgentExecutionCompletedEvent,AgentExecutionErrorEvent,AgentExecutionStartedEvent,)--try:- from agents import Agent as OpenAIAgent # type: ignore- from agents import Runner, enable_verbose_stdout_logging # type: ignore-- from .openai_agent_tool_adapter import OpenAIAgentToolAdapter-- OPENAI_AVAILABLE = True-except ImportError:- OPENAI_AVAILABLE = False+from crewai.tools import BaseTool+from crewai.tools.agent_tools.agent_tools import AgentTools+from crewai.utilities import Logger+from crewai.utilities.import_utils import require++openai_agents_module = cast(+ OpenAIAgentsModule,+ require(+ "agents",+ purpose="OpenAI agents functionality",+ ),+)+OpenAIAgent = openai_agents_module.Agent+Runner = openai_agents_module.Runner+enable_verbose_stdout_logging = openai_agents_module.enable_verbose_stdout_loggingclass OpenAIAgentAdapter(BaseAgentAdapter):- """Adapter for OpenAI Assistants"""+ """Adapter for OpenAI Assistants.++ Integrates OpenAI Assistants API with CrewAI's agent system, providing+ tool configuration, structured output handling, and task execution.+ """- model_config = {"arbitrary_types_allowed": True}+ model_config = ConfigDict(arbitrary_types_allowed=True)- _openai_agent: "OpenAIAgent" = PrivateAttr()- _logger: Logger = PrivateAttr(default_factory=lambda: Logger())- _active_thread: Optional[str] = PrivateAttr(default=None)+ _openai_agent: OpenAIAgentProtocol = PrivateAttr()+ _logger: Logger = PrivateAttr(default_factory=Logger)+ _active_thread: str | None = PrivateAttr(default=None)function_calling_llm: Any = Field(default=None)step_callback: Any = Field(default=None)- _tool_adapter: "OpenAIAgentToolAdapter" = PrivateAttr()+ _tool_adapter: OpenAIAgentToolAdapter = PrivateAttr()_converter_adapter: OpenAIConverterAdapter = PrivateAttr()def __init__(self,- model: str = "gpt-4o-mini",- tools: Optional[List[BaseTool]] = None,- agent_config: Optional[dict] = None,- **kwargs,- ):- if not OPENAI_AVAILABLE:- raise ImportError(- "OpenAI Agent Dependencies are not installed. Please install it using `uv add openai-agents`"- )- else:- role = kwargs.pop("role", None)- goal = kwargs.pop("goal", None)- backstory = kwargs.pop("backstory", None)- super().__init__(- role=role,- goal=goal,- backstory=backstory,- tools=tools,- agent_config=agent_config,- **kwargs,- )- self._tool_adapter = OpenAIAgentToolAdapter(tools=tools)- self.llm = model- self._converter_adapter = OpenAIConverterAdapter(self)+ **kwargs: Unpack[AgentKwargs],+ ) -> None:+ """Initialize the OpenAI agent adapter.++ Args:+ **kwargs: All initialization arguments including role, goal, backstory,+ model, tools, and agent_config.++ Raises:+ ImportError: If OpenAI agent dependencies are not installed.+ """+ super().__init__(**kwargs)+ self._tool_adapter = OpenAIAgentToolAdapter(tools=kwargs.get("tools"))+ self.llm = kwargs.get("model", "gpt-4o-mini")+ self._converter_adapter = OpenAIConverterAdapter(agent_adapter=self)def _build_system_prompt(self) -> str:- """Build a system prompt for the OpenAI agent."""+ """Build a system prompt for the OpenAI agent.++ Creates a prompt containing the agent's role, goal, and backstory,+ then enhances it with structured output instructions if needed.++ Returns:+ The complete system prompt string.+ """base_prompt = f"""You are {self.role}.-+Your goal is: {self.goal}Your backstory: {self.backstory}@@ -84,10 +105,25 @@ class OpenAIAgentAdapter(BaseAgentAdapter):def execute_task(self,task: Any,- context: Optional[str] = None,- tools: Optional[List[BaseTool]] = None,+ context: str | None = None,+ tools: list[BaseTool] | None = None,) -> str:- """Execute a task using the OpenAI Assistant"""+ """Execute a task using the OpenAI Assistant.++ Configures the assistant, processes the task, and handles event emission+ for execution tracking.++ Args:+ task: The task object to execute.+ context: Optional context information for the task.+ tools: Optional additional tools for this execution.++ Returns:+ The final answer from the task execution.++ Raises:+ Exception: If task execution fails.+ """self._converter_adapter.configure_structured_output(task)self.create_agent_executor(tools)@@ -95,7 +131,7 @@ class OpenAIAgentAdapter(BaseAgentAdapter):enable_verbose_stdout_logging()try:- task_prompt = task.prompt()+ task_prompt: str = task.prompt()if context:task_prompt = self.i18n.slice("task_with_context").format(task=task_prompt, context=context@@ -109,8 +145,8 @@ class OpenAIAgentAdapter(BaseAgentAdapter):task=task,),)- result = self.agent_executor.run_sync(self._openai_agent, task_prompt)- final_answer = self.handle_execution_result(result)+ result: Any = self.agent_executor.run_sync(self._openai_agent, task_prompt)+ final_answer: str = self.handle_execution_result(result)crewai_event_bus.emit(self,event=AgentExecutionCompletedEvent(@@ -120,7 +156,7 @@ class OpenAIAgentAdapter(BaseAgentAdapter):return final_answerexcept Exception as e:- self._logger.log("error", f"Error executing OpenAI task: {str(e)}")+ self._logger.log("error", f"Error executing OpenAI task: {e!s}")crewai_event_bus.emit(self,event=AgentExecutionErrorEvent(@@ -131,15 +167,22 @@ class OpenAIAgentAdapter(BaseAgentAdapter):)raise- def create_agent_executor(self, tools: Optional[List[BaseTool]] = None) -> None:- """- Configure the OpenAI agent for execution.+ def create_agent_executor(self, tools: list[BaseTool] | None = None) -> None:+ """Configure the OpenAI agent for execution.+While OpenAI handles execution differently through Runner,- we can use this method to set up tools and configurations.+ this method sets up tools and agent configuration.++ Args:+ tools: Optional tools to configure for the agent.++ Notes:+ TODO: Properly type agent_executor in BaseAgent to avoid type issues+ when assigning Runner class to this attribute."""- all_tools = list(self.tools or []) + list(tools or [])+ all_tools: list[BaseTool] = list(self.tools or []) + list(tools or [])- instructions = self._build_system_prompt()+ instructions: str = self._build_system_prompt()self._openai_agent = OpenAIAgent(name=self.role,instructions=instructions,@@ -152,27 +195,48 @@ class OpenAIAgentAdapter(BaseAgentAdapter):self.agent_executor = Runner- def configure_tools(self, tools: Optional[List[BaseTool]] = None) -> None:- """Configure tools for the OpenAI Assistant"""+ def configure_tools(self, tools: list[BaseTool] | None = None) -> None:+ """Configure tools for the OpenAI Assistant.++ Args:+ tools: Optional tools to configure for the assistant.+ """if tools:self._tool_adapter.configure_tools(tools)if self._tool_adapter.converted_tools:self._openai_agent.tools = self._tool_adapter.converted_toolsdef handle_execution_result(self, result: Any) -> str:- """Process OpenAI Assistant execution result converting any structured output to a string"""+ """Process OpenAI Assistant execution result.++ Converts any structured output to a string through the converter adapter.++ Args:+ result: The execution result from the OpenAI assistant.++ Returns:+ Processed result as a string.+ """return self._converter_adapter.post_process_result(result.final_output)- def get_delegation_tools(self, agents: List[BaseAgent]) -> List[BaseTool]:- """Implement delegation tools support"""- agent_tools = AgentTools(agents=agents)- tools = agent_tools.tools()- return tools+ def get_delegation_tools(self, agents: list[BaseAgent]) -> list[BaseTool]:+ """Implement delegation tools support.++ Creates delegation tools that allow this agent to delegate tasks to other agents.++ Args:+ agents: List of agents available for delegation.++ Returns:+ List of delegation tools.+ """+ agent_tools: AgentTools = AgentTools(agents=agents)+ return agent_tools.tools()- def configure_structured_output(self, task) -> None:+ def configure_structured_output(self, task: Any) -> None:"""Configure the structured output for the specific agent implementation.Args:- structured_output: The structured output to be configured+ task: The task object containing output format specifications."""self._converter_adapter.configure_structured_output(task)diff --git a/src/crewai/agents/agent_adapters/openai_agents/openai_agent_tool_adapter.py b/src/crewai/agents/agent_adapters/openai_agents/openai_agent_tool_adapter.pyindex 92eeb7b00..6c8323a88 100644--- a/src/crewai/agents/agent_adapters/openai_agents/openai_agent_tool_adapter.py+++ b/src/crewai/agents/agent_adapters/openai_agents/openai_agent_tool_adapter.py@@ -1,57 +1,125 @@-import inspect-from typing import Any, List, Optional+"""OpenAI agent tool adapter for CrewAI tool integration.++This module contains the OpenAIAgentToolAdapter class that converts CrewAI tools+to OpenAI Assistant-compatible format using the agents library.+"""-from agents import FunctionTool, Tool+import inspect+import json+import re+from collections.abc import Awaitable+from typing import Any, castfrom crewai.agents.agent_adapters.base_tool_adapter import BaseToolAdapter+from crewai.agents.agent_adapters.openai_agents.protocols import (+ OpenAIFunctionTool,+ OpenAITool,+)from crewai.tools import BaseTool+from crewai.utilities.import_utils import require++agents_module = cast(+ Any,+ require(+ "agents",+ purpose="OpenAI agents functionality",+ ),+)+FunctionTool = agents_module.FunctionTool+Tool = agents_module.Toolclass OpenAIAgentToolAdapter(BaseToolAdapter):- """Adapter for OpenAI Assistant tools"""+ """Adapter for OpenAI Assistant tools.++ Converts CrewAI BaseTool instances to OpenAI Assistant FunctionTool format+ that can be used by OpenAI agents.+ """- def __init__(self, tools: Optional[List[BaseTool]] = None):- self.original_tools = tools or []+ def __init__(self, tools: list[BaseTool] | None = None) -> None:+ """Initialize the tool adapter.- def configure_tools(self, tools: List[BaseTool]) -> None:- """Configure tools for the OpenAI Assistant"""+ Args:+ tools: Optional list of CrewAI tools to adapt.+ """+ super().__init__()+ self.original_tools: list[BaseTool] = tools or []+ self.converted_tools: list[OpenAITool] = []++ def configure_tools(self, tools: list[BaseTool]) -> None:+ """Configure tools for the OpenAI Assistant.++ Merges provided tools with original tools and converts them to+ OpenAI Assistant format.++ Args:+ tools: List of CrewAI tools to configure.+ """if self.original_tools:- all_tools = tools + self.original_tools+ all_tools: list[BaseTool] = tools + self.original_toolselse:all_tools = toolsif all_tools:self.converted_tools = self._convert_tools_to_openai_format(all_tools)+ @staticmethoddef _convert_tools_to_openai_format(- self, tools: Optional[List[BaseTool]]- ) -> List[Tool]:- """Convert CrewAI tools to OpenAI Assistant tool format"""+ tools: list[BaseTool] | None,+ ) -> list[OpenAITool]:+ """Convert CrewAI tools to OpenAI Assistant tool format.++ Args:+ tools: List of CrewAI tools to convert.++ Returns:+ List of OpenAI Assistant FunctionTool instances.+ """if not tools:return []def sanitize_tool_name(name: str) -> str:- """Convert tool name to match OpenAI's required pattern"""- import re+ """Convert tool name to match OpenAI's required pattern.++ Args:+ name: Original tool name.++ Returns:+ Sanitized tool name matching OpenAI requirements.+ """++ return re.sub(r"[^a-zA-Z0-9_-]", "_", name).lower()- sanitized = re.sub(r"[^a-zA-Z0-9_-]", "_", name).lower()- return sanitized+ def create_tool_wrapper(tool: BaseTool) -> Any:+ """Create a wrapper function that handles the OpenAI function tool interface.- def create_tool_wrapper(tool: BaseTool):- """Create a wrapper function that handles the OpenAI function tool interface"""+ Args:+ tool: The CrewAI tool to wrap.++ Returns:+ Async wrapper function for OpenAI agent integration.+ """async def wrapper(context_wrapper: Any, arguments: Any) -> Any:+ """Wrapper function to adapt CrewAI tool calls to OpenAI format.++ Args:+ context_wrapper: OpenAI context wrapper.+ arguments: Tool arguments from OpenAI.++ Returns:+ Tool execution result.+ """# Get the parameter name from the schema- param_name = list(- tool.args_schema.model_json_schema()["properties"].keys()- )[0]+ param_name: str = next(+ iter(tool.args_schema.model_json_schema()["properties"].keys())+ )# Handle different argument types+ args_dict: dict[str, Any]if isinstance(arguments, dict):args_dict = argumentselif isinstance(arguments, str):try:- import json-args_dict = json.loads(arguments)except json.JSONDecodeError:args_dict = {param_name: arguments}@@ -59,11 +127,11 @@ class OpenAIAgentToolAdapter(BaseToolAdapter):args_dict = {param_name: str(arguments)}# Run the tool with the processed arguments- output = tool._run(**args_dict)+ output: Any | Awaitable[Any] = tool._run(**args_dict)# Await if the tool returned a coroutineif inspect.isawaitable(output):- result = await output+ result: Any = await outputelse:result = output@@ -74,17 +142,20 @@ class OpenAIAgentToolAdapter(BaseToolAdapter):return wrapper- openai_tools = []+ openai_tools: list[OpenAITool] = []for tool in tools:- schema = tool.args_schema.model_json_schema()+ schema: dict[str, Any] = tool.args_schema.model_json_schema()schema.update({"additionalProperties": False, "type": "object"})- openai_tool = FunctionTool(- name=sanitize_tool_name(tool.name),- description=tool.description,- params_json_schema=schema,- on_invoke_tool=create_tool_wrapper(tool),+ openai_tool: OpenAIFunctionTool = cast(+ OpenAIFunctionTool,+ FunctionTool(+ name=sanitize_tool_name(tool.name),+ description=tool.description,+ params_json_schema=schema,+ on_invoke_tool=create_tool_wrapper(tool),+ ),)openai_tools.append(openai_tool)diff --git a/src/crewai/agents/agent_adapters/openai_agents/protocols.py b/src/crewai/agents/agent_adapters/openai_agents/protocols.pynew file mode 100644index 000000000..f94cac5d8--- /dev/null+++ b/src/crewai/agents/agent_adapters/openai_agents/protocols.py@@ -0,0 +1,74 @@+"""Type protocols for OpenAI agents modules."""++from collections.abc import Callable+from typing import Any, Protocol, TypedDict, runtime_checkable++from crewai.tools.base_tool import BaseTool+++class AgentKwargs(TypedDict, total=False):+ """Typed dict for agent initialization kwargs."""++ role: str+ goal: str+ backstory: str+ model: str+ tools: list[BaseTool] | None+ agent_config: dict[str, Any] | None+++@runtime_checkable+class OpenAIAgent(Protocol):+ """Protocol for OpenAI Agent."""++ def __init__(+ self,+ name: str,+ instructions: str,+ model: str,+ **kwargs: Any,+ ) -> None:+ """Initialize the OpenAI agent."""+ ...++ tools: list[Any]+ output_type: Any+++@runtime_checkable+class OpenAIRunner(Protocol):+ """Protocol for OpenAI Runner."""++ @classmethod+ def run_sync(cls, agent: OpenAIAgent, message: str) -> Any:+ """Run agent synchronously with a message."""+ ...+++@runtime_checkable+class OpenAIAgentsModule(Protocol):+ """Protocol for OpenAI agents module."""++ Agent: type[OpenAIAgent]+ Runner: type[OpenAIRunner]+ enable_verbose_stdout_logging: Callable[[], None]+++@runtime_checkable+class OpenAITool(Protocol):+ """Protocol for OpenAI Tool."""+++@runtime_checkable+class OpenAIFunctionTool(Protocol):+ """Protocol for OpenAI FunctionTool."""++ def __init__(+ self,+ name: str,+ description: str,+ params_json_schema: dict[str, Any],+ on_invoke_tool: Any,+ ) -> None:+ """Initialize the function tool."""+ ...diff --git a/src/crewai/agents/agent_adapters/openai_agents/structured_output_converter.py b/src/crewai/agents/agent_adapters/openai_agents/structured_output_converter.pyindex 252374bf0..b7bb5d1d7 100644--- a/src/crewai/agents/agent_adapters/openai_agents/structured_output_converter.py+++ b/src/crewai/agents/agent_adapters/openai_agents/structured_output_converter.py@@ -1,5 +1,12 @@+"""OpenAI structured output converter for CrewAI task integration.++This module contains the OpenAIConverterAdapter class that handles structured+output conversion for OpenAI agents, supporting JSON and Pydantic model formats.+"""+import jsonimport re+from typing import Any, Literalfrom crewai.agents.agent_adapters.base_converter_adapter import BaseConverterAdapterfrom crewai.utilities.converter import generate_model_description@@ -7,8 +14,7 @@ from crewai.utilities.i18n import I18Nclass OpenAIConverterAdapter(BaseConverterAdapter):- """- Adapter for handling structured output conversion in OpenAI agents.+ """Adapter for handling structured output conversion in OpenAI agents.This adapter enhances the OpenAI agent to handle structured output formatsand post-processes the results when needed.@@ -19,19 +25,23 @@ class OpenAIConverterAdapter(BaseConverterAdapter):_output_model: The Pydantic model for the output"""- def __init__(self, agent_adapter):- """Initialize the converter adapter with a reference to the agent adapter"""- self.agent_adapter = agent_adapter- self._output_format = None- self._schema = None- self._output_model = None+ def __init__(self, agent_adapter: Any) -> None:+ """Initialize the converter adapter with a reference to the agent adapter.- def configure_structured_output(self, task) -> None:+ Args:+ agent_adapter: The OpenAI agent adapter instance."""- Configure the structured output for OpenAI agent based on task requirements.+ super().__init__(agent_adapter=agent_adapter)+ self.agent_adapter: Any = agent_adapter+ self._output_format: Literal["json", "pydantic"] | None = None+ self._schema: str | None = None+ self._output_model: Any = None++ def configure_structured_output(self, task: Any) -> None:+ """Configure the structured output for OpenAI agent based on task requirements.Args:- task: The task containing output format requirements+ task: The task containing output format requirements."""# Reset configurationself._output_format = None@@ -55,19 +65,18 @@ class OpenAIConverterAdapter(BaseConverterAdapter):self._output_model = task.output_pydanticdef enhance_system_prompt(self, base_prompt: str) -> str:- """- Enhance the base system prompt with structured output requirements if needed.+ """Enhance the base system prompt with structured output requirements if needed.Args:- base_prompt: The original system prompt+ base_prompt: The original system prompt.Returns:- Enhanced system prompt with output format instructions if needed+ Enhanced system prompt with output format instructions if needed."""if not self._output_format:return base_prompt- output_schema = (+ output_schema: str = (I18N().slice("formatted_task_instructions").format(output_format=self._schema)@@ -76,16 +85,15 @@ class OpenAIConverterAdapter(BaseConverterAdapter):return f"{base_prompt}\n\n{output_schema}"def post_process_result(self, result: str) -> str:- """- Post-process the result to ensure it matches the expected format.+ """Post-process the result to ensure it matches the expected format.This method attempts to extract valid JSON from the result if necessary.Args:- result: The raw result from the agent+ result: The raw result from the agent.Returns:- Processed result conforming to the expected output format+ Processed result conforming to the expected output format."""if not self._output_format:return result@@ -97,26 +105,30 @@ class OpenAIConverterAdapter(BaseConverterAdapter):return resultexcept json.JSONDecodeError:# Try to extract JSON from markdown code blocks- code_block_pattern = r"```(?:json)?\s*([\s\S]*?)```"- code_blocks = re.findall(code_block_pattern, result)+ code_block_pattern: str = r"```(?:json)?\s*([\s\S]*?)```"+ code_blocks: list[str] = re.findall(code_block_pattern, result)for block in code_blocks:+ stripped_block = block.strip()try:- json.loads(block.strip())- return block.strip()+ json.loads(stripped_block)+ return stripped_blockexcept json.JSONDecodeError:- continue+ pass# Try to extract any JSON-like structure- json_pattern = r"(\{[\s\S]*\})"- json_matches = re.findall(json_pattern, result, re.DOTALL)+ json_pattern: str = r"(\{[\s\S]*\})"+ json_matches: list[str] = re.findall(json_pattern, result, re.DOTALL)for match in json_matches:+ is_valid = Truetry:json.loads(match)- return matchexcept json.JSONDecodeError:- continue+ is_valid = False++ if is_valid:+ return match# If all extraction attempts fail, return the originalreturn str(result)