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

Tool	Spatie Package	Description
`QueryActivityLogTool`	`spatie/laravel-activitylog`	Query and filter activity log entries
`QueryPermissionsTool`	`spatie/laravel-permission`	Query roles, permissions, and user access
`QueryMediaLibraryTool`	`spatie/laravel-medialibrary`	Query and filter media files
`QueryTagsTool`	`spatie/laravel-tags`	Query tags, tag types, and tagged models
`QueryTranslatableTool`	`spatie/laravel-translatable`	Query model translations across locales
`QuerySettingsTool`	`spatie/laravel-settings`	Query application settings groups and values

Quick Start

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.

hristijans / spatie-agent-tools

Maintainers

Package info

Statistics

Security