Skip to content

Commit ee9a12a

Browse files
fix: preserve function tool Annotated constraints (#5212)
1 parent 220e307 commit ee9a12a

2 files changed

Lines changed: 178 additions & 18 deletions

File tree

‎src/agents/function_schema.py‎

Lines changed: 20 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -316,15 +316,6 @@ def _extract_description_from_metadata(metadata: tuple[Any, ...]) -> str | None:
316316
return None
317317

318318

319-
def _extract_field_info_from_metadata(metadata: tuple[Any, ...]) -> FieldInfo | None:
320-
"""Returns the first FieldInfo in Annotated metadata, or None."""
321-
322-
for item in metadata:
323-
if isinstance(item, FieldInfo):
324-
return item
325-
return None
326-
327-
328319
def function_schema(
329320
func: Callable[..., Any],
330321
docstring_style: DocstringStyle | None = None,
@@ -434,12 +425,18 @@ def function_schema(
434425
# If a docstring param description exists, use it
435426
field_description = param_descs.get(name, None)
436427

428+
# Let Pydantic combine all Field entries and retain other Annotated metadata,
429+
# including constrained type aliases and validators, in its original order.
430+
field_info_from_annotated = (
431+
FieldInfo.from_annotation(type_hints_with_extras[name])
432+
if param_metadata.get(name)
433+
else None
434+
)
437435
value_ann = ann
438436
if param.kind in (param.VAR_POSITIONAL, param.VAR_KEYWORD):
439-
field_info = _extract_field_info_from_metadata(param_metadata.get(name, ()))
440-
if field_info is not None and field_info.metadata:
437+
if field_info_from_annotated is not None and field_info_from_annotated.metadata:
441438
# Constraints apply to each value, not the collected container or its defaults.
442-
value_ann = Annotated[(ann, *cast(Any, field_info).metadata)]
439+
value_ann = Annotated[(ann, *cast(Any, field_info_from_annotated).metadata)]
443440

444441
# Handle different parameter kinds
445442
if param.kind == param.VAR_POSITIONAL:
@@ -493,9 +490,6 @@ def function_schema(
493490

494491
else:
495492
# Normal parameter
496-
metadata = param_metadata.get(name, ())
497-
field_info_from_annotated = _extract_field_info_from_metadata(metadata)
498-
499493
if field_info_from_annotated is not None:
500494
merged = FieldInfo.merge_field_infos(
501495
field_info_from_annotated,
@@ -504,7 +498,17 @@ def function_schema(
504498
if default is not inspect._empty and not isinstance(default, FieldInfo):
505499
merged = FieldInfo.merge_field_infos(merged, default=default)
506500
elif isinstance(default, FieldInfo):
507-
merged = FieldInfo.merge_field_infos(merged, default)
501+
merged = FieldInfo.from_annotated_attribute(
502+
cast(Any, Annotated[ann, merged]), default
503+
)
504+
if not any(
505+
isinstance(item, FieldInfo) for item in param_metadata.get(name, ())
506+
):
507+
# Without an Annotated Field, descriptions retain the same precedence
508+
# as a plain annotation with a Field default below.
509+
merged = FieldInfo.merge_field_infos(
510+
merged, description=field_description or default.description
511+
)
508512
fields[name] = (ann, merged)
509513
elif default is inspect._empty:
510514
# Required field

‎tests/test_function_schema.py‎

Lines changed: 158 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,15 @@
33
from typing import Annotated, Any, Literal
44

55
import pytest
6-
from pydantic import BaseModel, Field, ValidationError
6+
from pydantic import AfterValidator, BaseModel, Field, PositiveInt, TypeAdapter, ValidationError
77
from pydantic.json_schema import PydanticJsonSchemaWarning
88
from typing_extensions import TypedDict
99

10-
from agents import RunContextWrapper, function_tool
10+
from agents import Agent, RunConfig, RunContextWrapper, Runner, function_tool
11+
from agents.decorators import tool
1112
from agents.exceptions import ModelBehaviorError, UserError
1213
from agents.function_schema import function_schema, generate_func_documentation
14+
from agents.testing import ScriptedModel, function_call
1315

1416

1517
def no_args_function():
@@ -1432,3 +1434,157 @@ def test_to_call_args_allows_kwargs_key_matching_var_positional_param() -> None:
14321434
args, kwargs_dict = fs.to_call_args(parsed)
14331435

14341436
assert _kwargs_var_positional_name(*args, **kwargs_dict) == ((1,), {"rest": 5})
1437+
1438+
1439+
@pytest.mark.parametrize(
1440+
"annotation, invalid_value, bounds",
1441+
[
1442+
(PositiveInt, -1, {"exclusiveMinimum": 0}),
1443+
(Annotated[int, Field(ge=0), Field(le=10)], 20, {"minimum": 0, "maximum": 10}),
1444+
],
1445+
)
1446+
@pytest.mark.parametrize("kind", ["ordinary", "positional", "keyword"])
1447+
@pytest.mark.asyncio
1448+
async def test_annotated_constraints_reject_arguments_before_tool_execution(
1449+
annotation, invalid_value, bounds, kind
1450+
):
1451+
invocations = []
1452+
1453+
if kind == "ordinary":
1454+
1455+
def update_ordinary(ctx: Annotated[RunContextWrapper[None], "Context"], quantity):
1456+
invocations.append(quantity)
1457+
return str(quantity)
1458+
1459+
update_inventory = update_ordinary
1460+
valid_payload = {"quantity": 5}
1461+
invalid_payload = {"quantity": invalid_value}
1462+
elif kind == "positional":
1463+
1464+
def update_positional(*quantity):
1465+
invocations.extend(quantity)
1466+
return str(quantity[0])
1467+
1468+
update_inventory = update_positional
1469+
valid_payload = {"quantity": [5]}
1470+
invalid_payload = {"quantity": [invalid_value]}
1471+
else:
1472+
1473+
def update_keyword(**quantity):
1474+
invocations.extend(quantity.values())
1475+
return str(quantity["value"])
1476+
1477+
update_inventory = update_keyword
1478+
valid_payload = {"quantity": {"value": 5}}
1479+
invalid_payload = {"quantity": {"value": invalid_value}}
1480+
1481+
update_inventory.__annotations__["quantity"] = annotation
1482+
decorated = tool(
1483+
update_inventory,
1484+
name_override="update_inventory",
1485+
strict_mode=kind != "keyword",
1486+
failure_error_function=None,
1487+
)
1488+
value_schema = decorated.params_json_schema["properties"]["quantity"]
1489+
if kind != "ordinary":
1490+
value_schema = value_schema["items" if kind == "positional" else "additionalProperties"]
1491+
assert value_schema["type"] == "integer"
1492+
for key, value in bounds.items():
1493+
assert value_schema[key] == value
1494+
1495+
with pytest.raises(ValidationError):
1496+
TypeAdapter(annotation).validate_python(invalid_value)
1497+
1498+
async def run(payload):
1499+
agent = Agent(
1500+
name="inventory",
1501+
tools=[decorated],
1502+
model=ScriptedModel([[function_call("update_inventory", payload, call_id="call-1")]]),
1503+
tool_use_behavior="stop_on_first_tool",
1504+
)
1505+
return await Runner.run(
1506+
agent, "Update inventory", run_config=RunConfig(tracing_disabled=True)
1507+
)
1508+
1509+
with pytest.raises(ModelBehaviorError, match="Invalid JSON input for tool"):
1510+
await run(invalid_payload)
1511+
assert invocations == []
1512+
1513+
result = await run(valid_payload)
1514+
assert result.final_output == "5"
1515+
assert invocations == [5]
1516+
1517+
1518+
@pytest.mark.parametrize("default", [0, Field(default=0)])
1519+
def test_annotated_metadata_preserves_validator_order(default):
1520+
def add_one(value: int) -> int:
1521+
return value + 1
1522+
1523+
def double(value: int) -> int:
1524+
return value * 2
1525+
1526+
def func(
1527+
value: Annotated[
1528+
int, AfterValidator(add_one), Field(ge=0), AfterValidator(double)
1529+
] = default,
1530+
):
1531+
return value
1532+
1533+
fs = function_schema(func)
1534+
parsed = fs.params_pydantic_model.model_validate({"value": 2})
1535+
args, kwargs = fs.to_call_args(parsed)
1536+
assert func(*args, **kwargs) == 6
1537+
1538+
1539+
def test_annotated_fields_preserve_description_and_default_precedence():
1540+
def func(
1541+
quantity: Annotated[
1542+
int,
1543+
Field(default=1, ge=0, description="First field"),
1544+
Field(le=10, description="Second field"),
1545+
"Annotated description",
1546+
] = 5,
1547+
):
1548+
"""Update inventory.
1549+
1550+
Args:
1551+
quantity: Docstring description.
1552+
"""
1553+
return quantity
1554+
1555+
for use_docstring_info, expected_description in (
1556+
(True, "Docstring description."),
1557+
(False, "Annotated description"),
1558+
):
1559+
fs = function_schema(func, use_docstring_info=use_docstring_info)
1560+
quantity = fs.params_json_schema["properties"]["quantity"]
1561+
assert quantity["minimum"] == 0
1562+
assert quantity["maximum"] == 10
1563+
assert quantity["description"] == expected_description
1564+
assert quantity["default"] == 5
1565+
assert fs.params_pydantic_model().quantity == 5
1566+
1567+
1568+
def test_annotated_description_overrides_field_default_description():
1569+
def func(
1570+
quantity: Annotated[int, "Annotated description"] = Field(
1571+
default=5, ge=0, description="Default description"
1572+
),
1573+
):
1574+
"""Update inventory.
1575+
1576+
Args:
1577+
quantity: Docstring description.
1578+
"""
1579+
return quantity
1580+
1581+
for use_docstring_info, expected_description in (
1582+
(True, "Docstring description."),
1583+
(False, "Annotated description"),
1584+
):
1585+
fs = function_schema(func, use_docstring_info=use_docstring_info)
1586+
quantity = fs.params_json_schema["properties"]["quantity"]
1587+
assert quantity["description"] == expected_description
1588+
assert quantity["minimum"] == 0
1589+
assert quantity["default"] == 5
1590+
assert fs.params_pydantic_model().quantity == 5

0 commit comments

Comments
 (0)