[AI Bundle] Add support for loading agent prompts from files

This change allows users to configure agent prompts via file paths
using the 'prompt.file' configuration option. The implementation uses
Symfony's HttpFoundation File class for clean, idiomatic file handling.

Configuration example:
```yaml
ai:
    agent:
        my_agent:
            platform: ai.platform.openai
            model: gpt-4o-mini
            prompt:
                file: '%kernel.project_dir%/config/prompts/assistant.txt'
```

Programmatic example:
```php
$file = new File('/path/to/prompt.txt');
$processor = new SystemPromptInputProcessor($file);
$agent = new Agent($platform, 'gpt-4o-mini', [$processor]);
```

Key features:
- prompt.text and prompt.file are mutually exclusive
- File existence and readability validated at container build time
- Works with any text-based file format (.txt, .json, .md, etc.)
- Uses Symfony\Component\HttpFoundation\File\File for clean API
- File content loaded lazily via $file->getContent()

Changes:
- Added symfony/http-foundation dependency to agent component
- SystemPromptInputProcessor now accepts File objects
- Added prompt.file configuration option with validation
- AiBundle creates File service definition from file path
- Comprehensive tests for single and multiline files

Examples:
- examples/misc/prompt-text-file.php - Text file example
- examples/misc/prompt-json-file.php - JSON file example
- fixtures/prompts/helpful-assistant.txt - Example text prompt
- fixtures/prompts/code-reviewer.json - Example JSON prompt

Author: OskarStark

examples/misc/prompt-json-file.php

@@ -0,0 +1,31 @@
+<?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\InputProcessor\SystemPromptInputProcessor;
+use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
+use Symfony\AI\Platform\Message\Message;
+use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\Component\HttpFoundation\File\File;
+
+require_once dirname(__DIR__).'/bootstrap.php';
+
+$platform = PlatformFactory::create($_ENV['OPENAI_API_KEY'], http_client());
+
+// Load system prompt from a JSON file
+$promptFile = new File(dirname(__DIR__, 2).'/fixtures/prompts/code-reviewer.json');
+$systemPromptProcessor = new SystemPromptInputProcessor($promptFile);
+
+$agent = new Agent($platform, 'gpt-4o-mini', [$systemPromptProcessor], logger: logger());
+$messages = new MessageBag(Message::ofUser('Review this code: function add($a, $b) { return $a + $b; }'));
+$result = $agent->call($messages);
+
+echo $result->getContent().\PHP_EOL;

examples/misc/prompt-text-file.php

@@ -0,0 +1,31 @@
+<?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\InputProcessor\SystemPromptInputProcessor;
+use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
+use Symfony\AI\Platform\Message\Message;
+use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\Component\HttpFoundation\File\File;
+
+require_once dirname(__DIR__).'/bootstrap.php';
+
+$platform = PlatformFactory::create($_ENV['OPENAI_API_KEY'], http_client());
+
+// Load system prompt from a plain text file (.txt)
+$promptFile = new File(dirname(__DIR__, 2).'/fixtures/prompts/helpful-assistant.txt');
+$systemPromptProcessor = new SystemPromptInputProcessor($promptFile);
+
+$agent = new Agent($platform, 'gpt-4o-mini', [$systemPromptProcessor], logger: logger());
+$messages = new MessageBag(Message::ofUser('Can you explain what dependency injection is?'));
+$result = $agent->call($messages);
+
+echo $result->getContent().\PHP_EOL;

fixtures/prompts/code-reviewer.json

@@ -0,0 +1,12 @@
+{
+  "role": "You are an expert code reviewer with deep knowledge of software engineering best practices, design patterns, and code quality.",
+  "responsibilities": [
+    "Review code for bugs and potential issues",
+    "Suggest improvements for code quality and maintainability",
+    "Identify security vulnerabilities",
+    "Recommend better design patterns when appropriate",
+    "Ensure code follows language-specific best practices"
+  ],
+  "tone": "constructive and educational",
+  "approach": "Provide thorough but concise feedback with specific suggestions and examples when helpful"
+}

fixtures/prompts/helpful-assistant.txt

@@ -0,0 +1,8 @@
+You are a helpful and knowledgeable assistant. Your goal is to provide accurate, concise, and useful responses to user queries.
+
+Guidelines:
+- Be clear and direct in your responses
+- Provide examples when appropriate
+- If you're unsure about something, say so
+- Be respectful and professional at all times
+- Break down complex topics into understandable explanations

src/agent/src/InputProcessor/SystemPromptInputProcessor.php

@@ -19,6 +19,7 @@
 use Symfony\AI\Agent\Toolbox\ToolboxInterface;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Tool\Tool;
+use Symfony\Component\HttpFoundation\File\File;
 use Symfony\Contracts\Translation\TranslatableInterface;
 use Symfony\Contracts\Translation\TranslatorInterface;
 
@@ -28,18 +29,22 @@
 final readonly class SystemPromptInputProcessor implements InputProcessorInterface
 {
     /**
-     * @param \Stringable|TranslatableInterface|string $systemPrompt the system prompt to prepend to the input messages
-     * @param ToolboxInterface|null                    $toolbox      the tool box to be used to append the tool definitions to the system prompt
+     * @param \Stringable|TranslatableInterface|string|File $systemPrompt the system prompt to prepend to the input messages, or a File object to read from
+     * @param ToolboxInterface|null                         $toolbox      the tool box to be used to append the tool definitions to the system prompt
      */
     public function __construct(
-        private \Stringable|TranslatableInterface|string $systemPrompt,
+        private \Stringable|TranslatableInterface|string|File $systemPrompt,
         private ?ToolboxInterface $toolbox = null,
         private ?TranslatorInterface $translator = null,
         private LoggerInterface $logger = new NullLogger(),
     ) {
         if ($this->systemPrompt instanceof TranslatableInterface && !$this->translator) {
             throw new RuntimeException('Translatable system prompt is not supported when no translator is provided.');
         }
+
+        if ($this->systemPrompt instanceof File && !class_exists(File::class)) {
+            throw new RuntimeException('File-based system prompt requires symfony/http-foundation. Try running "composer require symfony/http-foundation".');
+        }
     }
 
     public function processInput(Input $input): void
@@ -52,9 +57,13 @@ public function processInput(Input $input): void
             return;
         }
 
-        $message = $this->systemPrompt instanceof TranslatableInterface
-            ? $this->systemPrompt->trans($this->translator)
-            : (string) $this->systemPrompt;
+        if ($this->systemPrompt instanceof File) {
+            $message = $this->systemPrompt->getContent();
+        } elseif ($this->systemPrompt instanceof TranslatableInterface) {
+            $message = $this->systemPrompt->trans($this->translator);
+        } else {
+            $message = (string) $this->systemPrompt;
+        }
 
         if ($this->toolbox instanceof ToolboxInterface
             && [] !== $this->toolbox->getTools()

src/agent/tests/InputProcessor/SystemPromptInputProcessorTest.php

@@ -25,6 +25,7 @@
 use Symfony\AI\Platform\Result\ToolCall;
 use Symfony\AI\Platform\Tool\ExecutionReference;
 use Symfony\AI\Platform\Tool\Tool;
+use Symfony\Component\HttpFoundation\File\File;
 use Symfony\Component\Translation\TranslatableMessage;
 use Symfony\Contracts\Translation\TranslatorInterface;
 
@@ -221,6 +222,49 @@ public function testWithMissingTranslator()
         );
     }
 
+    public function testProcessInputWithFile()
+    {
+        $tempFile = tempnam(sys_get_temp_dir(), 'prompt_');
+        file_put_contents($tempFile, 'This is a system prompt from a file');
+
+        try {
+            $file = new File($tempFile);
+            $processor = new SystemPromptInputProcessor($file);
+
+            $input = new Input(new Gpt('gpt-4o'), new MessageBag(Message::ofUser('This is a user message')));
+            $processor->processInput($input);
+
+            $messages = $input->messages->getMessages();
+            $this->assertCount(2, $messages);
+            $this->assertInstanceOf(SystemMessage::class, $messages[0]);
+            $this->assertInstanceOf(UserMessage::class, $messages[1]);
+            $this->assertSame('This is a system prompt from a file', $messages[0]->content);
+        } finally {
+            unlink($tempFile);
+        }
+    }
+
+    public function testProcessInputWithMultilineFile()
+    {
+        $tempFile = tempnam(sys_get_temp_dir(), 'prompt_');
+        file_put_contents($tempFile, "Line 1\nLine 2\nLine 3");
+
+        try {
+            $file = new File($tempFile);
+            $processor = new SystemPromptInputProcessor($file);
+
+            $input = new Input(new Gpt('gpt-4o'), new MessageBag(Message::ofUser('This is a user message')));
+            $processor->processInput($input);
+
+            $messages = $input->messages->getMessages();
+            $this->assertCount(2, $messages);
+            $this->assertInstanceOf(SystemMessage::class, $messages[0]);
+            $this->assertSame("Line 1\nLine 2\nLine 3", $messages[0]->content);
+        } finally {
+            unlink($tempFile);
+        }
+    }
+
     private function getTranslator(): TranslatorInterface
     {
         return new class implements TranslatorInterface {

src/ai-bundle/config/options.php

@@ -309,19 +309,37 @@
                             ->beforeNormalization()
                                 ->ifArray()
                                 ->then(function (array $v) {
-                                    if (!isset($v['text']) && !isset($v['include_tools'])) {
-                                        throw new \InvalidArgumentException('Either "text" or "include_tools" must be configured for prompt.');
+                                    if (!isset($v['text']) && !isset($v['file']) && !isset($v['include_tools'])) {
+                                        throw new \InvalidArgumentException('Either "text", "file" or "include_tools" must be configured for prompt.');
                                     }
 
                                     return $v;
                                 })
                             ->end()
                             ->validate()
                                 ->ifTrue(function ($v) {
-                                    return \is_array($v) && '' === trim($v['text'] ?? '');
+                                    return \is_array($v) && isset($v['text']) && isset($v['file']);
+                                })
+                                ->thenInvalid('Cannot use both "text" and "file" for prompt. Choose one.')
+                            ->end()
+                            ->validate()
+                                ->ifTrue(function ($v) {
+                                    return \is_array($v) && isset($v['text']) && '' === trim($v['text']);
                                 })
                                 ->thenInvalid('The "text" cannot be empty.')
                             ->end()
+                            ->validate()
+                                ->ifTrue(function ($v) {
+                                    return \is_array($v) && isset($v['file']) && '' === trim($v['file']);
+                                })
+                                ->thenInvalid('The "file" cannot be empty.')
+                            ->end()
+                            ->validate()
+                                ->ifTrue(function ($v) {
+                                    return \is_array($v) && isset($v['file']) && !class_exists(\Symfony\Component\HttpFoundation\File\File::class);
+                                })
+                                ->thenInvalid('File-based system prompt requires symfony/http-foundation. Try running `composer require symfony/http-foundation`.')
+                            ->end()
                             ->validate()
                                 ->ifTrue(function ($v) {
                                     return \is_array($v) && ($v['enabled'] ?? false) && !interface_exists(TranslatorInterface::class);
@@ -332,6 +350,9 @@
                                 ->stringNode('text')
                                     ->info('The system prompt text')
                                 ->end()
+                                ->stringNode('file')
+                                    ->info('Path to file containing the system prompt (JSON format supported)')
+                                ->end()
                                 ->booleanNode('include_tools')
                                     ->info('Include tool definitions at the end of the system prompt')
                                     ->defaultFalse()

src/ai-bundle/src/AiBundle.php

@@ -84,6 +84,7 @@
 use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
 use Symfony\Component\DependencyInjection\Reference;
 use Symfony\Component\HttpClient\HttpClient;
+use Symfony\Component\HttpFoundation\File\File;
 use Symfony\Component\HttpKernel\Bundle\AbstractBundle;
 use Symfony\Component\Security\Core\Authorization\AuthorizationCheckerInterface;
 use Symfony\Component\Translation\TranslatableMessage;
@@ -652,14 +653,30 @@ private function processAgentConfig(string $name, array $config, ContainerBuilde
         if (isset($config['prompt'])) {
             $includeTools = isset($config['prompt']['include_tools']) && $config['prompt']['include_tools'];
 
-            if ($config['prompt']['enable_translation']) {
-                if (!class_exists(TranslatableMessage::class)) {
-                    throw new RuntimeException('For using prompt translataion, symfony/translation package is required. Try running "composer require symfony/translation".');
+            // Create prompt from file if configured, otherwise use text
+            if (isset($config['prompt']['file'])) {
+                $filePath = $config['prompt']['file'];
+                if (!file_exists($filePath)) {
+                    throw new InvalidArgumentException(\sprintf('Prompt file "%s" does not exist.', $filePath));
                 }
+                if (!is_readable($filePath)) {
+                    throw new InvalidArgumentException(\sprintf('Prompt file "%s" is not readable.', $filePath));
+                }
+                $prompt = new Definition(File::class, [$filePath]);
+            } elseif (isset($config['prompt']['text'])) {
+                $promptText = $config['prompt']['text'];
+
+                if ($config['prompt']['enable_translation']) {
+                    if (!class_exists(TranslatableMessage::class)) {
+                        throw new RuntimeException('For using prompt translataion, symfony/translation package is required. Try running "composer require symfony/translation".');
+                    }
 
-                $prompt = new TranslatableMessage($config['prompt']['text'], domain: $config['prompt']['translation_domain']);
+                    $prompt = new TranslatableMessage($promptText, domain: $config['prompt']['translation_domain']);
+                } else {
+                    $prompt = $promptText;
+                }
             } else {
-                $prompt = $config['prompt']['text'];
+                $prompt = '';
             }
 
             $systemPromptInputProcessorDefinition = (new Definition(SystemPromptInputProcessor::class))