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

[georg-wolflein]

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.

Specifically, it enables the following syntax:

@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:

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

• I've added new tests (if relevant)
• I've added/updated the relevant documentation
• I've run make lint and make format
• I've made sure tests pass

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

[seratch]

Could you check the lint error?

uv run ruff check
tests/test_function_schema.py:1:1: I001 [*] Import block is un-sorted or un-formatted
   |
 1 | / from collections.abc import Mapping
 2 | | from enum import Enum
 3 | | from typing import Any, Literal
 4 | |
 5 | | import pytest
 6 | | from pydantic import BaseModel, ValidationError, Field
 7 | | from typing_extensions import TypedDict
 8 | |
 9 | | from agents import RunContextWrapper
10 | | from agents.exceptions import UserError
11 | | from agents.function_schema import function_schema
12 | |
13 | |
   | |__^ I001
14 |   def no_args_function():
15 |       """This function has no args."""
   |
   = help: Organize imports

Found 1 error.
[*] 1 fixable with the `--fix` option.
make: *** [Makefile:16: lint] Error 1
Error: Process completed with exit code 2.

[georg-wolflein]

Could you check the lint error?

Done:) @seratch

[seratch]

LGTM; @rm-openai can you take a look at this?

[rm-openai]

This is so good, thanks! @georg-wolflein in a follow up would also love some docs for this