Laravel Agent Editable Prompts Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require lvlup-dev/laravel-agent-editable-prompts
   php artisan migrate
   

   The package auto-discovers the service provider and runs migrations.

2. First Use Case: Define prompts for an agent in the database via the agent_prompts table:

   // Create a prompt via Tinker or a seeder
   \LvlupDev\AgentEditablePrompts\Models\AgentPrompt::create([
       'agent_slug' => 'customer-support-agent',
       'priority' => 1,
       'content' => 'Greet the user warmly.',
   ]);
   

3. Resolve Prompts: Fetch a concatenated string or ordered segments in your code:

   $instructions = app(\LvlupDev\AgentEditablePrompts\Services\AgentPromptService::class)
       ->resolve('customer-support-agent');
   
   $segments = app(\LvlupDev\AgentEditablePrompts\Services\AgentPromptService::class)
       ->segments('customer-support-agent');
   

4. Admin UI (Optional): If using Inertia/Vue, publish the admin UI assets:

   php artisan vendor:publish --provider="LvlupDev\AgentEditablePrompts\AgentEditablePromptsServiceProvider" --tag="admin-views"
   

   Then register the CRUD route in routes/web.php:

   Route::inertia('/agent-prompts', 'AgentPrompts/Index');
   

Implementation Patterns

Core Workflows

1. Prompt Management:

   • Use the AgentPromptService to dynamically fetch prompts by agent_slug.
   • Segments: Iterate over ordered prompts (e.g., for Blade rendering per chunk):

     foreach ($segments as $segment) {
         Blade::render($segment->content);
     }
     

   • Concatenation: Join prompts into a single string (configurable separator, default: \n\n):

     $fullPrompt = $service->resolve('agent-slug', separator: ' ');
     

2. Database Structure:

   • agent_slug: Group prompts by agent (e.g., support-bot, marketing-agent).
   • priority: Controls order (lower = higher priority). Use 0 for default.
   • content: Store raw prompt text (Markdown/Blade supported).

3. Integration with Agents:

   • Pass resolved prompts to LLM services (e.g., Laravel AI, LangChain):

     $response = app('llm')->run($instructions);
     

   • Cache resolved prompts for performance:

     $cacheKey = "agent_prompt_{$agentSlug}";
     $instructions = Cache::remember($cacheKey, now()->addHours(1), fn() =>
         $service->resolve($agentSlug)
     );
     

4. Admin UI (Inertia/Vue):

   • CRUD Operations: Non-technical users can edit prompts via the published UI.
   • Customization: Extend the Vue components (e.g., add validation, custom fields) by overriding the published views:

     php artisan vendor:publish --tag="agent-prompts-views"
     

5. Testing:

   • Mock the AgentPromptService in tests:

     $service = Mockery::mock(AgentPromptService::class);
     $service->shouldReceive('resolve')->andReturn('Mocked prompt');
     $this->app->instance(AgentPromptService::class, $service);
     

Gotchas and Tips

Pitfalls

1. Priority Collisions:

   • If multiple prompts share the same priority, the database order becomes undefined.
   • Fix: Use unique priority values or add a created_at fallback in queries.

2. Separator Quirks:

   • The default separator (\n\n) may cause issues with multi-line prompts.
   • Tip: Override the separator per call:

     $service->resolve('agent-slug', separator: PHP_EOL);
     

3. Admin UI Dependencies:

   • The Inertia/Vue admin requires inertiajs/inertia-laravel and a frontend setup.
   • Workaround: Disable the UI by removing the route or publishing empty views.

4. Performance with Large Prompts:

   • Concatenating many high-priority prompts may hit memory limits.
   • Tip: Use segments() for chunked processing or paginate the database query.

5. Migration Conflicts:

   • If the agent_prompts table exists, the package’s migration will fail.
   • Fix: Manually check database/migrations/ for duplicates before running migrate.

Debugging

1. Query Issues:

   • Enable Laravel’s query logging to verify agent_slug and priority sorting:

     \DB::enableQueryLog();
     $service->resolve('agent-slug');
     \DB::getQueryLog();
     

2. Missing Prompts:

   • Ensure agent_slug matches exactly (case-sensitive) between database and code.
   • Tip: Add a where('agent_slug', $slug) debug query to verify records exist.

3. Admin UI Not Loading:

   • Check the frontend build process (e.g., Vite) for errors.
   • Tip: Clear caches:

     php artisan view:clear
     npm run dev
     

Extension Points

1. Custom Content Types:

   • Extend the AgentPrompt model to support additional fields (e.g., metadata):

     class AgentPrompt extends \LvlupDev\AgentEditablePrompts\Models\AgentPrompt {
         protected $casts = [
             'metadata' => 'json',
         ];
     }
     

2. Dynamic Separators:

   • Override the resolve() method in a service binding:

     $this->app->bind(AgentPromptService::class, function ($app) {
         $service = new AgentPromptService();
         $service->setSeparatorResolver(fn($slug) => $slug === 'special-agent' ? ' | ' : "\n\n");
         return $service;
     });
     

3. Event Hooks:

   • Listen for prompt updates to trigger side effects (e.g., cache invalidation):

     \LvlupDev\AgentEditablePrompts\Models\AgentPrompt::updated(fn($prompt) => Cache::forget("agent_prompt_{$prompt->agent_slug}"));
     

4. Blade Directives:

   • Create a custom directive to embed prompts in views:

     Blade::directive('agentPrompt', function ($slug) {
         return "<?php echo app(\\LvlupDev\\AgentEditablePrompts\\Services\\AgentPromptService::class)->resolve({$slug}); ?>";
     });
     

     Usage:

     @agentPrompt('customer-support-agent')