Ai Agent Laravel Package

## Getting Started

### Minimal Setup
1. **Install Core Packages**:
   ```bash
   composer require symfony/ai-agent symfony/ai-platform

2. Create a Basic Agent:

   use Symfony\Component\Ai\Agent\Agent;
   use Symfony\Component\Ai\Agent\Input;
   use Symfony\Component\Ai\Agent\Output;
   
   $agent = new Agent(
       new Input('What is Laravel?'),
       new \Symfony\Component\Ai\Platform\OpenAiPlatform('your-api-key')
   );
   
   $output = $agent->run();
   echo $output->getContent();
   

3. First Use Case: Chatbot with Wikipedia Tool

   composer require symfony/ai-wikipedia-tool
   

   use Symfony\Component\Ai\Tool\WikipediaTool;
   
   $agent = new Agent(
       new Input('Explain Symfony AI in simple terms'),
       new \Symfony\Component\Ai\Platform\OpenAiPlatform('api-key'),
       new \Symfony\Component\Ai\Toolbox\Toolbox([new WikipediaTool()])
   );
   

Where to Look First

• Documentation: Official guide for core concepts.
• src/Agent.php: Entry point for agent creation.
• src/Toolbox/: Tool integration patterns.
• tests/: Real-world usage examples (e.g., AgentTest.php, MultiAgentTest.php).

Implementation Patterns

Core Workflow: Agent Lifecycle

1. Input Processing:

   $agent->addInputProcessor(new \Symfony\Component\Ai\Agent\InputProcessor\SystemPromptInputProcessor('You are a helpful assistant.'));
   

2. Tool Integration:

   $toolbox = new \Symfony\Component\Ai\Toolbox\Toolbox([
       new \Symfony\Component\Ai\Tool\BraveSearchTool('your-api-key'),
       new \Symfony\Component\Ai\Tool\FilesystemTool('/tmp'),
   ]);
   $agent->setToolbox($toolbox);
   

3. Memory Management:

   $memory = new \Symfony\Component\Ai\Memory\StaticMemoryProvider();
   $agent->setMemory($memory);
   

4. Execution:

   $output = $agent->run();
   $output->getContent(); // Final response
   $output->getToolCalls(); // Logged tool invocations
   

Laravel-Specific Patterns

1. Service Provider Integration:

   // app/Providers/AiServiceProvider.php
   public function register()
   {
       $this->app->singleton(Agent::class, function ($app) {
           return new Agent(
               new Input(''),
               new \Symfony\Component\Ai\Platform\OpenAiPlatform(config('services.openai.key')),
               new \Symfony\Component\Ai\Toolbox\Toolbox([
                   new \Symfony\Component\Ai\Tool\SerpApiTool(config('services.serpapi.key')),
               ])
           );
       });
   }
   

2. Tool Bridge Registration:

   // app/Providers/AiServiceProvider.php
   public function boot()
   {
       $this->app->bind(
           \Symfony\Component\Ai\Tool\ClockTool::class,
           fn() => new \Symfony\Component\Ai\Tool\ClockTool()
       );
   }
   

3. Event-Driven Tool Calls (Laravel Events):

   // Listen to tool call events
   event(new \Symfony\Component\Ai\Event\ToolCallRequested(
       $toolCall,
       $agent
   ));
   

4. Async Processing with Queues:

   // Dispatch agent job
   dispatch(new RunAgentJob($input, $agent));
   

Multi-Agent Orchestration

use Symfony\Component\Ai\MultiAgent\MultiAgent;

$researchAgent = new Agent(/* ... */);
$responseAgent = new Agent(/* ... */);

$multiAgent = new MultiAgent([$researchAgent, $responseAgent]);
$output = $multiAgent->run(new Input('Research and summarize Symfony AI'));

Memory Patterns

1. Static Memory (In-Memory):

   $memory = new \Symfony\Component\Ai\Memory\StaticMemoryProvider();
   $agent->setMemory($memory);
   

2. Embedding Memory (Vector Store):

   $store = new \Symfony\Component\Ai\Store\PostgresStore(
       new \Doctrine\DBAL\Connection($connectionParams)
   );
   $memory = new \Symfony\Component\Ai\Memory\EmbeddingProvider($store);
   $agent->setMemory($memory);
   

Gotchas and Tips

Common Pitfalls

1. Tool Call Validation Failures:

   • Issue: Tools may reject invalid arguments silently.
   • Fix: Use symfony/validator for argument validation:

     use Symfony\Component\Validator\Constraints as Assert;
     
     #[Tool]
     public function search(string #[Assert\NotBlank] $query): string { ... }
     

2. Memory Leaks:

   • Issue: Static memory providers retain all conversations.
   • Fix: Use EmbeddingProvider with TTL or clear memory manually:

     $memory->clear();
     

3. Tool Dispatch Conflicts:

   • Issue: Multiple tools with the same class name may cause ambiguity.
   • Fix: Use unique tool IDs or qualify tool classes:

     $toolbox->addTool(new \App\Tool\CustomBraveSearchTool(), 'custom_brave');
     

4. Streaming Quirks:

   • Issue: Streaming responses may truncate if not handled properly.
   • Fix: Use DeltaInterface for chunked responses:

     $output->stream(function (DeltaInterface $delta) {
         echo $delta->getContent();
     });
     

5. Symfony Dependency Conflicts:

   • Issue: symfony/clock or symfony/http-client may conflict with Laravel.
   • Fix: Override bindings in Laravel’s service provider:

     $this->app->bind(\Symfony\Component\Clock\ClockInterface::class, function () {
         return \Illuminate\Support\Facades\Clock::getFacadeRoot();
     });
     

Debugging Tips

1. Enable Verbose Logging:

   $agent->setLogger(new \Monolog\Logger('ai_agent', [
       new \Monolog\Handler\StreamHandler('storage/logs/ai.log', Monolog\Logger::DEBUG),
   ]));
   

2. Inspect Tool Calls:

   $output = $agent->run();
   foreach ($output->getToolCalls() as $call) {
       dump($call->getName(), $call->getArguments());
   }
   

3. Test with Mock Platform:

   use Symfony\Component\Ai\Platform\MockPlatform;
   
   $agent = new Agent(
       new Input('Test'),
       new MockPlatform()
   );
   

Extension Points

1. Custom Input/Output Processors:

   class UppercaseOutputProcessor implements OutputProcessorInterface {
       public function __invoke(Output $output): Output {
           $output->setContent(strtoupper($output->getContent()));
           return $output;
       }
   }
   $agent->addOutputProcessor(new UppercaseOutputProcessor());
   

2. Dynamic Tool Registration:

   $toolbox->addToolsFromDirectory(__DIR__.'/Tools');
   

3. Override JSON Schema Generation:

   use Symfony\Component\Ai\Tool\Attribute\Tool;
   
   #[Tool(
       schema: [
           'properties' => [
               'query' => ['type' => 'string', 'description' => 'Custom search query']
           ]
       ]
   )]
   public function customSearch(string $query) { ... }
   

Performance Tips

1. Cache Tool Responses:

   $toolbox->addTool(new \App\Tool\CachedSerpApiTool(
       new \Symfony\Component\Ai\Tool\SerpApiTool('key'),
       new \Illuminate\Cache\Repository
   ));
   

2. Batch Tool Calls:

   $agent->setToolbox(new \Symfony\Component\Ai\Toolbox\Toolbox([
       new \App\Tool\BatchWebScraperTool(),
   ]));
   

3. Async Tool Execution:

   $toolbox->addTool(new \App\Tool\AsyncClockTool(
       new \Symfony\Component\Ai\Tool\ClockTool()
   ));
   

Laravel-Specific Quirks

1. Blade Integration:

   • Use OutputProcessor to render responses:

     $agent->addOutputProcessor(function (Output $output) {
         return new Output(view('ai.response', ['content' => $output->getContent()])->render());
     });
     

2. Nova Tool Integration:

   • Expose tools as Nova actions:

     public function tools(Nova $nova)
     {
         Nova::