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
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)
    ->withModel('opencode/ling-3.0-flash-fin-free')
    ->withTimeout(60)
    ->wiretap($logger->wiretap());

$observedTools = [];
$completed = null;

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

$agent->onEvent(AgentExecutionCompleted::class, function (AgentExecutionCompleted $event) use (&$completed) {
    $completed = $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";
    assert($response->text() !== '');
    assert(str_contains(strtolower($response->text()), 'composer.json'));
    assert($observedTools !== [], 'Expected the directory inspection to emit a tool-use event');
    assert($completed instanceof AgentExecutionCompleted, 'Expected an execution-completed event');
    assert($completed->cost !== null, 'Expected the completion event to carry reported cost');
} 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