TRIGGER when working with ai-sdk, Laravel's official first-party AI SDK. Activate when building or editing AI agents, chatbots, text generation, image generation, audio/TTS, transcription/STT, embeddings, RAG, vector stores, reranking, structured output, streaming, conversation memory, tools, MCP servers, queueing, broadcasting, and provider failover across OpenAI, Anthropic, Gemini, Azure, Groq, xAI, DeepSeek, Mistral, Ollama, ElevenLabs, Cohere, Jina, and VoyageAI. Invoke when the user references ai-sdk, the `Laravel\Ai\` namespace, or this project's AI features — not for other AI packages used directly.
TRIGGER when working with ai-sdk, Laravel's official first-party AI SDK. Activate when building or editing AI agents, chatbots, text generation, image generation, audio/TTS, transcription/STT, embeddings, RAG, vector stores, reranking, structured output, streaming, conversation memory, tools, MCP servers, queueing, broadcasting, and provider failover across OpenAI, Anthropic, Gemini, Azure, Groq, xAI, DeepSeek, Mistral, Ollama, ElevenLabs, Cohere, Jina, and VoyageAI. Invoke when the user references ai-sdk, the `Laravel\Ai\` namespace, or this project's AI features — not for other AI packages used directly.
license
MIT
metadata
{"author":"laravel"}
Developing with the Laravel AI SDK
The Laravel AI SDK (laravel/ai) is the official AI package for Laravel, providing a unified API for agents, images, audio, transcription, embeddings, reranking, vector stores, and file management across multiple AI providers.
Searching the Documentation
This package is new. Always search the documentation before implementing any feature. Never guess at APIs — the documentation is the single source of truth.
Use broad, simple queries that match the documentation section headings below.
Do not add package names to queries — package information is shared automatically. Use test agent fake, not laravel ai test agent fake.
Run multiple queries at once — the most relevant results are returned first.
Documentation Sections
Use these section headings as query terms for accurate results:
Introduction, Installation, Configuration, Provider Support
useLaravel\Ai\Image;
$image = Image::of('A sunset over mountains')
->landscape()
->quality('high')
->generate();
$path = $image->store(); // Store to default disk
useLaravel\Ai\Embeddings;
useIlluminate\Support\Str;
$response = Embeddings::for(['Text one', 'Text two'])
->dimensions(1536)
->cache()
->generate();
// Single string via Stringable$embedding = Str::of('Napa Valley has great wine.')->toEmbeddings();
Reranking
useLaravel\Ai\Reranking;
$response = Reranking::of(['Django is Python.', 'Laravel is PHP.', 'React is JS.'])
->limit(5)
->rerank('PHP frameworks');
$response->first()->document; // "Laravel is PHP."
Files and Vector Stores
useLaravel\Ai\Files\Document;
useLaravel\Ai\Stores;
// Store a file with the provider$file = Document::fromPath('/path/to/doc.pdf')->put();
// Create a vector store and add files$store = Stores::create('Knowledge Base');
$store->add($file->id);
$store->add(Document::fromStorage('manual.pdf')); // Store + add in one step
The #[UseCheapestModel] and #[UseSmartestModel] attributes are also available for automatic model selection.
Use #[RepairToolCalls] to let an agent recover when a model calls an unknown local tool. The failed call is returned to the model with the available local tool names, and the implicit step budget includes one repair step. Explicit #[MaxSteps] limits remain unchanged.
The #[WithoutBroadcasting] attribute stops the given stream event types from broadcasting (e.g. data-heavy ToolResult payloads that exceed the WebSocket frame limit). The events are still streamed and persisted; they just never hit the channel:
Register the server once, then return its tools from tools(). The SDK automatically wraps each Laravel\Mcp\Client\Primitives\Tool and presents it to the model as mcp_tools_<name>. Return your own Laravel\Mcp\Server\Tool instances in the same way and they retain their names and run in-process.
useLaravel\Mcp\Client;
useLaravel\Mcp\Facades\Mcp;
// In a service provider or routes/ai.phpMcp::registerClient('linear', fn () => Client::web('https://mcp.linear.app/mcp')
->withToken(config('services.linear.token')));
classSupportAgentimplementsAgent, HasTools{
usePromptable;
publicfunctiontools(): iterable{
returnMcp::client('linear')->tools();
}
}
The client connects on its first call, so call connect() only when you need to control the timing. Use Client::local('npx', ['-y', 'some-server']) for servers that run over stdio.
Point the SDK at any OpenAI-compatible endpoint (LM Studio, vLLM, Together, etc.) with the config-driven openai-compatible driver. Define named instances in config/ai.php, no code required:
It uses OpenAI-standard shapes and supports text, streaming, tools, structured output, image attachments, text embeddings, and audio transcription. Embedding dimensions are optional; omit them to use the model's native dimensions. For extra request-body fields, implement HasProviderOptions — the returned array is merged into the body.
Transcription uploads standard multipart (file + model + optional language) and defaults to response_format: json. Because endpoints vary, provider options override the defaults — pass response_format: 'verbose_json' for segments, or use diarize() on servers that implement diarized_json:
The namespace is Laravel\Ai, not Illuminate\Ai or Laravel\AI.
// CorrectuseLaravel\Ai\Image;
useLaravel\Ai\Contracts\Agent;
useLaravel\Ai\Promptable;
// Wrong — these do not existuseIlluminate\Ai\Image;
useLaravel\AI\Agent;
Unsupported Provider Capability
Calling a capability not supported by a provider throws a LogicException. Refer to the provider support table below.
