Return validation error details to LLM on function call argument failures

[Olivier-tl]

Feature Type

Would make my life easier

Feature Description

When the LLM makes a function call with invalid arguments (e.g., missing required fields, wrong types, invalid enum values), Livekit attempts to parse the arguments in a pydantic model (see here) which raises a ValidationError. Livekit does catch the exception and generate a tool output (see here). However it hardcodes "An internal error occurred" in the output (see here). This gives the LLM no feedback about what was wrong with its arguments, so it has no signal to self-correct.

Potential fix: catching the pydantic ValidationError and raising a ToolError would fix it, as tool errors are surfaced to the LLM (see here).

Workarounds / Alternatives

No response

Additional Context

No response

[weiguangli-io]

Root Cause

In livekit-agents/livekit/agents/llm/utils.py, the flow is:

1. Line 398 – model_type.model_validate(args_dict) raises a pydantic ValidationError when LLM-supplied arguments are invalid (wrong type, missing required field, bad enum value, etc.).
2. Line 605 – execute_function_call catches it as a generic Exception and passes it to make_function_call_output(…, exception=e).
3. Line 524-530 – make_function_call_output only special-cases ToolError and StopResponse; every other exception (including ValidationError) falls through to the catch-all branch that hardcodes output="An internal error occurred".

The LLM never sees what was actually wrong with its arguments, so it has no signal to self-correct.

Proposed Fix

In execute_function_call (line 593-610), catch pydantic.ValidationError separately before the generic except Exception and re-raise it as a ToolError with the validation details. This way the existing ToolError handling in make_function_call_output (line 503-513) surfaces the message to the LLM:

from pydantic import ValidationError

try:
    fnc_args, fnc_kwargs = prepare_function_arguments(...)
    result = function_tool(*fnc_args, **fnc_kwargs)
    if asyncio.iscoroutine(result):
        result = await result
    return make_function_call_output(fnc_call=fnc_call, output=result, exception=None)

except ValidationError as e:
    logger.warning(
        f"validation error for AI function `{tool_call.name}`",
        extra={"call_id": tool_call.call_id, "arguments": tool_call.arguments},
    )
    tool_error = ToolError(f"Invalid arguments: {e}")
    return make_function_call_output(fnc_call=fnc_call, output=None, exception=tool_error)

except Exception as e:
    logger.exception(...)
    return make_function_call_output(fnc_call=fnc_call, output=None, exception=e)

This is minimal and non-breaking – ValidationError from argument parsing is the only new case, and ToolError.message is already wired to be returned to the LLM.

Happy to submit a PR if this approach looks good.

[Olivier-tl]

The PR looks great, thanks for the quick fix 🙌