Laravel AI Sdk

Laravel AI SDK

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

1. fuse-ai-pilot:explore-codebase - Map existing AI usage (custom HTTP clients, OpenAI PHP, etc.) to migrate
2. fuse-ai-pilot:research-expert - Verify provider model IDs and pricing on the official Laravel AI SDK docs
3. mcp__context7__query-docs - Pull latest laravel.com/docs/13.x/ai-sdk examples

After implementation, run fuse-ai-pilot:sniper for validation.

Overview

Critical Rules

1. Use the Lab enum - Never hard-code provider strings; use Lab::Anthropic, Lab::OpenAI, etc.
2. Configure keys in .env - One env var per provider (OPENAI_API_KEY, ANTHROPIC_API_KEY, ...) read by config/ai.php
3. Agents are classes - Always implement Laravel\Ai\Contracts\Agent and use Promptable trait
4. Declare tools explicitly - Override tools(): iterable to expose tool calls; never assume implicit registration
5. 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

Templates

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