[Agent] Add Platform tool wrapper for using platforms as tools

Introduces a new Platform tool that wraps any PlatformInterface instance,
allowing agents to use specialized platforms as tools. This enables
scenarios like an OpenAI agent using ElevenLabs for speech-to-text.

- Add Platform tool class with support for Text, Audio, and Image results
- Add OpenAI example demonstrating ElevenLabs platform as tool
- Add documentation explaining the concept and usage
- Update demo AI Bundle configuration with platform tool examples

Author: OskarStark

demo/config/packages/ai.yaml

@@ -2,6 +2,8 @@ ai:
     platform:
         openai:
             api_key: '%env(OPENAI_API_KEY)%'
+        elevenlabs:
+            api_key: '%env(ELEVEN_LABS_API_KEY)%'
     agent:
         blog:
             model: 'gpt-4o-mini'
@@ -49,6 +51,15 @@ ai:
             model: 'gpt-4o-mini'
             prompt: 'You are a helpful general assistant. Assist users with any questions or tasks they may have.'
             tools: false
+        elevenlabs_audio:
+            model: 'gpt-4o-mini'
+            prompt: 'You are a helpful assistant with access to speech-to-text capabilities via ElevenLabs.'
+            tools:
+                # Platform as tool 🚀
+                - platform: 'elevenlabs'
+                  model: 'scribe_v1'
+                  name: 'transcribe_audio'
+                  description: 'Transcribes audio files to text using ElevenLabs.'
     multi_agent:
         support:
             orchestrator: 'orchestrator'
@@ -89,7 +100,16 @@ services:
 
     Symfony\AI\Store\Document\Loader\RssFeedLoader: ~
     Symfony\AI\Store\Document\Transformer\TextTrimTransformer: ~
-    
+
+    # Example: Using a Platform as a Tool
+    # This demonstrates how to wrap any platform as a tool that can be used by agents
+    app.tool.elevenlabs_transcription:
+        class: 'Symfony\AI\Agent\Toolbox\Tool\Platform'
+        arguments:
+            $platform: '@ai.platform.elevenlabs'
+            $model: 'scribe_v1'
+            $options: []
+
     app.filter.week_of_symfony:
         class: 'Symfony\AI\Store\Document\Filter\TextContainsFilter'
         arguments:

examples/openai/README-platform-as-tool.md

@@ -0,0 +1,80 @@
+# Platform as Tool
+
+This example demonstrates how to use one AI platform as a tool within an agent powered by another platform.
+
+## Concept
+
+Just like agents can use other agents as tools, platforms can also be wrapped as tools. This enables powerful compositions where:
+
+- An OpenAI-based agent can use ElevenLabs for speech-to-text
+- An Anthropic-based agent can use OpenAI's DALL-E for image generation
+- Any platform's specialized capabilities can be leveraged by agents using different platforms
+
+## Example: Speech-to-Text with ElevenLabs
+
+The `platform-as-tool.php` example shows an OpenAI agent that uses ElevenLabs' speech-to-text capabilities:
+
+```php
+use Symfony\AI\Agent\Toolbox\Tool\Platform;
+
+// Create ElevenLabs platform
+$elevenLabsPlatform = ElevenLabsPlatformFactory::create(
+    apiKey: env('ELEVEN_LABS_API_KEY'),
+    httpClient: http_client()
+);
+
+// Wrap it as a tool
+$speechToText = new Platform($elevenLabsPlatform, 'scribe_v1');
+
+// Add to agent's toolbox
+$toolbox = new Toolbox([$speechToText]);
+```
+
+## AI Bundle Configuration
+
+In a Symfony application using the AI Bundle, you can configure platforms as tools:
+
+```yaml
+ai:
+    platform:
+        openai:
+            api_key: '%env(OPENAI_API_KEY)%'
+        elevenlabs:
+            api_key: '%env(ELEVEN_LABS_API_KEY)%'
+
+    agent:
+        my_agent:
+            model: 'gpt-4o-mini'
+            tools:
+                # Use platform as tool via configuration
+                - platform: 'elevenlabs'
+                  model: 'scribe_v1'
+                  name: 'transcribe_audio'
+                  description: 'Transcribes audio files to text'
+```
+
+Or define it as a service:
+
+```yaml
+services:
+    app.tool.elevenlabs_transcription:
+        class: 'Symfony\AI\Agent\Toolbox\Tool\Platform'
+        arguments:
+            $platform: '@ai.platform.elevenlabs'
+            $model: 'scribe_v1'
+            $options: []
+```
+
+## Use Cases
+
+1. **Speech-to-Text**: Use ElevenLabs or Whisper for transcription while using another platform for reasoning
+2. **Image Generation**: Use DALL-E or Stable Diffusion for images while using another platform for chat
+3. **Specialized Models**: Leverage platform-specific models (e.g., code generation, embeddings) from any agent
+4. **Multi-Modal Workflows**: Combine different platforms' strengths in a single agent workflow
+
+## Benefits
+
+- **Best Tool for the Job**: Choose the best platform for each specific task
+- **Flexibility**: Mix and match platforms based on cost, performance, or features
+- **Composability**: Build complex AI systems by combining multiple platforms
+- **Simplicity**: Use the same tool interface whether wrapping agents or platforms

examples/openai/platform-as-tool.php

@@ -0,0 +1,54 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use Symfony\AI\Agent\Agent;
+use Symfony\AI\Agent\Toolbox\AgentProcessor;
+use Symfony\AI\Agent\Toolbox\Tool\Platform;
+use Symfony\AI\Agent\Toolbox\Toolbox;
+use Symfony\AI\Platform\Bridge\ElevenLabs\PlatformFactory as ElevenLabsPlatformFactory;
+use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
+use Symfony\AI\Platform\Message\Content\Audio;
+use Symfony\AI\Platform\Message\Message;
+use Symfony\AI\Platform\Message\MessageBag;
+
+require_once dirname(__DIR__).'/bootstrap.php';
+
+// Create the main OpenAI platform
+$openAiPlatform = PlatformFactory::create(env('OPENAI_API_KEY'), http_client());
+
+// Create ElevenLabs platform as a tool for speech-to-text
+$elevenLabsPlatform = ElevenLabsPlatformFactory::create(
+    apiKey: env('ELEVEN_LABS_API_KEY'),
+    httpClient: http_client()
+);
+
+// Wrap ElevenLabs platform as a tool
+$speechToText = new Platform($elevenLabsPlatform, 'scribe_v1');
+
+// Create toolbox with the platform tool
+$toolbox = new Toolbox([$speechToText], logger: logger());
+$processor = new AgentProcessor($toolbox);
+
+// Create agent with OpenAI platform but with ElevenLabs tool available
+$agent = new Agent($openAiPlatform, 'gpt-4o-mini', [$processor], [$processor], logger: logger());
+
+// The agent can now use ElevenLabs for speech-to-text while using OpenAI for reasoning
+$audioPath = dirname(__DIR__, 2).'/fixtures/audio.mp3';
+$messages = new MessageBag(
+    Message::ofUser(sprintf(
+        'I have an audio file. Please transcribe it and tell me what it says. Audio: %s',
+        Audio::fromFile($audioPath)
+    ))
+);
+
+$result = $agent->call($messages);
+
+echo $result->getContent().\PHP_EOL;

src/agent/src/Toolbox/Tool/Platform.php

@@ -0,0 +1,57 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Agent\Toolbox\Tool;
+
+use Symfony\AI\Platform\PlatformInterface;
+use Symfony\AI\Platform\Result\AudioResult;
+use Symfony\AI\Platform\Result\ImageResult;
+use Symfony\AI\Platform\Result\TextResult;
+
+/**
+ * Wraps a Platform instance as a tool, allowing agents to use specialized platforms for specific tasks.
+ *
+ * This enables scenarios where an agent using one platform (e.g., OpenAI) can leverage
+ * another platform (e.g., ElevenLabs for speech-to-text) as a tool.
+ *
+ * @author Oskar Stark <[email protected]>
+ */
+final readonly class Platform
+{
+    /**
+     * @param array<string, mixed> $options
+     */
+    public function __construct(
+        private PlatformInterface $platform,
+        private string $model,
+        private array $options = [],
+    ) {
+    }
+
+    /**
+     * @param array<mixed>|string|object $input the input to pass to the platform
+     */
+    public function __invoke(array|string|object $input): string
+    {
+        $result = $this->platform->invoke(
+            $this->model,
+            $input,
+            $this->options,
+        )->await();
+
+        return match (true) {
+            $result instanceof TextResult => $result->getContent(),
+            $result instanceof AudioResult => $result->getText() ?? base64_encode($result->getAudio()),
+            $result instanceof ImageResult => $result->getText() ?? base64_encode($result->getImage()),
+            default => throw new \LogicException(\sprintf('Unsupported result type "%s".', $result::class)),
+        };
+    }
+}