Laravel AI SDK

Comprehensive guide for building AI-powered features with the Laravel AI SDK (laravel/ai). Contains 17 rules across 7 categories covering agents, tools, media generation, embeddings, vector stores, and testing.

When to Apply

Reference these guidelines when:

Creating AI agents with instructions, tools, and structured output
Prompting agents with conversation context
Streaming or queueing agent responses
Generating images, audio, or transcriptions
Creating and querying vector embeddings
Building RAG (retrieval-augmented generation) features
Testing AI features with fakes and assertions

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Agents	CRITICAL	`agent-`
2	Tools	HIGH	`tool-`
3	Embeddings & Search	HIGH	`embed-`
4	Media Generation	MEDIUM	`media-`
5	Files & Storage	MEDIUM	`files-`
6	Infrastructure	MEDIUM	`infra-`
7	Testing	HIGH	`test-`

Quick Reference

1. Agents (CRITICAL)

agent-create-configure - Create agents with artisan, PHP attribute configuration
agent-prompting - Prompt agents, conversation context, RemembersConversations
agent-structured-output - Structured output with JSON schema
agent-streaming-async - Streaming, broadcasting, and queueing responses
agent-middleware - Agent middleware pipeline
agent-anonymous - Anonymous agents for quick interactions

2. Tools (HIGH)

tool-create - Create custom tools with schema and handle method
tool-provider - Provider tools: WebSearch, WebFetch, FileSearch, SimilaritySearch

3. Embeddings & Search (HIGH)

embed-generate-cache - Generate, store, and cache vector embeddings
embed-rerank - Rerank documents and collections by relevance

4. Media Generation (MEDIUM)

media-images - Generate, store, and queue images
media-audio-transcription - Text-to-speech and speech-to-text

5. Files & Storage (MEDIUM)

files-vector-stores - File storage and vector stores for RAG

6. Infrastructure (MEDIUM)

infra-failover - Automatic provider failover for resilience

7. Testing (HIGH)

test-agents - Fake agents, assert prompts, prevent stray prompts
test-media - Fake images, audio, and transcriptions
test-data - Fake embeddings, reranking, files, and vector stores

Essential Patterns

Creating an Agent

<?php

namespace App\Ai\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Promptable;

class SalesCoach implements Agent
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a sales coach, analyzing transcripts and providing feedback.';
    }
}

Prompting

use App\Ai\Agents\SalesCoach;

$response = SalesCoach::make()->prompt('Analyze this sales transcript...');

return (string) $response;

Generating Images

use Laravel\Ai\Image;

$image = Image::of('A donut sitting on the kitchen counter')
    ->landscape()
    ->generate();

$path = $image->store();

Generating Embeddings

use Illuminate\Support\Str;

$embeddings = Str::of('Napa Valley has great wine.')->toEmbeddings();

Testing

use App\Ai\Agents\SalesCoach;

SalesCoach::fake(['First response', 'Second response']);

SalesCoach::make()->prompt('Analyze this...');

SalesCoach::assertPrompted('Analyze this...');

How to Use

Read individual rule files for detailed explanations and code examples.

Each rule file contains:

YAML frontmatter with metadata (title, impact, tags)
Brief explanation of why it matters
Bad Example with explanation
Good Example with explanation
Laravel 13 and PHP 8.3 specific context and references

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

laravel-ai-sdk