README

Laravel AI Agent Kit is a Laravel package for building AI-powered application workflows on top of the official Laravel AI SDK. It gives your app package-owned blueprints, agents, provider profiles, tools, memory, queues, vector retrieval, and redacted telemetry without exposing provider SDK details as your public workflow API.

Use it when you want Laravel-native AI workflows that are explicit, testable, and safe by default.

Installation

Install the package with Composer:

composer require creativecrafts/laravel-ai-agent-kit

Publish the Laravel AI SDK configuration and migrations:

php artisan vendor:publish --provider="Laravel\\Ai\\AiServiceProvider"

Publish this package's configuration and migrations:

php artisan vendor:publish --tag="ai-agent-kit-config"
php artisan vendor:publish --tag="ai-agent-kit-migrations"
php artisan migrate

Optionally publish views:

php artisan vendor:publish --tag="ai-agent-kit-views"

Minimal configuration

After publishing config/ai-agent-kit.php, configure at least one enabled provider profile. The default local/test setup can use the bundled null provider profile. Production apps should configure real Laravel AI provider credentials through Laravel AI and map package provider profiles to the capabilities your workflows need.

At minimum, make sure:

• providers contains at least one enabled provider profile with the capabilities your workflows need. The bundled null profile has empty capabilities and is not sufficient for blueprint evaluation on its own — merge a preset from examples/provider-profile-presets.php or configure real profiles (see Providers).
• default_provider references an enabled provider profile.
• failover_order includes the default provider profile.
• memory.default_driver is intentional. The default in_memory driver is process-local and non-persistent.
• tool execution remains default-deny until you register and authorize tools deliberately.

See Configuration and Providers for the full setup path.

Quick start: evaluate text

Prefer dependency injection in controllers, jobs, commands, and application services:

use CreativeCrafts\LaravelAiAgentKit\Blueprints\TextToStructuredEvaluation;
use CreativeCrafts\LaravelAiAgentKit\Blueprints\TextToStructuredEvaluationRequest;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

final class EvaluateSupportReplyController
{
    public function __invoke(Request $request, TextToStructuredEvaluation $evaluation): JsonResponse
    {
        $result = $evaluation->evaluate(
            new TextToStructuredEvaluationRequest(
                subject: 'support reply',
                text: $request->string('text')->toString(),
                enabledDimensions: ['clarity', 'accuracy', 'completeness'],
                promptVersion: '1.0.0',
            ),
        );

        return response()->json($result->toArray());
    }
}

For route-level experiments or concise examples, the AgentKit facade exposes the same application-facing workflow shortcuts:

use CreativeCrafts\LaravelAiAgentKit\Blueprints\TextToStructuredEvaluationRequest;
use CreativeCrafts\LaravelAiAgentKit\Facades\AgentKit;

$result = AgentKit::evaluateText(
    new TextToStructuredEvaluationRequest(
        subject: 'support reply',
        text: 'We can refund the unused portion of your subscription within five business days.',
        enabledDimensions: ['clarity', 'accuracy', 'completeness'],
        promptVersion: '1.0.0',
    ),
);

Quick start: evaluate audio

Use the audio blueprint when the workflow should transcribe audio and evaluate the transcript through one package-owned result shape:

use CreativeCrafts\LaravelAiAgentKit\Blueprints\AudioToTextToEvaluationRequest;
use CreativeCrafts\LaravelAiAgentKit\Facades\AgentKit;

$result = AgentKit::evaluateAudio(
    new AudioToTextToEvaluationRequest(
        subject: 'support call',
        audioReference: 's3://bucket/audio/support-call.wav',
        audioMimeType: 'audio/wav',
        enabledDimensions: ['clarity', 'accuracy'],
        transcriptionPromptVersion: '1.0.0',
        evaluationPromptVersion: '1.0.0',
    ),
);

See Blueprints for request fields, result fields, prompt requirements, and structured-output behavior.

Quick start: evaluate audio with image

Use the audio-image blueprint when structured evaluation needs both a transcript and an image attachment:

use CreativeCrafts\LaravelAiAgentKit\Blueprints\AudioImageStructuredEvaluationRequest;
use CreativeCrafts\LaravelAiAgentKit\Blueprints\EvaluationImageInput;
use CreativeCrafts\LaravelAiAgentKit\Core\Modality\TranscriptionAudioSource;
use CreativeCrafts\LaravelAiAgentKit\Facades\AgentKit;

$result = AgentKit::evaluateAudioImage(
    new AudioImageStructuredEvaluationRequest(
        runId: 'eval-001',
        audio: TranscriptionAudioSource::fromBase64(base64_encode($audioBytes), 'audio/wav'),
        image: EvaluationImageInput::fromUrl('https://example.com/screenshot.png'),
        evaluationPrompt: 'Evaluate the transcript against the image.',
        schema: YourEvaluationSchema::class,
    ),
);

See Blueprints for capability requirements and pipeline composition.

Quick start: register and orchestrate agents

Register first-class agents explicitly through the package registry:

use App\Agents\CancellationAgent;
use App\Agents\CustomerSupportAgent;
use CreativeCrafts\LaravelAiAgentKit\Contracts\Agents\AgentRegistry;
use Illuminate\Support\ServiceProvider;

final class AppServiceProvider extends ServiceProvider
{
    public function boot(AgentRegistry $agents): void
    {
        $agents->registerMany([
            CustomerSupportAgent::class,
            CancellationAgent::class,
        ]);
    }
}

Then start an orchestrated workflow:

use CreativeCrafts\LaravelAiAgentKit\Core\Orchestration\OrchestrationRequest;
use CreativeCrafts\LaravelAiAgentKit\Facades\AgentKit;

$result = AgentKit::orchestrate(
    new OrchestrationRequest(
        entryAgent: 'support.agent',
        task: 'Handle a support refund workflow',
        input: ['subscription_id' => 'sub-123'],
    ),
);

See Agents and orchestration for agent definitions, delegation, handoffs, provider-profile assignment, and trace semantics.

Core concepts

Security and privacy defaults

• Tool execution is default-deny unless tools are explicitly registered and authorized.
• Telemetry is redacted by default and emits metadata-oriented package events.
• Conversation persistence is explicit: use in_memory for local/test use, database for encrypted durable storage, or redis for shared ephemeral memory.
• Provider SDK details stay behind package-owned contracts and DTOs.
• Queued workflows, vector stores, and persistent memory require production-specific configuration.

Documentation

Start with Getting started, then move to the focused guide for the subsystem you need. Maintainer and contributor process documents live behind CONTRIBUTING.md.

License

The MIT License (MIT). Please see LICENSE.md for more information.