Please read this first

• Have you read the docs? Yes, including the handoffs and tools pages.
• Have you searched for related issues? Yes. Handoff silently ignores strict_json_schema and coerces types #3723 / fix(handoffs): enforce strict Pydantic validation when strict_json_schema=True #3724 made handoffs validate strictly when strict_json_schema=True. This report is about what happens when that validation fails.

Describe the bug

When the model calls a function tool with arguments that fail validation, the SDK sends the error back to the model as the tool's output (failure_error_function, on by default) and the run continues. When the model calls a handoff with arguments that fail validation, handoff() raises ModelBehaviorError from on_invoke_handoff, and the whole run ends.

A strict schema doesn't prevent this everywhere. Only some providers enforce it while decoding. With others (we hit it with a Gemini model through LiteLLM), the model can still send a value the schema forbids. In our case the handoff's input was a Literal of the skills the agent currently has. The model named a skill it had used earlier in the conversation, which had since been removed, and the user's turn failed with a raw error instead of the model being told the value was invalid.

There is no option on handoff() or Handoff to change this, so the only workaround is a custom on_invoke_handoff that catches the validation error itself and hands back to the calling agent with a message.

Debug information

• Agents SDK version: v0.22.3, v0.24.0 and main at 9abc918
• Python version: 3.12
• Operating system: macOS
• Model and model provider: none; reproduced with agents.testing.ScriptedModel
• Does the issue reproduce with the latest Agents SDK release? Yes
• Does the issue occur consistently or intermittently? Consistently

Repro steps

import asyncio
from typing import Literal

from pydantic import BaseModel

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


class Pick(BaseModel):
    name: Literal["a"]


@function_tool
def pick(name: Literal["a"]) -> str:
    return f"picked {name}"


async def tool_case() -> None:
    model = ScriptedModel(
        [
            [function_call("pick", {"name": "b"}, call_id="1")],
            [assistant_message("done")],
        ]
    )
    result = await Runner.run(Agent(name="main", model=model, tools=[pick]), "go")
    print("function tool, invalid args ->", repr(result.final_output))


async def handoff_case() -> None:
    async def on_handoff(ctx, data: Pick) -> None:
        pass

    target = Agent(name="target", model=ScriptedModel([[assistant_message("hi")]]))
    h = handoff(target, on_handoff=on_handoff, input_type=Pick)
    model = ScriptedModel(
        [
            [function_call(h.tool_name, {"name": "b"}, call_id="1")],
            [assistant_message("done")],
        ]
    )
    try:
        result = await Runner.run(Agent(name="main", model=model, handoffs=[h]), "go")
        print("handoff, invalid args ->", repr(result.final_output))
    except Exception as exc:
        print("handoff, invalid args -> run raised", type(exc).__name__, exc)


async def main() -> None:
    await tool_case()
    await handoff_case()


asyncio.run(main())

Output on 0.22.3, 0.24.0 and main:

function tool, invalid args -> 'done'
handoff, invalid args -> run raised ModelBehaviorError Invalid JSON when parsing model output

Expected behavior

Invalid handoff arguments are handled the way invalid function tool arguments are: the error goes back to the model as the handoff call's output, the current agent stays in control, and the model can retry or answer without the handoff. A failure_error_function-style option on handoff() (default on, None to keep raising) would match the function tool API.