[Platform][VertexAi] Wrap list-array tool responses for Struct-proto compatibility

[peter-si]

Q	A
Branch?	main
Bug fix?	yes
New feature?	no
Deprecations?	no
Issues	-
License	MIT

Summary

Wraps list-array tool responses in a {items: [...]} object so they pass Gemini's Struct-proto validation on functionResponse.response. Without this, any tool that returns a JSON list 500s the whole turn with Proto field is not repeating, cannot start list.

Why

google.protobuf.Struct is a JSON-object shape — it cannot represent a sequential JSON array. The current normalizer wraps scalars as {rawResponse: <value>} (good) but passes lists through unchanged (broken). Every tool that returns rows / records / promos / search results / etc. fails.

Concrete reproducer: a tool method returning [{name: 'A'}, {name: 'B'}] produces functionResponse.response = [{name: 'A'}, {name: 'B'}], which Vertex rejects.

What changes

In Symfony\AI\Platform\Bridge\VertexAi\Contract\ToolCallMessageNormalizer:

• Associative arrays → pass through (unchanged)
• List arrays → wrapped as {items: [...]} (new)
• Scalars / null → wrapped as {rawResponse: <value>} (unchanged)

Drive-bys while in the file: extracted decodeContent() and asStruct() for readability, added a class-level docblock describing the Struct quirk, and dropped a no-op array_filter() on the outer payload (it never had anything to filter).

Backwards compatibility

The output shape changes for tools that returned a JSON list, but those tools currently 500 with the Struct-proto error against Gemini, so there are no working consumers depending on the broken shape. A [BC BREAK] entry has been added to the ai-vertex-ai-platform CHANGELOG under 0.10.

Tests

New src/platform/tests/Bridge/VertexAi/Contract/ToolCallMessageNormalizerTest covers associative passthrough, list-wrap, empty-list-wrap, scalar wrap, non-JSON content, null content, and tool-name preservation. 9 tests, 9 assertions, all green.

Note: PHPStan / Component / Agent is currently red on this branch due to a pre-existing Variable $sourceCollection might not be defined. issue in Agent\Toolbox\Toolbox::call() — verified independently against upstream/main. Fix submitted as #2103; once that merges, a rebase here will clear the failure.

🤖 Generated with Claude Code

[peter-si]

Heads up on red CI here:

• Fabbot / Check PR header — fixed in this push (title was missing the [Platform] prefix, now [Platform][VertexAi] ... per the convention used in [Platform][Gemini][VertexAI] Remove redundant EventSourceHttpClient wrapping #1906 / [Platform][VertexAi] Fix binary result handling #1938 / [Platform][VertexAi] Add Gemini 3 and 3.1 flash #1947).
• PHPStan / Component / Agent — this is a pre-existing failure on main (verified by running phpstan analyse src/agent against upstream/main). Toolbox::call() triggers Variable $sourceCollection might not be defined. because PHPStan can't correlate the two instanceof HasSourcesInterface checks. It happens to surface on every PR that runs Agent's PHPStan, not just this one.

I've opened #2103 with the two-line fix. Once that merges, the failure here will clear after a rebase. Let me know if you'd prefer this PR to depend on / include that fix instead.

[chr-hertel]

Hi @peter-si,
thanks for raising this, how did you end up with a tool result like [{name: 'A'}, {name: 'B'}]? so like, what is the return value of the tool?

I would expect a tool result to be more structured, and that's why we have the Symfony\AI\Agent\Toolbox\ToolResultConverter dealing with this here