feat(function_schema): Add support for pydantic Field annotations in tool arguments (for tools decorated with @function_schema) (#1124)

### Summary

This PR allows you to use the pydantic `Field` decorator to constrain
tool arguments for tools decorated with `@function_tool` (more
specifically, for tools using `function_schema` to parse tool
arguments). Such constrains include, e.g. limiting integers to a certain
range, but in principle, this should work for [any constrains supported
by the
API](https://platform.openai.com/docs/guides/structured-outputs?api-mode=responses#supported-properties).

Specifically, it enables the following syntax:
```python
@function_tool
def my_tool(age: int = Field(..., gt=0)) -> str:
    ...
```

Previously, one had to create a nested pydantic `BaseModel` to achieve
this functionality.
Issue #1123 explains this feature request and the previous workaround.

**Example:**
```python
import json

from pydantic import Field

from agents import function_tool


@function_tool
def my_tool(age: int = Field(..., gt=0)) -> str:
    return f"The age is {age}"


print(json.dumps(my_tool.params_json_schema, indent=2))
```
**Output:** (compare to #1123)
```
{
  "properties": {
    "age": {
      "exclusiveMinimum": 0,
      "title": "Age",
      "type": "integer"
    }
  },
  "required": [
    "age"
  ],
  "title": "my_tool_args",
  "type": "object",
  "additionalProperties": false
}
```

### Test plan

I added unit tests in `tests/test_function_schema.py`.

### Issue number

Closes #1123.

### Checks

- [x] I've added new tests (if relevant)
- [ ] I've added/updated the relevant documentation
- [x] I've run `make lint` and `make format`
- [x] I've made sure tests pass

**Note:** I am happy to add documentation for this; please point me to
where I should do so:)

Author: georg-wolflein

src/agents/function_schema.py

@@ -9,6 +9,7 @@
 
 from griffe import Docstring, DocstringSectionKind
 from pydantic import BaseModel, Field, create_model
+from pydantic.fields import FieldInfo
 
 from .exceptions import UserError
 from .run_context import RunContextWrapper
@@ -319,6 +320,14 @@ def function_schema(
                     ann,
                     Field(..., description=field_description),
                 )
+            elif isinstance(default, FieldInfo):
+                # Parameter with a default value that is a Field(...)
+                fields[name] = (
+                    ann,
+                    FieldInfo.merge_field_infos(
+                        default, description=field_description or default.description
+                    ),
+                )
             else:
                 # Parameter with a default value
                 fields[name] = (

tests/test_function_schema.py

@@ -3,7 +3,7 @@
 from typing import Any, Literal
 
 import pytest
-from pydantic import BaseModel, ValidationError
+from pydantic import BaseModel, Field, ValidationError
 from typing_extensions import TypedDict
 
 from agents import RunContextWrapper
@@ -451,3 +451,220 @@ def foo(x: int) -> int:
 
     assert fs.name == "custom"
     assert fs.params_json_schema.get("title") == "custom_args"
+
+
+def test_function_with_field_required_constraints():
+    """Test function with required Field parameter that has constraints."""
+
+    def func_with_field_constraints(my_number: int = Field(..., gt=10, le=100)) -> int:
+        return my_number * 2
+
+    fs = function_schema(func_with_field_constraints, use_docstring_info=False)
+
+    # Check that the schema includes the constraints
+    properties = fs.params_json_schema.get("properties", {})
+    my_number_schema = properties.get("my_number", {})
+    assert my_number_schema.get("type") == "integer"
+    assert my_number_schema.get("exclusiveMinimum") == 10  # gt=10
+    assert my_number_schema.get("maximum") == 100  # le=100
+
+    # Valid input should work
+    valid_input = {"my_number": 50}
+    parsed = fs.params_pydantic_model(**valid_input)
+    args, kwargs_dict = fs.to_call_args(parsed)
+    result = func_with_field_constraints(*args, **kwargs_dict)
+    assert result == 100
+
+    # Invalid input: too small (should violate gt=10)
+    with pytest.raises(ValidationError):
+        fs.params_pydantic_model(**{"my_number": 5})
+
+    # Invalid input: too large (should violate le=100)
+    with pytest.raises(ValidationError):
+        fs.params_pydantic_model(**{"my_number": 150})
+
+
+def test_function_with_field_optional_with_default():
+    """Test function with optional Field parameter that has default and constraints."""
+
+    def func_with_optional_field(
+        required_param: str,
+        optional_param: float = Field(default=5.0, ge=0.0),
+    ) -> str:
+        return f"{required_param}: {optional_param}"
+
+    fs = function_schema(func_with_optional_field, use_docstring_info=False)
+
+    # Check that the schema includes the constraints and description
+    properties = fs.params_json_schema.get("properties", {})
+    optional_schema = properties.get("optional_param", {})
+    assert optional_schema.get("type") == "number"
+    assert optional_schema.get("minimum") == 0.0  # ge=0.0
+    assert optional_schema.get("default") == 5.0
+
+    # Valid input with default
+    valid_input = {"required_param": "test"}
+    parsed = fs.params_pydantic_model(**valid_input)
+    args, kwargs_dict = fs.to_call_args(parsed)
+    result = func_with_optional_field(*args, **kwargs_dict)
+    assert result == "test: 5.0"
+
+    # Valid input with explicit value
+    valid_input2 = {"required_param": "test", "optional_param": 10.5}
+    parsed2 = fs.params_pydantic_model(**valid_input2)
+    args2, kwargs_dict2 = fs.to_call_args(parsed2)
+    result2 = func_with_optional_field(*args2, **kwargs_dict2)
+    assert result2 == "test: 10.5"
+
+    # Invalid input: negative value (should violate ge=0.0)
+    with pytest.raises(ValidationError):
+        fs.params_pydantic_model(**{"required_param": "test", "optional_param": -1.0})
+
+
+def test_function_with_field_description_merge():
+    """Test that Field descriptions are merged with docstring descriptions."""
+
+    def func_with_field_and_docstring(
+        param_with_field_desc: int = Field(..., description="Field description"),
+        param_with_both: str = Field(default="hello", description="Field description"),
+    ) -> str:
+        """
+        Function with both field and docstring descriptions.
+
+        Args:
+            param_with_field_desc: Docstring description
+            param_with_both: Docstring description
+        """
+        return f"{param_with_field_desc}: {param_with_both}"
+
+    fs = function_schema(func_with_field_and_docstring, use_docstring_info=True)
+
+    # Check that docstring description takes precedence when both exist
+    properties = fs.params_json_schema.get("properties", {})
+    param1_schema = properties.get("param_with_field_desc", {})
+    param2_schema = properties.get("param_with_both", {})
+
+    # The docstring description should be used when both are present
+    assert param1_schema.get("description") == "Docstring description"
+    assert param2_schema.get("description") == "Docstring description"
+
+
+def func_with_field_desc_only(
+    param_with_field_desc: int = Field(..., description="Field description only"),
+    param_without_desc: str = Field(default="hello"),
+) -> str:
+    return f"{param_with_field_desc}: {param_without_desc}"
+
+
+def test_function_with_field_description_only():
+    """Test that Field descriptions are used when no docstring info."""
+
+    fs = function_schema(func_with_field_desc_only)
+
+    # Check that field description is used when no docstring
+    properties = fs.params_json_schema.get("properties", {})
+    param1_schema = properties.get("param_with_field_desc", {})
+    param2_schema = properties.get("param_without_desc", {})
+
+    assert param1_schema.get("description") == "Field description only"
+    assert param2_schema.get("description") is None
+
+
+def test_function_with_field_string_constraints():
+    """Test function with Field parameter that has string-specific constraints."""
+
+    def func_with_string_field(
+        name: str = Field(..., min_length=3, max_length=20, pattern=r"^[A-Za-z]+$"),
+    ) -> str:
+        return f"Hello, {name}!"
+
+    fs = function_schema(func_with_string_field, use_docstring_info=False)
+
+    # Check that the schema includes string constraints
+    properties = fs.params_json_schema.get("properties", {})
+    name_schema = properties.get("name", {})
+    assert name_schema.get("type") == "string"
+    assert name_schema.get("minLength") == 3
+    assert name_schema.get("maxLength") == 20
+    assert name_schema.get("pattern") == r"^[A-Za-z]+$"
+
+    # Valid input
+    valid_input = {"name": "Alice"}
+    parsed = fs.params_pydantic_model(**valid_input)
+    args, kwargs_dict = fs.to_call_args(parsed)
+    result = func_with_string_field(*args, **kwargs_dict)
+    assert result == "Hello, Alice!"
+
+    # Invalid input: too short
+    with pytest.raises(ValidationError):
+        fs.params_pydantic_model(**{"name": "Al"})
+
+    # Invalid input: too long
+    with pytest.raises(ValidationError):
+        fs.params_pydantic_model(**{"name": "A" * 25})
+
+    # Invalid input: doesn't match pattern (contains numbers)
+    with pytest.raises(ValidationError):
+        fs.params_pydantic_model(**{"name": "Alice123"})
+
+
+def test_function_with_field_multiple_constraints():
+    """Test function with multiple Field parameters having different constraint types."""
+
+    def func_with_multiple_field_constraints(
+        score: int = Field(..., ge=0, le=100, description="Score from 0 to 100"),
+        name: str = Field(default="Unknown", min_length=1, max_length=50),
+        factor: float = Field(default=1.0, gt=0.0, description="Positive multiplier"),
+    ) -> str:
+        final_score = score * factor
+        return f"{name} scored {final_score}"
+
+    fs = function_schema(func_with_multiple_field_constraints, use_docstring_info=False)
+
+    # Check schema structure
+    properties = fs.params_json_schema.get("properties", {})
+
+    # Check score field
+    score_schema = properties.get("score", {})
+    assert score_schema.get("type") == "integer"
+    assert score_schema.get("minimum") == 0
+    assert score_schema.get("maximum") == 100
+    assert score_schema.get("description") == "Score from 0 to 100"
+
+    # Check name field
+    name_schema = properties.get("name", {})
+    assert name_schema.get("type") == "string"
+    assert name_schema.get("minLength") == 1
+    assert name_schema.get("maxLength") == 50
+    assert name_schema.get("default") == "Unknown"
+
+    # Check factor field
+    factor_schema = properties.get("factor", {})
+    assert factor_schema.get("type") == "number"
+    assert factor_schema.get("exclusiveMinimum") == 0.0
+    assert factor_schema.get("default") == 1.0
+    assert factor_schema.get("description") == "Positive multiplier"
+
+    # Valid input with defaults
+    valid_input = {"score": 85}
+    parsed = fs.params_pydantic_model(**valid_input)
+    args, kwargs_dict = fs.to_call_args(parsed)
+    result = func_with_multiple_field_constraints(*args, **kwargs_dict)
+    assert result == "Unknown scored 85.0"
+
+    # Valid input with all parameters
+    valid_input2 = {"score": 90, "name": "Alice", "factor": 1.5}
+    parsed2 = fs.params_pydantic_model(**valid_input2)
+    args2, kwargs_dict2 = fs.to_call_args(parsed2)
+    result2 = func_with_multiple_field_constraints(*args2, **kwargs_dict2)
+    assert result2 == "Alice scored 135.0"
+
+    # Test various validation errors
+    with pytest.raises(ValidationError):  # score too high
+        fs.params_pydantic_model(**{"score": 150})
+
+    with pytest.raises(ValidationError):  # empty name
+        fs.params_pydantic_model(**{"score": 50, "name": ""})
+
+    with pytest.raises(ValidationError):  # zero factor
+        fs.params_pydantic_model(**{"score": 50, "factor": 0.0})