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

@@ -11,6 +11,7 @@
 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
@@ -25,7 +26,18 @@
 from .models.interface import Model
 from .prompts import DynamicPromptFunction, Prompt, PromptUtil
 from .run_context import RunContextWrapper, TContext
-from .tool import FunctionTool, FunctionToolResult, Tool, function_tool
+from .tool import (
+    CodeInterpreterTool,
+    ComputerTool,
+    FileSearchTool,
+    FunctionTool,
+    FunctionToolResult,
+    ImageGenerationTool,
+    LocalShellTool,
+    Tool,
+    WebSearchTool,
+    function_tool,
+)
 from .util import _transforms
 from .util._types import MaybeAwaitable
 
@@ -246,6 +258,29 @@ 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
+        for i, tool in enumerate(self.tools):
+            if not isinstance(
+                tool,
+                (
+                    FunctionTool,
+                    FileSearchTool,
+                    WebSearchTool,
+                    ComputerTool,
+                    LocalShellTool,
+                    ImageGenerationTool,
+                    CodeInterpreterTool,
+                    Handoff,
+                ),
+            ):
+                raise UserError(
+                    f"tools[{i}] must be a valid Tool object (FunctionTool, FileSearchTool, "
+                    f"WebSearchTool, ComputerTool, LocalShellTool, ImageGenerationTool, "
+                    f"CodeInterpreterTool, or Handoff), 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