Skip to content

function_tool rejects valid arguments when a parameter uses Pydantic strict mode (Enum, date, UUID) #5448

Open

Description

@TheSaiEaranti

Please read this first

Describe the bug

When a @function_tool parameter uses Pydantic strict mode (ConfigDict(strict=True), Field(strict=True) or Strict()), arguments that match the tool's own params_json_schema are rejected for Enum, date, datetime, UUID and tuple fields. The tool never runs, and the model only gets "An error occurred while running the tool. Please try again." The same model and the same JSON work as an output_type and as a handoff input_type. This is Pydantic's strictness, not the SDK's strict_mode option.

_prepare_arguments decodes the JSON arguments with json.loads (tool.py#L1967) and validates the dict with schema.params_pydantic_model(**validation_input) (tool.py#L2787-L2791), which is Pydantic's Python mode. In strict mode, Python mode only accepts real Enum, date or UUID instances, while JSON mode also accepts the strings the schema asks for. The Pydantic docs say "strict mode is looser when validating from JSON". output_type and handoff inputs are validated in JSON mode (agent_output.py#L148-L153, handoffs/__init__.py#L358-L364), so the same model works there.

Agent.as_tool(parameters=...) fails the same way, because it calls params_adapter.validate_python(json_data) (agent.py#L761). A strict Pydantic dataclass fails at both call sites even when it only has str and int fields (dataclass_exact_type).

Debug information

  • Agents SDK version: 0.24.0, and main at cd26bbb
  • Related library versions: pydantic 2.12.3, pydantic-core 2.41.4
  • Python version: 3.12.7
  • Operating system: macOS 26.6.2
  • Model and model provider: none, offline repro with agents.testing.ScriptedModel
  • Does the issue reproduce with the latest Agents SDK release? Yes
  • Does the issue occur consistently or intermittently? Consistently

Output of OPENAI_AGENTS_DISABLE_TRACING=1 python repro.py with the script below, the same on 0.24.0 and main. tool ran: is never printed.

model got: ['An error occurred while running the tool. Please try again.']
output_type: priority=<Priority.HIGH: 'high'> due=datetime.date(2026, 11, 1)

By default the error only says Invalid JSON input for tool create_ticket, though the JSON is valid. With OPENAI_AGENTS_DONT_LOG_TOOL_DATA=0 the SDK logs the Pydantic errors: Input should be an instance of Priority [type=is_instance_of, input_value='high', input_type=str] for ticket.priority and Input should be a valid date [type=date_type, input_value='2026-11-01', input_type=str] for ticket.due.

Repro steps

import asyncio
import datetime
import enum
import json

from pydantic import BaseModel, ConfigDict

from agents import Agent, Runner, function_tool
from agents.testing import ScriptedModel, assistant_message, function_call


class Priority(enum.Enum):
    LOW = "low"
    HIGH = "high"


class Ticket(BaseModel):
    model_config = ConfigDict(strict=True)
    priority: Priority
    due: datetime.date


@function_tool
def create_ticket(ticket: Ticket) -> str:
    print("tool ran:", ticket)
    return "created"


ticket = {"priority": "high", "due": "2026-11-01"}


async def main() -> None:
    call = function_call("create_ticket", {"ticket": ticket}, call_id="c1")
    model = ScriptedModel([[call], [assistant_message("ok")]])
    result = await Runner.run(Agent(name="a", model=model, tools=[create_ticket]), "file it")
    outputs = [i.output for i in result.new_items if i.type == "tool_call_output_item"]
    print("model got:", outputs)

    # The same model accepts the same JSON as an output_type.
    model = ScriptedModel([[assistant_message(json.dumps(ticket))]])
    result = await Runner.run(Agent(name="b", model=model, output_type=Ticket), "x")
    print("output_type:", result.final_output)


asyncio.run(main())

Expected behavior

Arguments that match the tool's schema validate and the tool runs, as with output_type.

Suggested fix

Keep the Python-mode call and retry in JSON mode only when it raises ValidationError. In _create_function_tool, next to _prepare_arguments:

        def _validate_arguments(data: dict[str, Any]) -> BaseModel:
            try:
                return (
                    schema.params_pydantic_model(**data) if data else schema.params_pydantic_model()
                )
            except ValidationError:
                pass
            # Tool arguments are JSON. In strict mode, Python mode rejects the JSON form of
            # Enum, date, UUID or tuple values, so retry in JSON mode.
            return schema.params_pydantic_model.model_validate_json(json.dumps(data))

Then parsed = _validate_arguments(validation_input) replaces L2787-L2791. as_tool needs the same pattern at agent.py#L761, retrying with params_adapter.validate_json(json.dumps(data)) (agent.py doesn't import json yet). With both changes the repro runs the tool (model got: ['created']), a strict int still rejects "5", and the test suite gives the same results as on main. Calls that validate today never reach the retry, so they don't change.

Validating in JSON mode every time would also fix this, but it changes what some existing non-strict tools receive. With pydantic 2.12.3, a Path | str parameter gets PosixPath('notes.txt') instead of 'notes.txt', and a Decimal parameter sent 5.0 gets Decimal('5') instead of Decimal('5.0'). That's why I'd go with the fallback, but either works for the strict cases.

For tests, I'd cover only the strict cases: a strict model with Enum, date and UUID fields and a strict dataclass, through @function_tool and as_tool(parameters=...), plus a check that a strict int still rejects "5".

Activity

  1. Lahari25 commented on Oct 29, 2026

    @Lahari25

    I'd like to take this. I reproduced it on main (cd26bbb) for @function_tool with ConfigDict(strict=True) and Field(strict=True), and for Agent.as_tool(parameters=...). I also confirmed your note about always using JSON mode: a Path | str parameter gets PosixPath('notes.txt') and a Decimal sent as 5.0 becomes Decimal('5'). So I went with the fallback you suggested: Python mode first, JSON mode only on failure, at both call sites. That comes with regression tests for the strict cases and a guard test that non-strict values are unchanged. PR shortly.

  2. Lahari25 commented on Oct 29, 2026

    @Lahari25

    The fix and tests are ready on my fork: Lahari25/openai-agents-python@main...fix/strict-tool-args-json-mode (+256/−7, merges cleanly; full suite passes locally). PRs from non-collaborators are currently disabled here, so I'm leaving it linked in case it's useful.

  3. MagicBeards commented on Nov 18, 2026

    @MagicBeards

    Now that #6067 has landed, one thing worth settling here, because it looks like the same fix but I do not think it should take the same shape.

    #6067 made JSON validation opt-in for the Codex tool (parameter_validation_mode="json"), keeping Python-mode as the default. That fits that call site: parameters_model comes from resolved_options.parameters (codex_tool.py:316), so the caller supplies the model and may rely on Python-mode semantics somewhere else. Defaulting to JSON mode would change behaviour the caller never opted into.

    function_tool is a different case on both points:

    • the model is not caller-supplied. params_pydantic_model is generated by the SDK from the function signature (function_schema.py:551), so there is no other consumer with Python-mode expectations to protect;
    • the arguments are always JSON. _prepare_arguments receives the model's raw JSON string and nothing else, so Python-mode validation can never succeed for a strict date, UUID, Enum or tuple field. The tool's own params_json_schema advertises exactly the JSON forms that Python mode rejects — {"format": "date", "type": "string"} — so the current behaviour refuses what it promised.

    So my reading is that JSON-mode should be the default here rather than an option, and adding a flag would mean two validation modes where only one can ever work. That is also what the model-output path, handoff input_type and the sandbox tools already do — function_tool is the only remaining caller that validates a JSON payload in Python mode.

    The reason I am raising it rather than just sending the patch: if you would rather function_tool also get an opt-in switch for symmetry with #6067, that is a different diff (a ModelSettings-shaped option plus a compatibility default), and I would rather write the one you want than guess.

    Two things the change does affect, both worth stating up front:

    • a Pydantic plugin that registers only a Python-mode handler stops observing tool argument validation, because Pydantic wraps validate_python and validate_json separately. A JSON-mode handler observes it instead, which is what the model-output and handoff paths already require.
    • json.loads accepts an unpaired surrogate escape such as {"a": "\ud800"} while Pydantic's parser rejects it, so that input moves from "runs the tool" to ModelBehaviorError. A parity sweep of the common lax coercions found no other difference between the two modes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions