bug #387 [Platform] Fix VertexAI server tools (valtzu)

This PR was merged into the main branch.

Discussion
----------

[Platform] Fix VertexAI server tools

| Q             | A
| ------------- | ---
| Bug fix?      | yes
| New feature?  | no
| Docs?         | yes
| Issues        | Fix #386
| License       | MIT

1. Align "Gemini via VertexAI" server tools configuration with Gemini platform
    - This makes it easier to migrate from Gemini -> Vertex and vice-versa
3. Fix the server tools example to actually use server tools
4. Fix how server tools are provided to VertexAI

Worth noting that unlike Gemini API, it seems VertexAI does not support client-side tools when using server-side tools, the api is returning `Multiple tools are supported only when they are all search tools`. This is why the `Clock` & `Toolbox` was removed from the example.

Commits
-------

ea0cbe5 [Platform] Fix VertexAI server tools

Author: chr-hertel

examples/vertexai/server-tools.php

@@ -10,9 +10,6 @@
  */
 
 use Symfony\AI\Agent\Agent;
-use Symfony\AI\Agent\Toolbox\AgentProcessor;
-use Symfony\AI\Agent\Toolbox\Tool\Clock;
-use Symfony\AI\Agent\Toolbox\Toolbox;
 use Symfony\AI\Platform\Bridge\VertexAi\Gemini\Model;
 use Symfony\AI\Platform\Bridge\VertexAi\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
@@ -22,15 +19,15 @@
 
 $platform = PlatformFactory::create(env('GOOGLE_CLOUD_LOCATION'), env('GOOGLE_CLOUD_PROJECT'), adc_aware_http_client());
 
-$model = new Model(Model::GEMINI_2_5_PRO);
+$model = new Model(Model::GEMINI_2_5_PRO, ['server_tools' => ['url_context' => true]]);
+$agent = new Agent($platform, $model, [], [], logger());
 
-$toolbox = new Toolbox([new Clock()], logger: logger());
-$processor = new AgentProcessor($toolbox);
-$agent = new Agent($platform, $model, [$processor], [$processor], logger());
-
-$content = file_get_contents('https://www.euribor-rates.eu/en/current-euribor-rates/4/euribor-rate-12-months/');
 $messages = new MessageBag(
-    Message::ofUser("Based on the following page content, what was the 12-month Euribor rate a week ago?\n\n".$content)
+    Message::ofUser(
+        <<<'PROMPT'
+            What's the latest 12-month Euribor rate based on https://www.euribor-rates.eu/en/current-euribor-rates/4/euribor-rate-12-months/
+            PROMPT,
+    ),
 );
 
 $result = $agent->call($messages);

src/platform/doc/vertexai-server-tools.rst

@@ -28,11 +28,10 @@ The URL Context tool allows the model to fetch and analyze content from specifie
 
 ::
 
-    $model = new VertexAi\Gemini\Model('gemini-2.5-pro');
+    $model = new VertexAi\Gemini\Model('gemini-2.5-pro', ['server_tools' => ['url_context' => true]]);
 
-    $content = file_get_contents('https://www.euribor-rates.eu/en/current-euribor-rates/4/euribor-rate-12-months/');
     $messages = new MessageBag(
-        Message::ofUser("Based on the following page content, what was the 12-month Euribor rate a week ago?\n\n".$content)
+        Message::ofUser("Based on https://www.euribor-rates.eu/en/current-euribor-rates/4/euribor-rate-12-months/, what is the latest 12-month Euribor rate?"),
     );
 
     $result = $platform->invoke($model, $messages);
@@ -51,9 +50,9 @@ More info can be found at https://cloud.google.com/vertex-ai/generative-ai/docs/
 ::
 
     $model = new VertexAi\Gemini\Model('gemini-2.5-pro', [
-        'tools' => [[
-            'googleSearch' => new \stdClass()
-        ]]
+        'server_tools' => [
+            'google_search' => true,
+        ],
     ]);
 
     $messages = new MessageBag(
@@ -70,9 +69,9 @@ More info can be found at https://cloud.google.com/vertex-ai/generative-ai/docs/
 ::
 
     $model = new Gemini('gemini-2.5-pro-preview-03-25', [
-        'tools' => [[
-            'codeExecution' => new \stdClass()
-        ]]
+        'server_tools' => [
+            'code_execution' => true,
+        ],
     ]);
 
     $messages = new MessageBag(
@@ -88,10 +87,10 @@ Using Multiple Server Tools
 You can enable multiple tools in a single request::
 
     $model = new Gemini('gemini-2.5-pro-preview-03-25', [
-        'tools' => [[
-            'googleSearch' => new \stdClass(),
-            'codeExecution' => new \stdClass()
-        ]]
+        'server_tools' => [
+            'google_search' => true,
+            'code_execution' => true,
+        ],
     ]);
 
 Example

src/platform/src/Bridge/VertexAi/Gemini/ModelClient.php

@@ -76,6 +76,17 @@ public function request(BaseModel $model, array|string $payload, array $options
             $options['tools'][] = ['functionDeclarations' => $tools];
         }
 
+        if (isset($options['server_tools'])) {
+            foreach ($options['server_tools'] as $tool => $params) {
+                if (!$params) {
+                    continue;
+                }
+
+                $options['tools'][] = [$tool => true === $params ? new \ArrayObject() : $params];
+            }
+            unset($options['server_tools']);
+        }
+
         if (\is_string($payload)) {
             $payload = [
                 'contents' => [

src/platform/tests/Bridge/VertexAi/Gemini/ModelClientTest.php

@@ -57,4 +57,35 @@ public function testItInvokesTheTextModelsSuccessfully()
         );
         $this->assertSame($expectedResponse, $data);
     }
+
+    public function testItPassesServerToolsFromOptions()
+    {
+        $payload = [
+            'content' => [
+                ['parts' => ['text' => 'Server tool test']],
+            ],
+        ];
+        $httpClient = new MockHttpClient(
+            function ($method, $url, $options) {
+                self::assertJsonStringEqualsJsonString(
+                    <<<'JSON'
+                        {
+                          "tools": [
+                            {"google_search": {}}
+                          ],
+                          "content": [
+                            {"parts":{"text":"Server tool test"}}
+                          ]
+                        }
+                        JSON,
+                    $options['body'],
+                );
+
+                return new JsonMockResponse('{}');
+            }
+        );
+
+        $client = new ModelClient($httpClient, 'global', 'test');
+        $client->request(new Model(Model::GEMINI_2_0_FLASH), $payload, ['server_tools' => ['google_search' => true]]);
+    }
 }