README

Laravel AI SDK agent tools for Spatie packages. Drop-in tools that give your AI agents the ability to query and interact with data managed by popular Spatie packages — no glue code required.

Requirements

• PHP 8.2+
• Laravel 12+
• Laravel AI SDK (laravel/ai)

Each tool requires its corresponding Spatie package to be installed. See the individual tool documentation for specific package requirements.

Installation

composer require hristijans/spatie-agent-tools

The package auto-discovers its service provider — no manual registration needed.

Available Tools

Quick Start

Register the tools you need on your Laravel AI SDK agent:

use Hristijans\SpatieAgentTools\Tools\QueryActivityLogTool;
use Hristijans\SpatieAgentTools\Tools\QueryMediaLibraryTool;
use Hristijans\SpatieAgentTools\Tools\QueryPermissionsTool;
use Hristijans\SpatieAgentTools\Tools\QuerySettingsTool;
use Hristijans\SpatieAgentTools\Tools\QueryTagsTool;
use Hristijans\SpatieAgentTools\Tools\QueryTranslatableTool;
use Laravel\Ai\Agents\Agent;
use Laravel\Ai\Contracts\HasTools;

class MyAgent implements Agent, HasTools
{
    public function tools(): iterable
    {
        return [
            new QueryActivityLogTool,
            new QueryPermissionsTool,
            new QueryMediaLibraryTool,
            new QueryTagsTool,
            new QueryTranslatableTool,
            new QuerySettingsTool,
        ];
    }
}

Your agent can now query activity logs, roles and permissions, media files, tags, translations, and application settings through natural language — no extra configuration required.

Tip: You only need to register the tools for packages you have installed. If you only use spatie/laravel-permission, just register QueryPermissionsTool.

Documentation

Comprehensive documentation for each tool is available in the docs/ directory:

• Activity Log Tool — Query and filter activity log entries by causer, subject, log name, description, and date range.
• Laravel Permission Tool — List roles and permissions, look up what a role can do, find which roles hold a permission, and audit a user's full access breakdown.
• Media Library Tool — Query media files by model, collection, mime type, disk, file name, size, and upload date.
• Tags Tool — List and search tags, discover tag types, find tags on a model, and look up which models use a specific tag.
• Translatable Tool — Get translations for a model, check which locales exist, find missing translations, and discover models with a specific locale.
• Settings Tool — List registered settings groups, read current values, inspect individual properties, and check locked status.

License

The MIT License (MIT). Please see License File for more information.