# Laravel Ai Sdk

> Use when integrating AI agents, tool calling, embeddings, structured output, or streaming in Laravel 13 via the `laravel/ai` package. Covers 14+ providers (OpenAI, Anthropic, Gemini, Azure, Groq, DeepSeek, Ollama, Mistral, xAI, Cohere, ElevenLabs, Jina, VoyageAI, OpenRouter).

- **Type:** Skill
- **Install:** `agentstack add skill-fusengine-agents-laravel-ai-sdk`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [fusengine](https://agentstack.voostack.com/s/fusengine)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [fusengine](https://github.com/fusengine)
- **Source:** https://github.com/fusengine/agents/tree/main/plugins/laravel-expert/skills/laravel-ai-sdk

## Install

```sh
agentstack add skill-fusengine-agents-laravel-ai-sdk
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](references/templates/Agent.php.md) for a full agent

---

## Reference Guide

| Topic | Reference | When to Consult |
|-------|-----------|-----------------|
| **Installation** | [installation.md](references/installation.md) | Setting up `laravel/ai` and providers |
| **Agents** | [agents.md](references/agents.md) | Building agent classes with attributes |
| **Tools** | [tools.md](references/tools.md) | Tool calling, `FileSearch`, custom tools |
| **Embeddings** | [embeddings.md](references/embeddings.md) | Generating vectors for semantic search |
| **Streaming** | [streaming.md](references/streaming.md) | SSE + Vercel AI SDK protocol |
| **Structured output** | [structured-output.md](references/structured-output.md) | `agent()` helper + JSON Schema |

### Templates

| Template | When to Use |
|----------|-------------|
| [Agent.php.md](references/templates/Agent.php.md) | Net new agent class |
| [Tool.php.md](references/templates/Tool.php.md) | Custom tool implementation |
| [EmbeddingService.php.md](references/templates/EmbeddingService.php.md) | Batch embedding generation |
| [StreamingController.php.md](references/templates/StreamingController.php.md) | SSE streaming endpoint |

---

## Quick Reference

### Generate text

```php
use App\Ai\Agents\SalesCoach;

$response = (new SalesCoach)->prompt('Summarize this call');
```

### Generate embeddings

```php
use Illuminate\Support\Str;

$embedding = Str::of('Napa Valley wine')->toEmbeddings();
```

### Stream

```php
Route::get('/coach', fn () => (new SalesCoach)->stream('Analyze this'));
```

→ See [Agent.php.md](references/templates/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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [fusengine](https://github.com/fusengine)
- **Source:** [fusengine/agents](https://github.com/fusengine/agents)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-fusengine-agents-laravel-ai-sdk
- Seller: https://agentstack.voostack.com/s/fusengine
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.