Laragent Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation:

   composer require maestroerror/laragent
   php artisan vendor:publish --tag="laragent-config"
   

   Configure config/laragent.php with your API keys (e.g., OPENAI_API_KEY).

2. Generate Your First Agent:

   php artisan make:agent CustomerSupportAgent
   

   This creates a new agent class in app/AiAgents/ with a familiar Eloquent-like structure.

3. Define Agent Behavior:

   // app/AiAgents/CustomerSupportAgent.php
   class CustomerSupportAgent extends Agent
   {
       protected $model = 'gpt-4';
       protected $temperature = 0.3;
   
       public function instructions()
       {
           return "You are a customer support agent. Be polite and concise.";
       }
   
       #[Tool('Fetch user order details')]
       public function getOrderDetails($orderId)
       {
           return Order::find($orderId)->toArray();
       }
   }
   

4. Use the Agent:

   $response = CustomerSupportAgent::forUser(auth()->user())
       ->respond("How can I track my order #12345?");
   

5. Test Locally: Use the LarAgent\Testing\TestAgent facade to mock responses during development:

   TestAgent::fake([
       CustomerSupportAgent::class => fn($message) => "Order #12345 is in transit."
   ]);
   

Implementation Patterns

Core Workflows

1. Agent Lifecycle:

   • Creation: Use make:agent for boilerplate.
   • Configuration: Override properties ($model, $temperature) or methods (instructions(), prompt()).
   • Execution: Chain methods like forUser() or for("custom_history") before respond().

2. Tool Integration:

   • Method Tools: Annotate public methods with #[Tool('description')].
   • Facade Tools: Use Tool::create() for dynamic tools:

     $tool = Tool::create('SearchDatabase', fn($query) => DB::table('products')->where('name', 'like', "%$query%")->get());
     

   • Parallel Execution: Enable via $parallelToolCalls = true (default: false).

3. Multi-Agent Workflows:

   • Sequential Chaining:

     $agent1 = new FirstAgent();
     $agent2 = new SecondAgent();
     $result = $agent1->respond($message)->then($agent2);
     

   • Event-Driven Coordination: Listen to AgentResponding events to trigger other agents.

4. Memory Management:

   • Per-User History: Defaults to CacheChatHistory (configured in config/laragent.php).
   • Custom Storage: Extend ChatHistory and bind via service provider:

     $this->app->bind(\LarAgent\History\ChatHistory::class, CustomChatHistory::class);
     

5. API Exposure:

   • OpenAI-Compatible Endpoint: Use LarAgent\OpenAi\OpenAiController for direct API access.
   • Structured Output: Return JSON-schema-validated responses:

     #[Tool('ValidateUserInput', outputSchema: ['type' => 'object', 'properties' => ['valid' => ['type' => 'boolean']]])]
     public function validateInput($input) { ... }
     

Integration Tips

• Queue Jobs: Wrap agent responses in dispatch() for async processing:

  dispatch(new ProcessAgentResponse($agent, $message));
  

• Event Observers: Hook into AgentResponded to log or transform responses:

  event(new AgentResponded($agent, $response));
  

• Testing: Use TestAgent::fake() to mock responses in unit tests:

  TestAgent::fake([
      CustomerSupportAgent::class => fn($msg) => "Mocked: $msg"
  ]);
  

Gotchas and Tips

Pitfalls

1. Tool Validation:

   • Issue: Tools with complex schemas may fail silently if strict: false (default in some drivers like Anthropic).
   • Fix: Explicitly set outputSchema with additionalProperties: false:

     #[Tool(outputSchema: ['type' => 'object', 'properties' => ['id' => ['type' => 'string']], 'additionalProperties' => false])]
     

2. Token Limits:

   • Issue: Long conversations may hit OpenAI’s 4096-token limit.
   • Fix:
     • Use default_truncation_threshold in config to auto-truncate.
     • Switch to gpt-4 (32k context) or implement custom chunking via ChatHistory.

3. Provider Fallbacks:

   • Issue: Fallback providers (protected $provider = ['primary', 'fallback']) may not respect per-agent overrides.
   • Fix: Use config(['laragent.providers.primary' => [...]]) dynamically.

4. Event Order:

   • Issue: AgentResponding fires before tool execution, while AgentResponded fires after.
   • Fix: Use AgentToolExecuting for tool-specific hooks.

5. Memory Leaks:

   • Issue: InMemoryChatHistory retains all conversations in RAM.
   • Fix: Switch to CacheChatHistory or implement TTL:

     protected $history = \LarAgent\History\CacheChatHistory::class;
     protected $historyTTL = 60 * 60 * 24; // 1 day
     

Debugging Tips

• Enable Logging:

  config(['laragent.log' => true]);
  

  Check storage/logs/laragent.log for driver interactions.

• Inspect Tools: Use dd($agent->getTools()) to verify tool definitions before execution.

• Streaming Debug: For sendMessageStreamed(), log chunks:

  $agent->sendMessageStreamed($message)->each(function ($chunk) {
      Log::debug($chunk);
  });
  

Extension Points

1. Custom Drivers:

   • Extend LarAgent\Drivers\LlmDriver and bind in AppServiceProvider:

     $this->app->bind(\LarAgent\Drivers\LlmDriver::class, CustomDriver::class);
     

2. Chat History:

   • Implement LarAgent\History\ChatHistory and register:

     $this->app->bind(\LarAgent\History\ChatHistory::class, function ($app, $params) {
         return new DatabaseChatHistory($params['user_id']);
     });
     

3. Events:

   • Listen to built-in events (e.g., AgentResponding) or dispatch custom ones:

     event(new CustomAgentEvent($agent, $response));
     

4. Artisan Commands:

   • Extend LarAgent\Console\MakeAgentCommand to add custom agent templates.

Config Quirks

• Provider Overrides: Per-agent provider configs override global settings but ignore api_key (always uses global).

  // Override model but keep global API key
  protected $provider = 'custom';
  protected $model = 'gemini-1.0';
  

• Parallel Tools: Disabling $parallelToolCalls improves reliability but may increase latency for sequential tools.

• Extras Handling: Driver-specific extras (e.g., reasoning_effort for OpenAI Responses API) must be set in $extras:

  protected $extras = ['reasoning_effort' => 'high'];