Laravel AI SDK
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Map existing AI usage (custom HTTP clients, OpenAI PHP, etc.) to migrate
- fuse-ai-pilot:research-expert - Verify provider model IDs and pricing on the official Laravel AI SDK docs
- mcp__context7__query-docs - Pull latest
laravel.com/docs/13.x/ai-sdk examples
After implementation, run fuse-ai-pilot:sniper for validation.
Overview
| Feature |
Description |
| Unified API |
Same code surface for 14+ providers via Lab enum |
| Agents |
Class-based with Agent contract + Promptable trait |
| Tool calling |
First-party FileSearch + custom tools per agent |
| Embeddings |
Embeddings::for([...])->generate() + Str::toEmbeddings() |
| Streaming |
Native SSE + Vercel AI SDK protocol compatibility |
| Structured output |
agent(schema: fn ($s) => ...) with JsonSchema |
Critical Rules
- Use the
Lab enum - Never hard-code provider strings; use Lab::Anthropic, Lab::OpenAI, etc.
- Configure keys in
.env - One env var per provider (OPENAI_API_KEY, ANTHROPIC_API_KEY, ...) read by config/ai.php
- Agents are classes - Always implement
Laravel\Ai\Contracts\Agent and use Promptable trait
- Declare tools explicitly - Override
tools(): iterable to expose tool calls; never assume implicit registration
- Stream via routes - Return
$agent->stream(...) directly from a route; do not buffer in memory
Architecture
app/
├── Ai/
│ ├── Agents/
│ │ └── SalesCoach.php # implements Agent, uses Promptable
│ ├── Tools/
│ │ └── SearchProducts.php # custom tool class
│ └── Services/
│ └── EmbeddingService.php # Embeddings::for() wrapper
config/
└── ai.php # providers, default models
.env # *_API_KEY entries
→ See Agent.php.md for a full agent
Reference Guide
| Topic |
Reference |
When to Consult |
| Installation |
installation.md |
Setting up laravel/ai and providers |
| Agents |
agents.md |
Building agent classes with attributes |
| Tools |
tools.md |
Tool calling, FileSearch, custom tools |
| Embeddings |
embeddings.md |
Generating vectors for semantic search |
| Streaming |
streaming.md |
SSE + Vercel AI SDK protocol |
| Structured output |
structured-output.md |
agent() helper + JSON Schema |
Templates
| Template |
When to Use |
| Agent.php.md |
Net new agent class |
| Tool.php.md |
Custom tool implementation |
| EmbeddingService.php.md |
Batch embedding generation |
| StreamingController.php.md |
SSE streaming endpoint |
Quick Reference
Generate text
use App\Ai\Agents\SalesCoach;
$response = (new SalesCoach)->prompt('Summarize this call');
Generate embeddings
use Illuminate\Support\Str;
$embedding = Str::of('Napa Valley wine')->toEmbeddings();
Stream
Route::get('/coach', fn () => (new SalesCoach)->stream('Analyze this'));
→ See Agent.php.md for complete example
Best Practices
DO
- Use class-level attributes (
#[Provider], #[Model], #[MaxSteps]) to lock agent configuration
- Cache embeddings in the DB - regenerating is expensive
- Set explicit
#[Timeout] to avoid runaway long generations
- Use
usingVercelDataProtocol() for Next.js / SvelteKit frontends
DON'T
- Don't declare an AI Agent without
#[Tool] declarations if it needs to call functions - tools must be registered explicitly
- Don't store API keys in
config/ai.php directly; use env() so values aren't committed
- Don't use
Lab::OpenAI strings - use the enum for type safety
- Don't loop manually over
Embeddings::for() items; pass the full array - the SDK batches efficiently
1---2name: laravel-ai-sdk3description: Use when integrating AI agents, tool calling, embeddings, structured output, or streaming in Laravel 13 via the `laravel/ai` package.4versions:5 laravel: "13.0"6 php: "8.3"7 laravel/ai: "^1.0"8user-invocable: true9references: references/installation.md, references/agents.md, references/tools.md, references/embeddings.md, references/streaming.md, references/structured-output.md, references/templates/Agent.php.md, references/templates/Tool.php.md, references/templates/EmbeddingService.php.md, references/templates/StreamingController.php.md10related-skills: laravel-attributes, laravel-vector-search11metadata:12 source: https://skillmd.com/skills/fusengine/laravel-ai-sdk13---1415<objective>16Covers the `laravel/ai` package for Laravel 13: building class-based Agents17(Agent contract + Promptable trait), tool calling (FileSearch + custom tools),18generating and storing embeddings, structured output via JSON Schema, and19streaming (SSE + Vercel AI SDK protocol). Supports 14+ providers through the20unified `Lab` enum — OpenAI, Anthropic, Gemini, Azure, Groq, DeepSeek, Ollama,21Mistral, xAI, Cohere, ElevenLabs, Jina, VoyageAI, OpenRouter.22</objective>2324# Laravel AI SDK2526## Agent Workflow (MANDATORY)2728Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:29301. **fuse-ai-pilot:explore-codebase** - Map existing AI usage (custom HTTP clients, OpenAI PHP, etc.) to migrate312. **fuse-ai-pilot:research-expert** - Verify provider model IDs and pricing on the official Laravel AI SDK docs323. **mcp__context7__query-docs** - Pull latest `laravel.com/docs/13.x/ai-sdk` examples3334After implementation, run **fuse-ai-pilot:sniper** for validation.3536---3738## Overview3940| Feature | Description |41|---------|-------------|42| **Unified API** | Same code surface for 14+ providers via `Lab` enum |43| **Agents** | Class-based with `Agent` contract + `Promptable` trait |44| **Tool calling** | First-party `FileSearch` + custom tools per agent |45| **Embeddings** | `Embeddings::for([...])->generate()` + `Str::toEmbeddings()` |46| **Streaming** | Native SSE + Vercel AI SDK protocol compatibility |47| **Structured output** | `agent(schema: fn ($s) => ...)` with `JsonSchema` |4849---5051## Critical Rules52531. **Use the `Lab` enum** - Never hard-code provider strings; use `Lab::Anthropic`, `Lab::OpenAI`, etc.542. **Configure keys in `.env`** - One env var per provider (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, ...) read by `config/ai.php`553. **Agents are classes** - Always implement `Laravel\Ai\Contracts\Agent` and use `Promptable` trait564. **Declare tools explicitly** - Override `tools(): iterable` to expose tool calls; never assume implicit registration575. **Stream via routes** - Return `$agent->stream(...)` directly from a route; do not buffer in memory5859---6061## Architecture6263```64app/65├── Ai/66│ ├── Agents/67│ │ └── SalesCoach.php # implements Agent, uses Promptable68│ ├── Tools/69│ │ └── SearchProducts.php # custom tool class70│ └── Services/71│ └── EmbeddingService.php # Embeddings::for() wrapper72config/73└── ai.php # providers, default models74.env # *_API_KEY entries75```7677→ See [Agent.php.md](references/templates/Agent.php.md) for a full agent7879---8081## Reference Guide8283| Topic | Reference | When to Consult |84|-------|-----------|-----------------|85| **Installation** | [installation.md](references/installation.md) | Setting up `laravel/ai` and providers |86| **Agents** | [agents.md](references/agents.md) | Building agent classes with attributes |87| **Tools** | [tools.md](references/tools.md) | Tool calling, `FileSearch`, custom tools |88| **Embeddings** | [embeddings.md](references/embeddings.md) | Generating vectors for semantic search |89| **Streaming** | [streaming.md](references/streaming.md) | SSE + Vercel AI SDK protocol |90| **Structured output** | [structured-output.md](references/structured-output.md) | `agent()` helper + JSON Schema |9192### Templates9394| Template | When to Use |95|----------|-------------|96| [Agent.php.md](references/templates/Agent.php.md) | Net new agent class |97| [Tool.php.md](references/templates/Tool.php.md) | Custom tool implementation |98| [EmbeddingService.php.md](references/templates/EmbeddingService.php.md) | Batch embedding generation |99| [StreamingController.php.md](references/templates/StreamingController.php.md) | SSE streaming endpoint |100101---102103## Quick Reference104105### Generate text106107```php108use App\Ai\Agents\SalesCoach;109110$response = (new SalesCoach)->prompt('Summarize this call');111```112113### Generate embeddings114115```php116use Illuminate\Support\Str;117118$embedding = Str::of('Napa Valley wine')->toEmbeddings();119```120121### Stream122123```php124Route::get('/coach', fn () => (new SalesCoach)->stream('Analyze this'));125```126127→ See [Agent.php.md](references/templates/Agent.php.md) for complete example128129---130131## Best Practices132133### DO134- Use class-level attributes (`#[Provider]`, `#[Model]`, `#[MaxSteps]`) to lock agent configuration135- Cache embeddings in the DB - regenerating is expensive136- Set explicit `#[Timeout]` to avoid runaway long generations137- Use `usingVercelDataProtocol()` for Next.js / SvelteKit frontends138139### DON'T140- Don't declare an AI Agent without `#[Tool]` declarations if it needs to call functions - tools must be registered explicitly141- Don't store API keys in `config/ai.php` directly; use `env()` so values aren't committed142- Don't use `Lab::OpenAI` strings - use the enum for type safety143- Don't loop manually over `Embeddings::for()` items; pass the full array - the SDK batches efficiently