README

A Telescope-like monitoring dashboard for Laravel AI SDK interactions. Logs agent invocations, tool calls, token usage, costs, and latency — with a built-in web dashboard and support for MCP server/client tracing.

Features

• Automatic recording of every laravel/ai agent invocation (prompt text, response, token counts, cost, latency)
• Per-invocation tool call tracing for agent tools, MCP server tools, and MCP client tools
• Cost calculation for OpenAI, Anthropic, Gemini, Groq, DeepSeek, and Mistral models
• Built-in web dashboard (Blade + Alpine.js + Chart.js, no build step required)
• Tag invocations programmatically or declaratively with #[Tag]
• Flexible filtering: skip individual invocations or tool calls via events
• Two storage drivers: database (full-featured) and file (lightweight, local dev)
• Automatic daily pruning via the Laravel scheduler

Requirements

• PHP ^8.3
• Laravel ^12.0
• laravel/ai ^0.8.1

Installation

1. Install via Composer

composer require wcflabs/ai-ledger

2. Publish the configuration

php artisan vendor:publish --tag=ai-ledger-config

This creates config/ai-ledger.php.

3. Publish and register the authorization provider

php artisan vendor:publish --tag=ai-ledger-provider

This copies AiLedgerApplicationServiceProvider into app/Providers/. Register it in bootstrap/providers.php:

return [
    // ...
    App\Providers\AiLedgerApplicationServiceProvider::class,
];

4. Publish and run the migrations

php artisan vendor:publish --tag=ai-ledger-migrations
php artisan migrate

Dashboard

Once installed, the dashboard is available at /ai-ledger (configurable via dashboard.path in the config).

Authentication:

By default, the dashboard is accessible in the local environment only. For production access, open app/Providers/AiLedgerApplicationServiceProvider.php and add authorized email addresses to the viewAiLedger gate:

protected function gate(): void
{
    Gate::define('viewAiLedger', function ($user) {
        return in_array($user?->email, [
            'admin@example.com',
        ]);
    });
}

You can also provide a fully custom auth callback anywhere (e.g., in a service provider):

use WCFLabs\AiLedger\Facades\AiLedger;

AiLedger::auth(function ($request) {
    return $request->user()?->isAdmin();
});

Configuration

All options live in config/ai-ledger.php.

Storage Drivers

database (default)

Stores invocations and tool calls in two database tables (ai_ledger_invocations, ai_ledger_tool_calls). Supports full filtering, aggregation, and the metrics dashboard.

file

Writes one JSON file per invocation to storage/logs/ai-ledger/. Intended for local development only — it does not support filtering events, dashboard aggregation, or the metrics chart. No migrations required.

AI_LEDGER_DRIVER=file

Tagging Invocations

Tags appear in the dashboard and can be used to categorize invocations by feature, user type, or any other dimension.

Declarative — #[Tag] attribute

Apply the #[Tag] attribute to any Agent or Tool class:

use WCFLabs\AiLedger\Attributes\Tag;
use Laravel\Ai\Agent;

#[Tag('checkout', 'billing')]
class CheckoutAgent extends Agent
{
    // ...
}

Programmatic — AiLedger::tag()

Call AiLedger::tag() before the invocation runs. Tags are flushed and attached to the next recorded invocation:

use WCFLabs\AiLedger\Facades\AiLedger;

AiLedger::tag('user:premium', 'feature:recommendations');

$result = $agent->handle($input);

Suppressing Logging

Wrap any code block with AiLedger::withoutLogging() to prevent it from being recorded:

use WCFLabs\AiLedger\Facades\AiLedger;

$result = AiLedger::withoutLogging(function () use ($agent, $input) {
    return $agent->handle($input);
});

MCP Integration

Requires laravel/mcp to be installed.

MCP calls are logged automatically — no manual setup required.

• Inbound MCP server tool calls (external MCP clients calling your app): intercepted transparently by overriding laravel/mcp's CallTool handler in the container.
• MCP tools used inside Laravel AI agents (McpServerTool, McpTool): captured via the standard InvokingTool/ToolInvoked events with the correct tool_type (mcp_server or mcp_client).

Manual decorator (advanced)

If you call an MCP client directly outside of a Laravel AI agent context, you can opt in to logging via LoggingMcpClientDecorator:

use WCFLabs\AiLedger\Mcp\LoggingMcpClientDecorator;

$client = new LoggingMcpClientDecorator($mcpClient);

$result = $client->callTool('search', ['query' => 'example']);

All other methods on the underlying client are proxied transparently via __call.

Filtering

You can prevent individual invocations or tool calls from being stored by listening to the filtering events and returning false.

Skip an invocation

use WCFLabs\AiLedger\Events\FilteringInvocation;
use Illuminate\Support\Facades\Event;

Event::listen(FilteringInvocation::class, function (FilteringInvocation $event) {
    // Skip invocations triggered by internal health-check agents
    if (str_contains($event->data['agent_class'] ?? '', 'HealthCheck')) {
        return false;
    }
});

Skip a tool call

use WCFLabs\AiLedger\Events\FilteringToolCall;
use Illuminate\Support\Facades\Event;

Event::listen(FilteringToolCall::class, function (FilteringToolCall $event) {
    if ($event->data['tool_name'] === 'internal_ping') {
        return false;
    }
});

Returning false from the listener skips storage but still executes the agent or tool normally.

Artisan Commands

Pruning

When pruning.enabled is true, the package automatically schedules ai-ledger:prune to run daily via the Laravel scheduler (callAfterResolving). No manual scheduler entry is required.

To override the retention period at runtime:

php artisan ai-ledger:prune --days=7

License

MIT — see LICENSE.