fix: validate tool types in Agent.tools list to prevent runtime AttributeError (fixes #1443)

This fix addresses issue #1443 where passing invalid tool types (e.g., raw
functions instead of FunctionTool objects) in the tools list would pass
initialization but fail at runtime with:

  AttributeError: 'function' object has no attribute 'name'
  (in src/agents/run.py line 584)

Changes:
- Added validation in Agent.__post_init__ to check each tool in the list
- Invalid tools now raise UserError at initialization with helpful message
- Suggests using @function_tool decorator when raw functions are detected

This provides better developer experience by:
1. Catching errors early (at init vs runtime)
2. Providing clear error messages
3. Suggesting the correct fix

Test Coverage:
- Added test_tools_content_validation_issue_1443 with 3 test cases
- Tests raw functions, strings, and mixed valid/invalid tools
- Verifies correct error index is reported

Author: gn00295120

src/agents/agent.py

@@ -5,12 +5,13 @@
 import inspect
 from collections.abc import Awaitable
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, Callable, Generic, Literal, cast
+from typing import TYPE_CHECKING, Any, Callable, Generic, Literal, cast, get_args
 
 from openai.types.responses.response_prompt_param import ResponsePromptParam
 from typing_extensions import NotRequired, TypeAlias, TypedDict
 
 from .agent_output import AgentOutputSchemaBase
+from .exceptions import UserError
 from .guardrail import InputGuardrail, OutputGuardrail
 from .handoffs import Handoff
 from .items import ItemHelpers
@@ -246,6 +247,21 @@ def __post_init__(self):
         if not isinstance(self.tools, list):
             raise TypeError(f"Agent tools must be a list, got {type(self.tools).__name__}")
 
+        # Validate each tool is a valid Tool type
+        # Tool is a Union type, so we need to get the valid types from it
+        valid_tool_types = get_args(Tool) + (Handoff,)
+
+        for i, tool in enumerate(self.tools):
+            if not isinstance(tool, valid_tool_types):
+                # Generate a friendly list of valid types for the error message
+                type_names = ", ".join(t.__name__ for t in valid_tool_types)
+                raise UserError(
+                    f"tools[{i}] must be a valid Tool object ({type_names}), "
+                    f"got {type(tool).__name__}. "
+                    f"Did you forget to use @function_tool decorator or pass the function itself "
+                    f"instead of a tool?"
+                )
+
         if not isinstance(self.mcp_servers, list):
             raise TypeError(
                 f"Agent mcp_servers must be a list, got {type(self.mcp_servers).__name__}"

tests/test_agent_config.py

@@ -214,6 +214,49 @@ def test_list_field_validation(self):
         with pytest.raises(TypeError, match="Agent handoffs must be a list"):
             Agent(name="test", handoffs="not_a_list")  # type: ignore
 
+    def test_tools_content_validation_issue_1443(self):
+        """Test that tools list validates each element is a valid Tool object (Issue #1443)
+
+        This test addresses the issue where passing invalid tool types (e.g., raw functions)
+        in a list would pass __post_init__ validation but fail later at runtime with:
+        AttributeError: 'function' object has no attribute 'name'
+
+        The fix validates each tool in the list during initialization.
+        """
+        from agents.exceptions import UserError
+
+        def raw_function():
+            """A raw function, not decorated with @function_tool"""
+            return "test"
+
+        # Case 1: Raw function in tools list should raise UserError at init
+        with pytest.raises(
+            UserError,
+            match=r"tools\[0\] must be a valid Tool object.*got function.*@function_tool",
+        ):
+            Agent(name="test", tools=[raw_function])  # type: ignore
+
+        # Case 2: String in tools list should raise UserError at init
+        with pytest.raises(
+            UserError,
+            match=r"tools\[0\] must be a valid Tool object.*got str",
+        ):
+            Agent(name="test", tools=["invalid_string"])  # type: ignore
+
+        # Case 3: Mixed valid and invalid tools - should catch invalid at correct index
+        from agents import function_tool
+
+        @function_tool
+        def valid_tool() -> str:
+            """A valid tool"""
+            return "ok"
+
+        with pytest.raises(
+            UserError,
+            match=r"tools\[1\] must be a valid Tool object.*got str",
+        ):
+            Agent(name="test", tools=[valid_tool, "invalid"])  # type: ignore
+
     def test_model_settings_validation(self):
         """Test model_settings validation - prevents runtime errors"""
         # Valid case