🌟 The Journey of an Agent Request

When you ask an agent to do something, it goes through a carefully orchestrated lifecycle that ensures reliability, traceability, and extensibility. Let's follow a request from start to finish!

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

🚀 Step 1: Starting the Journey

Everything begins with a simple, fluent API call. Here's how you kick things off:

// The journey begins!
$response = CustomerSupportAgent::ask('Where is my order?')
    ->forUser($user)
    ->withSession('session-123')
    ->withContext(['order_id' => 123])
    ->temperature(0.7)
    ->execute();

// Or for async processing
DataProcessingAgent::process($bigDataset)
    ->async()
    ->onQueue('heavy-lifting')
    ->execute();

🎭 Step 2: The Lifecycle Hooks

Your agent has six powerful hooks to customize behavior at key moments. These are your backstage passes to the agent's thinking process!

public function beforeLlmCall(array $inputMessages, AgentContext $context): array
{
    // Add system context, filter sensitive data, start tracing
    return $inputMessages;
}

public function afterLlmResponse(Response|Generator $response, AgentContext $context): mixed
{
    // Log token usage: $response->usage
    // Extract and store memories
    return $response;
}

public function beforeToolCall(string $toolName, array $arguments, AgentContext $context): array
{
    // Validate permissions, add API keys, log tool usage
    return $arguments;
}

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

// Before delegation
public function beforeSubAgentDelegation(string $subAgentName, string $taskInput, ...): array

// After delegation
public function afterSubAgentDelegation(string $subAgentName, string $result, ...): string

📡 Step 3: Events Along the Way

As your agent works, it broadcasts seven key events that you can listen to for monitoring, logging, or triggering other actions!

👂 Listening to Events

// In your EventServiceProvider
protected $listen = [
    AgentExecutionStarting::class => [
        LogAgentActivity::class,
        CheckRateLimits::class,
    ],
    ToolCallInitiating::class => [
        ValidateToolPermissions::class,
        LogToolUsage::class,
    ],
];

// Example event listener
class LogAgentActivity
{
    public function handle(AgentExecutionStarting $event): void
    {
        Log::info('Agent starting', [
            'agent' => $event->agentClass,
            'mode' => $event->mode,
            'user' => $event->userId,
        ]);
    }
}

🧩 Step 4: Key Players in the Lifecycle

Several important components work together to make the agent lifecycle smooth and reliable:

⚡ Streaming: Real-time Responses

When you enable streaming, the lifecycle adapts to deliver responses token by token:

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

foreach ($stream as $chunk) {
    // Each chunk arrives as soon as it's generated
    echo $chunk;
    flush();
}

// Events are still dispatched during streaming!

💡 Pro Tips for Lifecycle Mastery