Vizra Adk Laravel Package

Getting Started

Minimal Steps

1. Installation:

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

   • Publishes config, migrations, and Livewire dashboard assets.

2. First Agent:

   php artisan vizra:make:agent CustomerSupportAgent
   

   • Generates a scaffolded agent class in app/Agents/.

3. Quick Test:

   php artisan vizra:chat customer_support
   

   • Opens Tinker with a pre-configured chat session.

Where to Look First

• Agent Scaffolding: app/Agents/ - Auto-discovered agent classes.
• Tool Definitions: app/Tools/ - Custom tool implementations.
• Config: config/vizra.php - API keys, model defaults, and behavior settings.
• Dashboard: /vizra - Livewire-powered UI for testing and monitoring.

First Use Case

Create a simple support agent that can:

1. Look up orders via a custom tool
2. Generate responses using the LLM
3. Maintain conversation history

// 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];

    public function handleOrderInquiry(string $orderId): string
    {
        return $this->run("Handle customer inquiry for order #{$orderId}")
            ->forUser(auth()->user())
            ->go();
    }
}

Implementation Patterns

Core Workflows

1. Agent Execution Flow:

   // Basic execution
   $response = CustomerSupportAgent::run('User query')
       ->forUser($user)
       ->withMemory($memory)
       ->go();
   
   // With streaming
   $response = CustomerSupportAgent::run('User query')
       ->stream(fn($token) => Log::info($token))
       ->go();
   

2. Tool Integration Pattern:

   // In your agent's tools array
   protected array $tools = [
       DatabaseQueryTool::class,
       PaymentProcessorTool::class,
       EmailSenderTool::class,
   ];
   
   // Tool implementation
   class DatabaseQueryTool implements ToolInterface
   {
       public function definition(): array
       {
           return [
               'name' => 'db_query',
               'description' => 'Execute SQL queries',
               'parameters' => [
                   'type' => 'object',
                   'properties' => [
                       'query' => ['type' => 'string'],
                       'params' => ['type' => 'array']
                   ]
               ]
           ];
       }
   
       public function execute(array $args, AgentContext $context): string
       {
           return DB::select($args['query'], $args['params']);
       }
   }
   

3. Memory Management:

   // Persistent memory
   $memory = AgentMemory::create()
       ->addFact('user_preferences', $user->preferences)
       ->persist();
   
   // Session memory
   $session = $this->memory->startSession()
       ->add('last_query', $query)
       ->end();
   

Integration Tips

1. Laravel Events:

   // Trigger agent on event
   event(new OrderCreated($order))
       ->then(fn() => CustomerSupportAgent::run(
           "Notify customer about order #{$order->id}"
       )->forUser($order->user)->go());
   

2. Queue Jobs:

   // Dispatch async agent execution
   CustomerSupportAgent::run('Process refund')
       ->forUser($user)
       ->dispatch()
       ->onQueue('agents');
   

3. Livewire Integration:

   // In Livewire component
   public function handleUserMessage(string $message)
   {
       $response = CustomerSupportAgent::run($message)
           ->forUser($this->user)
           ->go();
   
       $this->messages[] = [
           'user' => $message,
           'bot' => $response->content
       ];
   }
   

4. API Endpoints:

   Route::post('/agents/chat', function (Request $request) {
       $agent = CustomerSupportAgent::run($request->input('message'))
           ->forUser(auth()->user())
           ->go();
   
       return response()->json($agent->toArray());
   });
   

Advanced Patterns

1. Agent Composition:

   // Delegate to specialized agents
   class MasterAgent extends BaseLlmAgent
   {
       public function handleRequest(string $query): string
       {
           $specializedAgents = [
               'orders' => OrderAgent::class,
               'support' => SupportAgent::class,
               'billing' => BillingAgent::class
           ];
   
           $agentClass = collect($specializedAgents)
               ->first(fn($class, $key) =>
                   str_contains($query, $key)
               );
   
           return $agentClass::run($query)->go();
       }
   }
   

2. Tool Pipelines:

   // Complex workflow tool
   class OrderFulfillmentPipelineTool implements ToolInterface
   {
       public function execute(array $args, AgentContext $context): string
       {
           return ToolChain::create('fulfillment')
               ->pipe(ValidateOrderTool::class)
               ->pipe(InventoryCheckTool::class)
               ->pipe(ShippingScheduleTool::class)
               ->execute($args, $context);
       }
   }
   

3. Evaluation Framework:

   // Test agent responses
   $evaluation = AgentEvaluator::create()
       ->forAgent(CustomerSupportAgent::class)
       ->withTestCases([
           'test_order_inquiry' => [
               'input' => 'Where is my order?',
               'expected' => 'contains tracking number'
           ]
       ])
       ->run();
   
   $results = $evaluation->getResults();
   

Gotchas and Tips

Common Pitfalls

1. Tool Parameter Validation:

   • Issue: Tools may fail silently with malformed parameters
   • Fix: Always validate inputs in execute():

     if (!isset($args['order_id'])) {
         throw new \InvalidArgumentException('Order ID required');
     }
     

2. Memory Leaks:

   • Issue: Unbounded memory growth from long conversations
   • Fix: Implement memory pruning:

     $memory->pruneOlderThan(Carbon::now()->subDays(7));
     

3. API Rate Limits:

   • Issue: Unexpected failures from LLM provider throttling
   • Fix: Configure retry logic in config/vizra.php:

     'llm' => [
         'retry_attempts' => 3,
         'retry_delay' => 1000, // ms
     ],
     

4. Circular Dependencies:

   • Issue: Tools calling each other recursively
   • Fix: Implement depth tracking:

     if ($context->get('call_depth') > 5) {
         throw new \RuntimeException('Maximum call depth exceeded');
     }
     

Debugging Tips

1. Execution Tracing:

   php artisan vizra:trace --agent=CustomerSupportAgent --query="test"
   

   • View full execution path with tool calls and LLM prompts

2. Memory Inspection:

   $memory = AgentMemory::find($memoryId);
   dd($memory->getFacts());
   

3. Tool Logging:

   // Add to tool execute method
   Log::debug('Tool executed', [
       'tool' => $this->definition()['name'],
       'args' => $args,
       'context' => $context->toArray()
   ]);
   

Configuration Quirks

1. Model Fallbacks:

   • Configure fallback models in config/vizra.php:

     'models' => [
         'default' => 'gpt-4o',
         'fallback' => [
             'gpt-4o' => 'gpt-4',
             'gpt-4' => 'gpt-3.5-turbo'
         ]
     ],
     

2. Tool Discovery:

   • Ensure tools are in app/Tools/ or registered via service provider:

     $this->app->bind(
         ToolInterface::class,
         InventoryCheckTool::class
     );
     

3. Memory Storage:

   • Customize storage engine:

     'memory' => [
         'driver' => 'database', // or 'redis', 'filesystem'
         'table' => 'agent_memories',
     ],
     

Extension Points

1. Custom Prompt Templates:

   // Override default prompt structure
   AgentBuilder::macro('withCustomPrompt', function ($template) {
       $this->promptTemplate = $template;
       return $this;
   });
   

2. Evaluation Metrics:

   // Add custom evaluation metric
   AgentEvaluator::