Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Invalid handoff arguments end the run, while invalid function tool arguments go back to the model

Open
  • Is something wrong?
#5,392 4 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
62/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
ai, backend-api-design

Research direction

Start by comparing handoff argument validation with the function tool path that returns validation errors through failure_error_function; the issue names handoff() and Handoff but no source or test files. Trace the on_invoke_handoff error path and add a regression test based on the ScriptedModel repro. Done when invalid handoff arguments can be returned to the model while the current agent retains control, with the proposed option allowing callers to keep raising.

Written by the indexing model from the issue text.

Description

Please read this first
  • Have you read the docs? Yes, including the handoffs and tools pages.
  • Have you searched for related issues? Yes. #3723 / #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 9abc9182
  • 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.

Dominant language
Python
Stars
30.2k
Forks
4.9k
Avg merge
12h 18m
Merged PRs (30d)
148

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from openai/openai-agents-python

All issues in openai/openai-agents-python

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.