Fix empty tool calls and arguments in OpenAI compatible models #80

Jameswlepage · 2025-09-02T01:42:28Z

Summary

Fixes critical API compatibility issues when AI models make function/tool calls with no parameters. The SDK was generating invalid payloads rejected by OpenAI and Anthropic APIs.

Changes

Fix empty tool_calls handling: Only include tool_calls field when array contains items (OpenAI rejects empty arrays)
Fix empty arguments encoding: Convert empty PHP arrays to objects before JSON encoding (APIs expect {} not [] for empty parameters)
Add test coverage: New tests for both edge cases to prevent regression

Technical Details

The issue manifests in two ways:

OpenAI API Error: Invalid 'messages[X].tool_calls': empty array. Expected at least one item
- Occurs when tool_calls: [] is included in messages
- Fixed by conditionally including the field only when non-empty
Anthropic API Error: messages.X.content.0.tool_use.input: Input should be a valid dictionary
- Occurs when empty arguments encode as "[]" instead of "{}"
- Fixed by converting empty arrays to objects before JSON encoding

Testing

# Run new tests
./vendor/bin/phpunit --filter="testGetMessagePartToolCallDataEmptyArguments|testPrepareMessagesParamNoToolCalls"

# Verify all tests pass
composer run phpunit  # 878 tests, 3547 assertions ✓
composer run phpstan  # No errors ✓

Impact

Enables WordPress Abilities API integration (many parameterless functions)
Fixes production failures with function calling
Maintains full backward compatibility

Related

Community reports: OpenAI empty tool_calls error
Similar issues reported with Anthropic's Claude API in August 2024

- Only include tool_calls field when there are actual tool calls (OpenAI rejects empty arrays) - Convert empty argument arrays to objects in JSON encoding (both OpenAI and Anthropic require objects) - Add comprehensive test coverage for both edge cases This fixes critical API failures when AI models make function/tool calls with no parameters, making the SDK production-ready for parameterless functions like those in WordPress Abilities API.

Copilot

Pull Request Overview

This PR fixes critical compatibility issues with OpenAI and Anthropic APIs when AI models make function/tool calls with empty parameters. The changes ensure proper JSON encoding and conditional field inclusion to prevent API rejections.

Fix empty tool_calls array handling by only including the field when non-empty
Fix empty arguments encoding to produce {} instead of [] for parameterless function calls
Add comprehensive test coverage for both edge cases

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
`src/Providers/OpenAiCompatibleImplementation/AbstractOpenAiCompatibleTextGenerationModel.php`	Implements conditional tool_calls inclusion and empty arguments object conversion
`tests/unit/Providers/OpenAiCompatibleImplementation/AbstractOpenAiCompatibleTextGenerationModelTest.php`	Adds test cases for empty tool calls and empty arguments scenarios

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-09-02T01:44:09Z

src/Providers/OpenAiCompatibleImplementation/AbstractOpenAiCompatibleTextGenerationModel.php

+            if (is_array($args) && empty($args)) {
+                $args = (object) array();


[nitpick] The (object) array() conversion can be simplified to new \stdClass() for better readability and clarity of intent when creating an empty object.

Suggested change

if (is_array($args) && empty($args)) {

$args = (object) array();

$args = new \stdClass();

felixarntz

@Jameswlepage Thanks, great catch!

For the empty tool_calls, this makes total sense. About the other change, I have a follow up question - technically always making it an empty object doesn't seem right (unless this is truly the only way to make it work against the OpenAI API).

felixarntz · 2025-09-02T02:43:04Z

src/Providers/OpenAiCompatibleImplementation/AbstractOpenAiCompatibleTextGenerationModel.php

+            if (is_array($args) && empty($args)) {
+                $args = (object) array();
+            }


This one is tricky. Technically speaking, for JSON-encoding this should still only be turned into stdClass when the expected input shape is object. While that's often the case, it only depends on the schema - it could also be array, in which case leaving it a PHP array would be correct.

What happens if the parameters JSON schema specified for the function expects an actual array (indexed/numeric)? Does the OpenAI API always fail if it's an empty array? If so, that would seem like a flaw in the API (although, if that's the case, of course we still need to fix / work around it in our SDK).

I thought about this a bit more, and while my concern is still valid in theory, in practice the OpenAI API specification does not support arrays as the root value. So it's fair to assume the data should be an object in this scenario.

...Providers/OpenAiCompatibleImplementation/AbstractOpenAiCompatibleTextGenerationModelTest.php

felixarntz · 2025-09-02T02:46:06Z

...Providers/OpenAiCompatibleImplementation/AbstractOpenAiCompatibleTextGenerationModelTest.php

+
+        $model = $this->createModel();
+        $prepared = $model->exposePrepareMessagesParam([$message], null);
+


PHPCS errors here:

Suggested change

$model = $this->createModel();

$prepared = $model->exposePrepareMessagesParam([$message], null);

$model = $this->createModel();

$prepared = $model->exposePrepareMessagesParam([$message], null);

github-actions · 2025-10-15T04:00:42Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: Jameswlepage <isotropic@git.wordpress.org>
Co-authored-by: felixarntz <flixos90@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

…ol call.

felixarntz

@Jameswlepage It's been a while, so I hope it's fine that I finished this up for you! It was only a few minor details anyway.

Hoping to get 0.2.0 out by end of this week, it's long overdue!

Jameswlepage requested review from Copilot and felixarntz September 2, 2025 01:43

Copilot AI reviewed Sep 2, 2025

View reviewed changes

felixarntz reviewed Sep 2, 2025

View reviewed changes

felixarntz added this to the 0.2.0 milestone Sep 2, 2025

felixarntz added the [Type] Bug An existing feature does not function as intended label Sep 2, 2025

felixarntz added 2 commits October 14, 2025 20:53

Merge branch 'trunk' into fix/empty-tool-calls-parameters

7c2fff1

Fix PHPCS errors.

f043ca6

Clarify empty array to object conversion for OpenAI API compatible to…

133e576

…ol call.

felixarntz approved these changes Oct 15, 2025

View reviewed changes

felixarntz merged commit a447c4e into trunk Oct 15, 2025
6 checks passed

felixarntz deleted the fix/empty-tool-calls-parameters branch October 15, 2025 04:05

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Fix empty tool calls and arguments in OpenAI compatible models #80

Fix empty tool calls and arguments in OpenAI compatible models #80

Uh oh!

Jameswlepage commented Sep 2, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Sep 2, 2025

Uh oh!

felixarntz left a comment

Uh oh!

felixarntz Sep 2, 2025

Uh oh!

felixarntz Oct 15, 2025

Uh oh!

Uh oh!

felixarntz Sep 2, 2025

Uh oh!

github-actions bot commented Oct 15, 2025

Uh oh!

felixarntz left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		if (is_array($args) && empty($args)) {
		$args = (object) array();

	if (is_array($args) && empty($args)) {
	$args = (object) array();
	$args = new \stdClass();


		$model = $this->createModel();
		$prepared = $model->exposePrepareMessagesParam([$message], null);

Fix empty tool calls and arguments in OpenAI compatible models #80

Fix empty tool calls and arguments in OpenAI compatible models #80

Uh oh!

Conversation

Jameswlepage commented Sep 2, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

felixarntz Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

felixarntz Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

felixarntz Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Oct 15, 2025

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants