> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instructorphp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent ctrl events

## Overview

AgentCtrl provides a comprehensive event system for monitoring agent execution. Use the
built-in `AgentCtrlConsoleLogger` for formatted output, or attach custom listeners for
targeted monitoring. Events fire in real-time during execution.

Key concepts:

* `AgentCtrlConsoleLogger`: Built-in wiretap that formats events for console output
* `wiretap()`: Observe ALL events with a single callback
* `onEvent()`: Listen to specific event types (started, completed, text received, etc.)
* Event types: `AgentExecutionStarted`, `AgentTextReceived`, `AgentToolUsed`, `AgentExecutionCompleted`, `AgentErrorOccurred`

## Example

```php theme={null}
<?php
require 'examples/boot.php';

use Cognesy\AgentCtrl\AgentCtrl;
use Cognesy\AgentCtrl\Broadcasting\AgentCtrlConsoleLogger;
use Cognesy\AgentCtrl\Enum\AgentType;
use Cognesy\AgentCtrl\Event\AgentExecutionCompleted;
use Cognesy\AgentCtrl\Event\AgentToolUsed;

// 1. Built-in console logger: formatted, color-coded output
$logger = new AgentCtrlConsoleLogger(
    useColors: true,
    showTimestamps: true,
    showToolArgs: true,   // Show tool input args
    showSandbox: false,   // Hide sandbox setup events
    showPipeline: false,  // Hide request/response pipeline
    showStreaming: false,  // Hide stream events
);

$agent = AgentCtrl::make(AgentType::OpenCode)
    ->wiretap($logger->wiretap());

// 2. Targeted listeners: subscribe to specific event types
$agent->onEvent(AgentToolUsed::class, function (AgentToolUsed $event) {
    echo "\n  >>> Tool used: {$event->tool}\n\n";
});

$agent->onEvent(AgentExecutionCompleted::class, function (AgentExecutionCompleted $event) {
    echo "\n=== Execution Complete ===\n";
    echo "  Tools: {$event->toolCallCount}\n";
    if ($event->cost !== null) {
        echo "  Cost: $" . number_format($event->cost, 4) . "\n";
    }
    $tokens = ($event->inputTokens ?? 0) + ($event->outputTokens ?? 0);
    if ($tokens > 0) {
        echo "  Tokens: {$tokens}\n";
    }
});

// Run the agent
echo "=== Agent Execution Log ===\n\n";
$response = $agent->executeStreaming('List files in current directory and explain what you see.');

echo "\n=== Result ===\n";
if ($response->isSuccess()) {
    echo "Answer: " . $response->text() . "\n";
} else {
    echo "Error: Command failed with exit code {$response->exitCode}\n";
    exit(1);
}
?>
```

## Expected Output

```
=== Agent Execution Log ===

14:32:15.123 [opencode] [EXEC] Execution started [prompt=List files in current directory...]
14:32:15.234 [opencode] [PROC] Process started [commands=1]
14:32:15.456 [opencode] [TEXT] Text received [length=48]
14:32:16.234 [opencode] [TOOL] bash {command=ls -la}

  >>> Tool used: bash

14:32:16.567 [opencode] [TEXT] Text received [length=156]
14:32:17.890 [opencode] [DONE] Execution completed [exit=0, tools=1, cost=$0.0034, tokens=198]

=== Execution Complete ===
  Tools: 1
  Cost: $0.0034
  Tokens: 198

=== Result ===
Answer: The directory contains several PHP project files including composer.json for
dependencies, a src/ directory with source code, and configuration files.
```

## Key Points

* **Console logger**: `AgentCtrlConsoleLogger` provides clean, color-coded event output with configurable toggles
* **Wiretap pattern**: Observe all events with `wiretap()` for comprehensive logging
* **Targeted listening**: Use `onEvent()` for specific event types when you only care about certain events
* **Composable**: Combine the console logger with targeted listeners
* **Real-time monitoring**: Events fire as execution progresses, not after completion
* **Rich metadata**: Events include timestamps, model info, token usage, costs, and tool details
* **Use cases**: Logging, telemetry, progress bars, debugging, analytics