Vizra Adk Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require vizra/vizra-adk
   php artisan vizra:install
   

   • Publishes config, migrations, and assets
   • Sets up database tables for agents, tools, and traces

2. First Agent Creation:

   php artisan vizra:make:agent CustomerSupportAgent
   

   • Generates a scaffolded agent class in app/Agents/

3. Basic Usage:

   $response = CustomerSupportAgent::run('User query here')
       ->forUser(auth()->user())
       ->go();
   

   • Auto-discovers agents from app/Agents/ namespace
   • Supports fluent chaining for user context, memory, and execution modes

Where to Look First

• Agent Scaffolding: app/Agents/ directory (auto-discovered)
• Tool Definitions: app/Tools/ directory (auto-discovered)
• Configuration: config/vizra.php (published by installer)
• Dashboard: /vizra (Livewire-powered UI for testing)

First Use Case

Create a simple support agent that delegates to tools:

// app/Agents/CustomerSupportAgent.php
class CustomerSupportAgent extends BaseLlmAgent
{
    protected string $name = 'customer_support';
    protected string $instructions = 'You are a helpful customer support assistant.';
    protected array $tools = [
        OrderLookupTool::class,
        RefundProcessorTool::class,
    ];
}

// Run in Tinker or controller:
$response = CustomerSupportAgent::run('I need to cancel my order #12345')
    ->forUser($user)
    ->go();

Implementation Patterns

Core Workflows

1. Agent Development Cycle:

   flowchart TD
     A[Define Agent] --> B[Add Tools]
     B --> C[Configure Memory]
     C --> D[Test Locally]
     D --> E[Deploy]
   

2. Tool Integration Pattern:

   // 1. Define tool schema
   public function definition(): array {
       return [
           'name' => 'tool_name',
           'description' => 'Tool purpose',
           'parameters' => [
               'type' => 'object',
               'properties' => [
                   'param1' => ['type' => 'string'],
               ],
           ],
       ];
   }
   
   // 2. Implement execution
   public function execute(array $args, AgentContext $context): string {
       return json_encode($this->service->process($args));
   }
   

3. Memory Integration:

   // In agent class
   protected function configureMemory(): void {
       $this->memory()
           ->use('vector_store') // Default memory type
           ->withEmbeddingModel('text-embedding-3-small')
           ->withRetentionPolicy(30); // Days
   }
   

Integration Tips

1. Laravel Service Integration:

   // Bind custom service to tool
   $this->app->singleton(RefundProcessorTool::class, function ($app) {
       return new RefundProcessorTool(
           $app->make(PaymentGateway::class),
           $app->make(NotificationService::class)
       );
   });
   

2. Event-Driven Agents:

   // In EventServiceProvider
   public function boot(): void {
       OrderShipped::listen(function ($event) {
           Agent::run('order_fulfillment')
               ->forUser($event->user)
               ->withInput($event->order->toArray())
               ->queue();
       });
   }
   

3. Dashboard Customization:

   // Add custom metrics to dashboard
   VizraDashboard::macro('addMetric', function ($name, $callback) {
       $this->metrics[$name] = $callback;
   });
   
   // Usage:
   VizraDashboard::addMetric('avg_response_time', fn() => AgentTrace::avg('response_time'));
   

Advanced Patterns

1. Tool Pipeline Composition:

   // app/Tools/Composite/ProcessOrderPipeline.php
   ToolChain::create('order_processing')
       ->pipe(ValidateOrderTool::class)
       ->transform(fn($data) => ['valid' => true, 'order' => $data])
       ->when(fn($data) => $data['valid'])
       ->pipe(ChargePaymentTool::class)
       ->pipe(NotifyCustomerTool::class);
   

2. Agent Delegation:

   // In parent agent
   protected function handleComplexRequest(string $input): string {
       return $this->delegateTo('specialist_agent')
           ->withInput($input)
           ->withMemory($this->memory)
           ->execute();
   }
   

3. Evaluation Framework:

   // Test agent quality
   $results = AgentEvaluator::run('customer_support')
       ->withTestCases([
           'test_cancel_order' => 'I want to cancel my order',
           'test_refund_request' => 'How do I get a refund?',
       ])
       ->withEvaluator('gpt-4')
       ->execute();
   

Gotchas and Tips

Common Pitfalls

1. Tool Schema Mismatches:

   • Problem: Agent fails to use tools due to parameter type mismatches
   • Solution: Validate schemas with:

     $this->validateToolSchema(OrderLookupTool::class);
     

2. Memory Bloat:

   • Problem: Vector store grows too large
   • Solution: Implement retention policies:

     $this->memory()->withRetentionPolicy(7); // 7 days
     

3. Token Budget Exceeds:

   • Problem: Complex workflows hit API limits
   • Solution: Use streaming and chunking:

     $response = CustomerSupportAgent::run('...')
         ->stream()
         ->chunk(1000)
         ->go();
     

4. Circular Dependencies:

   • Problem: Tools calling each other recursively
   • Solution: Add depth tracking:

     $this->toolChain->withMaxDepth(5);
     

Debugging Tips

1. Trace Visualization:

   php artisan vizra:trace:view latest
   

   • Shows execution flow with timing metrics

2. Tool Logging:

   // Enable verbose tool logging
   config(['vizra.debug.tools' => true]);
   

3. Memory Inspection:

   // Dump agent memory
   dd($agent->memory()->getFacts());
   

Configuration Quirks

1. Model Provider Switching:

   • Tip: Use environment-based config:

     // config/vizra.php
     'providers' => env('LLM_PROVIDER') === 'google'
         ? 'google'
         : 'openai',
     

2. Dashboard Permissions:

   • Gotcha: Livewire components need proper middleware
   • Fix:

     Route::middleware(['auth:sanctum', 'can:access,vizra'])->group(...);
     

3. Queue Workers:

   • Tip: Use separate queues for different agent types:

     $agent->queueOn('high_priority');
     

Extension Points

1. Custom Evaluators:

   // app/Providers/VizraServiceProvider.php
   VizraADK::extend('custom_evaluator', function () {
       return new CustomEvaluator(
           app(LLMClient::class),
           app(EvaluationMetrics::class)
       );
   });
   

2. Memory Adapters:

   // Register custom memory store
   VizraADK::extendMemory('redis', function () {
       return new RedisMemoryStore(
           app(Redis::class),
           config('vizra.memory.ttl')
       );
   });
   

3. Agent Middleware:

   // Add pre/post execution hooks
   VizraADK::macro('beforeRun', function ($callback) {
       $this->beforeRunCallbacks[] = $callback;
   });
   
   // Usage:
   Agent::beforeRun(function ($agent, $input) {
       $agent->memory()->addFact("Initial input: {$input}");
   });
   

Performance Optimization

1. Caching Strategies:

   // Cache frequent tool responses
   $tool->withCache(function ($args) {
       return Cache::remember(
           "tool:{$this->name}:{$args['order_id']}",
           now()->addHours(1),
           fn() => $this->execute($args, $context)
       );
   });
   

2. Batch Processing:

   // Process multiple orders in one API call
   $results = OrderBatchProcessor::process([
       $order1->id,
       $order2->id,
   ]);
   

3. Memory Compression:

   // Use smaller embedding models for memory
   $this->memory()->withEmbeddingModel('text-embedding-ada-002');
   

Security Considerations

1. Tool Input Validation:

   //