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, sessions, and memory

2. First Agent Creation:

   php artisan vizra:make:agent CustomerSupportAgent
   

   • Generates a scaffolded agent class in app/Agents

3. Immediate Usage:

   // In a controller or command
   $response = CustomerSupportAgent::run('User query here')
       ->forUser(auth()->user())
       ->go();
   

Where to Look First

• Core Classes:

  • app/Agents/ - Your custom agent implementations
  • app/Tools/ - Custom tool implementations
  • config/vizra-adk.php - Configuration options

• Key Facades:

  use Vizra\VizraADK\Facades\Agent;
  use Vizra\VizraADK\Facades\Tool;
  

• Artisan Commands:

  php artisan vizra:chat [agent-name]       # Interactive testing
  php artisan vizra:make:agent [name]      # Generate agent scaffold
  php artisan vizra:make:tool [name]       # Generate tool scaffold
  php artisan vizra:make:toolbox [name]    # Generate toolbox scaffold
  

First Use Case

Create a simple customer support agent that can:

1. Answer FAQs using persistent memory
2. Look up orders via a custom tool
3. Delegate complex issues to a specialist agent

// app/Agents/CustomerSupportAgent.php
class CustomerSupportAgent extends BaseLlmAgent
{
    protected string $name = 'customer_support';
    protected string $description = 'Handles customer inquiries';
    protected string $instructions = 'Be helpful and professional...';
    protected string $model = 'gpt-4o';

    protected array $tools = [
        OrderLookupTool::class,
        FaqMemoryTool::class,
        DelegateToEscalationTool::class,
    ];

    public function handleFaq(string $question): string
    {
        return $this->useTool(FaqMemoryTool::class, ['question' => $question]);
    }
}

Implementation Patterns

Core Workflows

1. Agent Execution Flow:

   // Basic execution
   $response = CustomerSupportAgent::run('My order is late')
       ->forUser($user)
       ->withMemory('previous_conversations')
       ->go();
   
   // With streaming
   $response = CustomerSupportAgent::run('Complex query')
       ->stream()
       ->go(function ($chunk) {
           echo $chunk;
       });
   

2. Tool Integration Pattern:

   // Using tools directly
   $orderData = $agent->useTool(OrderLookupTool::class, [
       'order_id' => 'ORD12345'
   ]);
   
   // Conditional tool usage
   if ($agent->shouldUseTool('order_lookup')) {
       $result = $agent->useTool('order_lookup', ['order_id' => $id]);
   }
   

3. Memory Management:

   // Persistent memory
   $agent->remember('user_preferences', $preferences);
   
   // Session memory
   $agent->session()->remember('current_context', $context);
   
   // Vector memory (RAG)
   $agent->useMemory('product_knowledge')
         ->search('What are your best selling items?');
   

4. Workflow Construction:

   // Sequential workflow
   $workflow = AgentWorkflow::create()
       ->step('greet_customer')
       ->step('check_order_status')
       ->step('offer_resolution')
       ->build();
   
   $result = $workflow->execute($agent);
   

Integration Tips

1. Laravel Service Providers:

   // Register custom agents/tools
   public function register()
   {
       $this->app->bind('custom.agent', function() {
           return new CustomAgent();
       });
   }
   
   // Bind tools to container
   Tool::extend('custom_tool', function() {
       return new CustomTool();
   });
   

2. Event Listeners:

   // Listen to agent events
   event(new AgentStarted($agent, $user, $input));
   event(new AgentCompleted($agent, $response));
   

3. Queue Jobs:

   // Queue agent execution
   QueueAgentExecution::dispatch($agentName, $input, $userId)
       ->onConnection('database')
       ->delay(now()->addMinute());
   

4. Livewire Integration:

   // In a Livewire component
   public $agentResponse = '';
   
   public function handleUserInput(string $input)
   {
       $this->agentResponse = Agent::run('chat_agent')
           ->forUser(auth()->user())
           ->run($input);
   }
   

5. Testing Pattern:

   // Using the testing helpers
   $response = Agent::test('customer_support')
       ->withInput('My order is late')
       ->expectOutputContains('shipping delay')
       ->run();
   
   // Mock tools for testing
   Tool::fake(OrderLookupTool::class)
       ->shouldReturn(['status' => 'shipped']);
   

Advanced Patterns

1. Agent Composition:

   // Create composite agents
   $composite = AgentComposer::create()
       ->addAgent('customer_support')
       ->addAgent('technical_support')
       ->withFallbackTo('customer_support')
       ->build();
   

2. Dynamic Tool Loading:

   // Load tools based on context
   $tools = [];
   if ($user->isPremium()) {
       $tools[] = PremiumSupportTool::class;
   }
   $tools[] = StandardSupportTool::class;
   
   return Agent::build('support_agent')
       ->withTools($tools)
       ->register();
   

3. Memory Augmentation:

   // Augment memory with external data
   $memory = Memory::create()
       ->withSource('database', function() {
           return Product::all()->pluck('description');
       })
       ->withSource('api', function() {
           return Http::get('https://api.example.com/pricing')->json();
       })
       ->build();
   

4. Evaluation Framework:

   // Create test cases
   $test = AgentTest::create('customer_support')
       ->withInput('How do I return an item?')
       ->expectOutputContains(['return policy', '30 days'])
       ->expectNoOutputContains(['refund', 'chargeback'])
       ->build();
   
   // Run evaluation
   $results = AgentEvaluator::run($test);
   

Gotchas and Tips

Common Pitfalls

1. Tool Execution Errors:

   • Issue: Tools failing silently due to improper error handling
   • Fix: Always wrap tool execution in try-catch:

     try {
         return $this->useTool($tool, $args);
     } catch (ToolExecutionException $e) {
         return $this->handleToolFailure($e);
     }
     

2. Memory Bloat:

   • Issue: Unbounded memory growth causing performance issues
   • Fix: Implement TTL policies:

     // In config/vizra-adk.php
     'memory' => [
         'ttl' => [
             'session' => 30, // minutes
             'persistent' => 30, // days
         ],
     ]
     

3. Streaming Issues:

   • Issue: Streaming responses getting cut off
   • Fix: Ensure proper chunk handling:

     $response = $agent->run($input)->stream();
     $response->onChunk(function($chunk) {
         echo $chunk->text;
         flush();
     });
     

4. Token Limits:

   • Issue: Agents hitting token limits unexpectedly
   • Fix: Monitor and adjust:

     // Check token usage before execution
     $tokenUsage = $agent->estimateTokenUsage($input);
     if ($tokenUsage > config('vizra-adk.max_tokens')) {
         $agent->compressMemory();
     }
     

5. Circular Dependencies:

   • Issue: Agents/tools creating circular references
   • Fix: Use dependency injection carefully:

     // Avoid direct instantiation in tools
     public function __construct(
         private readonly ToolManager $toolManager
     ) {}
     

Debugging Tips

1. Tracing System:

   // Enable detailed tracing
   $agent->enableTracing()
        ->withTraceLevel('debug')
        ->go();
   
   // View traces in dashboard
   route('vizra.traces.index');
   

2. Tool Debugging:

   // Log tool execution details
   Tool::macro('debug', function($toolName) {
       return function($args) use ($toolName) {
           \Log::debug("Executing $toolName with args: " . json_encode($args));
           return $this->execute($