Laravel AI SDK Documentation

The Laravel AI SDK provides a unified, expressive API for interacting with various AI providers (such as OpenAI, Anthropic, and Gemini) through a consistent, Laravel-friendly interface. It enables developers to implement several AI-driven capabilities within their applications, including:

• Intelligent Agents: Building agents equipped with tools and capable of producing structured output.
• Image Generation: Creating images via AI models.
• Audio Processing: Synthesizing (Text-to-Speech) and transcribing (Speech-to-Text) audio.
• Vector Embeddings: Creating embeddings for semantic search and RAG (Retrieval-Augmented Generation) workflows.

The primary way to interact with the Laravel AI SDK is through Agents. To create a custom agent, implement the Laravel\Ai\Contracts\Agent interface and use the Laravel\Ai\Promptable trait. This allows you to define custom instructions and use the prompt() method to generate responses.

You can also use the agent() global helper to create Anonymous Agents for quick, one-off tasks without defining a class.

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.';
    }
}

// Usage
$response = (new SalesCoach)->prompt('Analyze this transcript...');

// Anonymous Agent
use function Laravel\Ai\agent;
$response = agent(instructions: 'You are a helpful assistant.')->prompt('Hello');

In version 0.9, Agent::fake() responses now run through the real TextGenerationLoop. This makes faked responses more realistic but may affect tests that assert on exact message counts or streamed events:

• Tool Calls: Faking a tool call for an unregistered tool now throws NoSuchToolException instead of being silently skipped.
• Message Count: After a faked tool call, $response->messages includes one extra message (the final assistant reply).
• Streaming Events: Faking an empty string no longer emits TextStart/TextEnd events. Faked tool calls now emit a ToolCall event during streaming.

The human-in-the-loop tool approval flow now records pause and resolution details in a new nullable TEXT column named approval_state on the conversation messages table.

If you have already published and run the conversation migrations, you must manually add this column via a new migration.

return new class extends Migration
{
    public function up(): void
    {
        Schema::table(config('ai.conversations.tables.messages', 'agent_conversation_messages'), function (Blueprint $table) {
            $table->text('approval_state')->nullable()->after('meta');
        });
    }

    public function down(): void
    {
        Schema::table(config('ai.conversations.tables.messages', 'agent_conversation_messages'), function (Blueprint $table) {
            $table->dropColumn('approval_state');
        });
    }
};

In version 0.9, the providerOptions() method was removed from embeddings and transcription builders. Use withProviderOptions() instead.

Additionally, the signature for withProviderOptions() on provider tools changed. The $provider string argument was removed in favor of an array or a closure that allows varying options per provider.

// Embeddings/Transcription builders
Ai::embeddings('...')->withProviderOptions(['dimensions' => 256]);

// Provider tools (using a closure to vary options per provider)
$tool->withProviderOptions(fn (Lab|string $provider) => match ($provider) {
    Lab::OpenAi => ['key' => 'value'],
    default => [],
});

As of version 0.9, Anthropic structured outputs use the native output_config.format API by default. If your application relies on the previous synthetic tool-based approach, you can disable native structured outputs in your provider configuration.

Set use_native_structured_output to false in the anthropic config block.

'anthropic' => [
    'use_native_structured_output' => false,
],

When importing classes from the Laravel AI SDK, ensure you use the correct namespace. The SDK uses Laravel\Ai, not Illuminate\Ai or Laravel\AI (case-sensitive). Using the wrong namespace will result in class not found errors.

// Correct
use Laravel\Ai\Image;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Promptable;

// Wrong — these do not exist
use Illuminate\Ai\Image;
use Laravel\AI\Agent;

For advanced retrieval and document management:

• Reranking: Use Laravel\Ai\Reranking::of($documents) to re-order a list of documents based on a query string via ->rerank($query). This returns a collection where you can access the top results via ->first()->document.
• Files: Use Laravel\Ai\Files\Document::fromPath($path)->put() to upload and store a file with an AI provider.
• Vector Stores: Use Laravel\Ai\Stores::create($name) to initialize a store. You can add files to a store using $store->add($fileId) or by passing a Document object directly via $store->add(Document::fromStorage('manual.pdf')).

// Reranking
$response = Reranking::of(['Doc 1', 'Doc 2'])->limit(5)->rerank('PHP frameworks');

// Files and Stores
$file = Document::fromPath('/path/to/doc.pdf')->put();
$store = Stores::create('Knowledge Base');
$store->add($file->id);

In version 0.10, Agent methods such as prompt(), stream(), queue(), broadcast(), broadcastNow(), and broadcastOnQueue() now accept Decisions|string.

A Decisions instance is used to resume a paused run by providing a map of approval decisions keyed by tool call ID.

If you implement Laravel\Ai\Contracts\Agent directly, you must update your $prompt parameter type hints to Decisions|string.

use Laravel\\Ai\\Approvals\Decision;
use Laravel\\Ai\\Approvals\Decisions;

$agent->prompt(Decisions::from([
    'call_abc' => true,
    'call_def' => Decision::reject('Not permitted.'),
]));