Getting Started

First Steps

Installation: Add LarAgent via Composer:

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

Configure Providers: Update config/laragent.php with your API keys (e.g., OpenAI, Anthropic) and preferred defaults.
Create Your First Agent: Generate an agent class:
```
php artisan make:agent CustomerSupportAgent
```
Define Agent Logic: Customize the generated agent class (app/AiAgents/CustomerSupportAgent.php) with:
- Instructions (instructions() method)
- Tools (annotated methods with #[Tool])
- Provider/config overrides (e.g., $model = 'gpt-4')

Test Locally: Use Tinker to interact with your agent:

php artisan tinker

$agent = new \App\AiAgents\CustomerSupportAgent();
$response = $agent->forUser(auth()->user())->respond("How do I reset my password?");
dd($response);

Key First-Use Cases

Chatbot Integration: Build a real-time chat interface using the agent’s respond() method.
Automated Workflows: Chain agent responses with Laravel queues for async processing.
Tool Integration: Connect to external APIs via annotated tools (e.g., database queries, payment processing).

Implementation Patterns

Core Workflows

Agent Lifecycle:
- Creation: Extend LarAgent\Agent and override methods like instructions().
- Execution: Use respond() with optional context (user, history name).
- Tool Usage: Annotate methods with #[Tool] and define input/output schemas.
Provider Management:
- Multi-Provider Fallback: Configure an array of providers in $provider (e.g., ['openai', 'gemini']).
- Dynamic Overrides: Override provider settings per agent (e.g., $temperature = 0.3).
History Handling:
- Per-User Storage: Use forUser() to scope history to authenticated users.
- Custom Namespaces: Pass a string to for() to create isolated chat histories (e.g., for("support_tickets")).
Tool Integration:
- Method-Based Tools: Annotate public methods with #[Tool] and define parameters.
- Facade Tools: Use Tool::make() for reusable tools outside agent classes.
- Parallel Execution: Enable $parallelToolCalls = true for concurrent tool calls.

Integration Tips

Laravel Events: Listen to AgentResponding, AgentResponded, or ToolExecuting events for custom logic.
API Exposure: Use the built-in OpenAI-compatible endpoint (/api/agents/{agent}) for frontend integration.

Queue Jobs: Wrap agent responses in AgentJob for async processing:

AgentJob::dispatch(new CustomerSupportAgent(), $message, $user);

Testing: Mock agents with LarAgent\Testing\Fakes\FakeAgent for unit tests.

Example: Multi-Step Agent

class OrderProcessingAgent extends Agent {
    protected $tools = ['fetchOrder', 'updateOrderStatus'];

    #[Tool('Fetch order details by ID')]
    public function fetchOrder(string $orderId) {
        return Order::findOrFail($orderId)->toArray();
    }

    #[Tool('Update order status')]
    public function updateOrderStatus(string $orderId, string $status) {
        return Order::where('id', $orderId)->update(['status' => $status]);
    }

    public function instructions() {
        return "Process customer orders by fetching details and updating statuses.";
    }
}

Gotchas and Tips

Common Pitfalls

Tool Schema Mismatches:
- Issue: Tools may fail if input schemas don’t match the agent’s expectations.
- Fix: Use #[Tool(schema: "...")] to explicitly define JSON schemas for complex tools.
- Debug: Check laravel.log for ToolValidationException errors.
Rate Limits:
- Issue: High temperature or large context windows may trigger API rate limits.
- Fix: Implement AgentRateLimited event listeners or use fallback providers.
History Bloat:
- Issue: In-memory history grows unbounded.
- Fix: Switch to CacheChatHistory or DatabaseChatHistory for persistent storage.
Parallel Tool Calls:
- Issue: Disabled by default ($parallelToolCalls = false), which may slow down workflows.
- Fix: Enable for performance-critical tools, but handle race conditions in tool logic.

Debugging Tips

Log Agent Interactions: Use AgentResponding event to log input/output:
```
event(new AgentResponding($agent, $message, $history));
```
Inspect Tools: Dump tool definitions with:
```
dd($agent->getTools());
```

Test Providers: Use the fake provider for offline testing:

config(['laragent.providers.default.driver' => \LarAgent\Drivers\Fake\FakeDriver::class]);

Configuration Quirks

Provider Labels:
- Must match keys in config/laragent.php (case-sensitive).
- Example: $provider = 'openai' requires 'openai' => [...] in config.
Chat History Keys:
- Default key format: {agent_class}:{user_id}:{history_name}.
- Override with $historyKey property in the agent class.
Extras Handling:
- Model-specific extras (e.g., reasoning_effort) must be set in $extras:
```
protected $extras = ['reasoning_effort' => 'high'];
```

Extension Points

Custom Drivers:

Extend LarAgent\Drivers\LlmDriver and register in config/laragent.php:

'custom_driver' => [
    'driver' => \App\Drivers\CustomDriver::class,
    // ...
],

Chat History:
- Create a new history class extending LarAgent\History\ChatHistory and publish it:
```
php artisan make:history CustomDatabaseHistory
```
Events:
- Extend agent behavior by listening to events (e.g., AgentResponded):
```
event(new AgentResponded($agent, $response));
```

Tool Facade:

Tool::extend('custom', function () {
    return new CustomTool();
});

Performance Tips

Batch Tools: Group related tools into a single method to reduce API calls.
Cache Responses: Use Laravel’s cache to store frequent tool responses.
Streaming: Use respondStreamed() for large responses to avoid memory issues.

Security Notes

API Keys: Never hardcode keys; use environment variables or Laravel’s vault.
Tool Validation: Always validate tool inputs to prevent injection attacks.

Rate Limiting: Implement middleware to throttle agent requests:

Route::middleware(['throttle:10,1'])->group(function () {
    Route::post('/api/agents/{agent}', [AgentController::class, 'respond']);
});

Laragent Laravel Package