AI Agents

class AdvancedAgent extends BaseLlmAgent
{
    // Model configuration
    protected string $model = 'gpt-4o';
    protected ?float $temperature = 0.7;
    protected ?int $maxTokens = 1000;
    protected ?float $topP = 0.9;

    // Tools this agent can use
    protected array $tools = [
        OrderLookupTool::class,
        RefundProcessorTool::class,
        EmailSenderTool::class,
    ];

    // Sub-agents this agent can delegate to
    protected array $subAgents = [
        TechnicalSupportAgent::class,
        BillingSupportAgent::class,
    ];

    // Enable streaming responses
    protected bool $streaming = false;
}

// Basic conversational usage
$response = CustomerSupportAgent::run('How do I reset my password?')
    ->go();

// With user context
$response = CustomerSupportAgent::run('Show me my recent orders')
    ->forUser($user)
    ->go();

// With session for conversation continuity
$response = CustomerSupportAgent::run('What was my previous question?')
    ->withSession($sessionId)
    ->go();

// Event-driven execution
OrderProcessingAgent::run($orderCreatedEvent)
    ->async()
    ->go();

// Data analysis with context
$insights = AnalyticsAgent::run($salesData)
    ->withContext(['period' => 'last_quarter'])
    ->go();

// Process large datasets asynchronously
DataProcessorAgent::run($largeDataset)
    ->async()
    ->onQueue('processing')
    ->go();

// Monitor system health with thresholds
SystemMonitorAgent::run($metrics)
    ->withContext(['threshold' => 0.95])
    ->go();

// Generate reports with specific formats
$report = ReportAgent::run('weekly_summary')
    ->withContext(['format' => 'pdf'])
    ->go();

// Enable streaming for real-time responses
$stream = StorytellerAgent::run('Tell me a story')
    ->streaming()
    ->go();

foreach ($stream as $chunk) {
    echo $chunk;
    flush();
}

// Enable history for conversational agents
class ChatAgent extends BaseLlmAgent
{
    protected bool $includeConversationHistory = true; // Send history to LLM
    protected string $contextStrategy = 'recent'; // 'none', 'recent', 'full'
    protected int $historyLimit = 10; // last 10 messages (for 'recent' strategy)
}

// Override at runtime
$context->setState('include_history', true);
$context->setState('history_depth', 5);

class CustomAgent extends BaseLlmAgent
{
    public function beforeLlmCall(array $inputMessages, AgentContext $context): array
    {
        // Modify messages before sending to LLM
        // This is also where tracing starts
        return $inputMessages;
    }

    public function afterLlmResponse(Response|Generator $response, AgentContext $context, ?PendingRequest $request = null): mixed
    {
        // Process the LLM response
        // Access token usage: $response->usage
        // Access original request: $request
        return $response;
    }

    public function beforeToolCall(string $toolName, array $arguments, AgentContext $context): array
    {
        // Modify tool arguments before execution
        return $arguments;
    }

    public function afterToolResult(string $toolName, string $result, AgentContext $context): string
    {
        // Process tool results
        return $result;
    }

    public function onToolException(string $toolName, Throwable $e, AgentContext $context): void
    {
        // Handle tool execution errors
        // Log errors, send alerts, or implement recovery strategies
    }
}

// Use a specific prompt version
$response = CustomerSupportAgent::run('Help me with my order')
    ->withPromptVersion('friendly')
    ->go();

// A/B test different tones
$version = rand(0, 1) ? 'professional' : 'casual';
$response = CustomerSupportAgent::run($query)
    ->withPromptVersion($version)
    ->go();

class CustomerSupportAgent extends BaseLlmAgent
{
    protected function getPromptData(AgentContext $context): array
    {
        return [
            'company_name' => config('app.company_name'),
            'support_hours' => '9 AM - 5 PM EST',
            'ticket_count' => $this->getUserTicketCount($context),
        ];
    }
}

Welcome to {{ $company_name }} support!
Our hours: {{ $support_hours }}

@if($ticket_count > 0)
You have {{ $ticket_count }} open tickets.
@endif

class CustomerServiceManager extends BaseLlmAgent
{
    protected string $name = 'customer_service_manager';

    protected string $instructions = "You are a customer service manager.
        Route technical questions to the technical support agent.
        Route billing questions to the billing agent.
        Handle general inquiries yourself.";

    protected array $subAgents = [
        TechnicalSupportAgent::class,
        BillingSupportAgent::class,
        SalesAgent::class,
    ];
}

User: "My payment failed"
  ↓
Manager Agent analyzes the request
  ↓
Decides: "This is a billing issue"
  ↓
Delegates to BillingSupportAgent
  ↓
BillingSupportAgent handles the request
  ↓
Response returned to user

class TechnicalSupportAgent extends BaseLlmAgent
{
    protected string $name = 'technical_support';

    protected string $description = 'Handles technical issues, bugs, and integration problems';

    protected string $instructions = "You are a technical support specialist.
        Help users with technical issues, debugging, and integration problems.
        Be patient and thorough in your explanations.";

    protected array $tools = [
        LogLookupTool::class,
        SystemStatusTool::class,
    ];
}

class BillingSupportAgent extends BaseLlmAgent
{
    protected string $name = 'billing_support';

    protected string $description = 'Handles billing, payments, and subscription questions';

    protected string $instructions = "You are a billing specialist.
        Help users with payment issues, invoices, and subscription management.";

    protected array $tools = [
        InvoiceLookupTool::class,
        RefundProcessorTool::class,
    ];
}

// Execute agent asynchronously via queue
$job = DataProcessorAgent::run($largeDataset)
    ->async()
    ->onQueue('processing')
    ->go();

// With delay and retries
$job = ReportAgent::run('quarterly_report')
    ->delay(300) // 5 minutes
    ->tries(3)
    ->timeout(600) // 10 minutes
    ->go();

// Send images with your request
$response = VisionAgent::run('What\'s in this image?')
    ->withImage('/path/to/image.jpg')
    ->go();

// Multiple images and documents
$response = DocumentAnalyzer::run('Summarize these documents')
    ->withDocument('/path/to/report.pdf')
    ->withImage('/path/to/chart.png')
    ->withImageFromUrl('https://example.com/diagram.jpg')
    ->go();

// Override agent parameters at runtime
$response = CreativeWriterAgent::run('Write a poem')
    ->temperature(0.9) // More creative
    ->maxTokens(500)
    ->go();

// Set multiple parameters
$response = AnalyticalAgent::run($data)
    ->withParameters([
        'temperature' => 0.2,
        'max_tokens' => 2000,
        'top_p' => 0.95
    ])
    ->go();

// Add custom context
$response = ShoppingAssistant::run('Find me a laptop')
    ->withContext([
        'budget' => 1500,
        'preferences' => ['brand' => 'Apple'],
        'location' => 'New York'
    ])
    ->go();

1. Your Code → AgentExecutor (Fluent API)
2. AgentExecutor → AgentManager (Orchestration)
3. AgentManager → Agent Instance (Your Logic)
4. Agent → LLM Provider (AI Processing)
5. LLM → Tools (If Needed)
6. Response → Back Through the Chain

public function beforeLlmCall(array $messages, AgentContext $context): array
{
    // Add user preferences to system message
    $messages[0]['content'] .= "\nUser prefers formal tone.";
    return $messages;
}

public function afterLlmResponse(Response $response, AgentContext $context, ?PendingRequest $request): mixed
{
    // Log token usage and request details for monitoring
    Log::info('LLM call completed', [
        'model' => $request?->model(),
        'usage' => $response->usage
    ]);
    return $response;
}

public function beforeToolCall(string $toolName, array $arguments, AgentContext $context): array
{
    // Add API keys or validate permissions
    if ($toolName === 'weather_api') {
        $arguments['api_key'] = config('services.weather.key');
    }
    return $arguments;
}