fusengine/laravel-ai-sdk

Laravel AI SDK

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

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

| 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

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

| 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