🎯 What's an Agent?

Think of agents as your smart AI assistants that can handle complex tasks, remember conversations, and even work with other agents. They're not just chatbots – they're intelligent systems that can analyze data, make decisions, and take actions! 🚀

🏗️ Creating Your First Agent

Ready to build your first AI agent? It's easier than you think! Let's create a helpful customer support agent that can answer questions and solve problems.

⚡ Quick Start with Artisan

Fire up your terminal and run this magical command:

php artisan vizra:make:agent CustomerSupportAgent

Boom! 💥 You've just created your first agent! Let's peek inside and see what makes it tick:

📝 The Agent Blueprint

<?php

namespace App\Agents;

use Vizra\VizraADK\Agents\BaseLlmAgent;

class CustomerSupportAgent extends BaseLlmAgent
{
    protected string $name = 'customer_support';

    protected string $description = 'Handles customer inquiries and support requests';

    protected string $instructions = "You are a helpful customer support assistant.
                Be friendly, professional, and solution-oriented.
                Always prioritize customer satisfaction.";

    // Optional: Specify model and parameters
    protected string $model = 'gpt-4o';
    protected ?float $temperature = 0.7;
    protected ?int $maxTokens = 1000;
}

Agent Configuration Options

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

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

🚀 Unleashing Your Agent's Powers

Now comes the fun part – putting your agent to work! Vizra ADK gives you six amazing ways to interact with your agents, each perfect for different scenarios.

💬 Let's Chat! Using the Fluent API

Working with agents feels natural with our fluent API. Check out these examples:

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

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

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

// Event-driven execution
OrderProcessingAgent::trigger($orderCreatedEvent)
    ->async()
    ->execute();

// Data analysis
$insights = AnalyticsAgent::analyze($salesData)
    ->withContext(['period' => 'last_quarter'])
    ->execute();

🌊 Real-time Magic with Streaming

Want to see your agent think in real-time? Enable streaming for that ChatGPT-like experience:

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

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

🔧 Customizing Agent Behavior

Want to add your own special sauce? 🌶️ Agents come with powerful lifecycle hooks that let you customize exactly how they work. It's like having backstage passes to your agent's brain!

Here's how to use these superpowers:

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): mixed
    {
        // Process the LLM response
        // Access token usage: $response->usage
        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;
    }
}

🤝 Building Agent Teams

Why have one agent when you can have a whole team? 🎉 Agents can delegate tasks to specialized sub-agents, creating powerful AI workflows. Think of it as building your own AI company!

class ManagerAgent extends BaseLlmAgent
{
    protected function registerSubAgents(): array
    {
        return [
            'technical_support' => TechnicalSupportAgent::class,
            'billing_support' => BillingSupportAgent::class,
            'sales_specialist' => SalesAgent::class,
        ];
    }

    // The agent will automatically have access to a 'delegate_to_sub_agent' tool
    // and instructions about available sub-agents
}

🚀 Advanced Agent Techniques

Ready to level up? Here are some pro tips and advanced features that'll make your agents work harder and smarter! 💪

⚙️ Background Processing with Async

Got heavy lifting to do? Send your agents to work in the background:

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

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

🖼️ Vision & Multimodal Magic

Your agents aren't just text wizards – they have eyes too! 👀 Send images, documents, and watch the magic happen:

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

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

🎛️ Fine-Tune on the Fly

Need more creativity? Want faster responses? Override any parameter at runtime:

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

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

🧠 Memory That Actually Remembers

Unlike that friend who forgets your birthday every year, your agents have perfect memory! They remember everything important about your conversations and context.

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

💎 Pro Tips from the Trenches

Want to build agents that users actually love? Here's the wisdom we've gathered from building hundreds of agents: