Wer heute KI-Features in ein Laravel-Projekt integriert, steht schnell vor einem bekannten Dilemma: Du bindest dich an einen Provider, die API ändert sich, ein günstigeres Modell erscheint – und plötzlich steckst du in einem Refactoring-Marathon. Genau dieses Problem löst das offizielle Laravel AI SDK. Wir nutzen es bei redbeed.com bereits produktiv, und der Wechsel zwischen Modellen ist seitdem kein Thema mehr.
Das Problem: KI-Integration ist fragil und kostspielig
In vielen Laravel-Projekten sieht die KI-Integration so aus: Direkte HTTP-Calls an die OpenAI-API, hartcodierte Modellnamen wie gpt-4o im Service-Layer, und Response-Handling, das exakt auf ein Provider-Format zugeschnitten ist. Das funktioniert – bis es nicht mehr funktioniert.
Die typischen Schmerzpunkte:
- Vendor Lock-in: Dein gesamter Code ist an einen Provider gekoppelt. Ein Wechsel bedeutet Refactoring in dutzenden Dateien.
- Kostenexplosion: Du nutzt ein teures Modell für Tasks, die ein günstigeres genauso gut erledigen würde.
- Modell-Karussell: Neue Modelle erscheinen im Wochentakt. Jedes Update erfordert manuelle Anpassungen.
- Fehlende Abstraktion: Ohne einheitliche Schnittstelle schreibst du für jeden Provider eigene Adapter.
Laravel AI SDK – Abstraktion statt Vendor Lock-in
Das Laravel AI SDK löst genau das. Es bietet eine einheitliche API-Schnittstelle für verschiedene KI-Provider: OpenAI, Anthropic (Claude) und Google Gemini. Die Idee ist simpel aber wirkungsvoll – du programmierst gegen eine Abstraktion, nicht gegen eine konkrete Provider-API.
Das SDK ist seit Laravel 13 offiziell verfügbar und bringt ein Agent-Konzept mit, das die Arbeit mit LLMs strukturiert und wartbar macht. Statt lose API-Calls durch deinen Code zu streuen, kapselst du KI-Logik in Agents – dedizierte Klassen mit klarer Verantwortung.
Provider wechseln in Sekunden – Ein praktisches Beispiel
Das Herzstück ist die Ai-Facade. Ein einfacher Text-Request sieht so aus:
use Laravel\Ai\Facades\Ai;
$response = Ai::text('Fasse diesen Artikel in drei Sätzen zusammen: ' . $article->body);
echo $response->text;
Der Clou: Welches Modell dahinter arbeitet, bestimmst du in der Konfiguration – nicht im Code. In deiner config/ai.php legst du den Default-Provider fest:
'default' => env('AI_PROVIDER', 'openai'),
'providers' => [
'openai' => [
'api_key' => env('OPENAI_API_KEY'),
],
'anthropic' => [
'api_key' => env('ANTHROPIC_API_KEY'),
],
'google' => [
'api_key' => env('GOOGLE_API_KEY'),
],
],
Von GPT zu Claude wechseln? Eine Zeile in der .env:
AI_PROVIDER=anthropic
Kein Refactoring. Keine Breaking Changes. Dein gesamter Code funktioniert weiter.
PHP Attributes: Intelligente Agent-Verwaltung mit #[UseSmartestModel] und #[UseCheapestModel]
Richtig spannend wird es mit Agents. Du erstellst einen Agent per Artisan-Command:
php artisan make:agent SummaryAgent
Das generiert eine Agent-Klasse, die du mit PHP Attributes dekorieren kannst (#[UseSmartestModel]):
use Laravel\Ai\Agents\Agent;
use Laravel\Ai\Attributes\UseSmartestModel;
#[UseSmartestModel]
class ResearchAgent extends Agent
{
public function instructions(): string
{
return 'Du bist ein Recherche-Assistent. Analysiere Quellen gründlich und liefere fundierte Zusammenfassungen.';
}
}
Und für einfachere Tasks, bei denen du Kosten sparen willst (#[UseCheapestModel]):
use Laravel\Ai\Agents\Agent;
use Laravel\Ai\Attributes\UseCheapestModel;
#[UseCheapestModel]
class TaggingAgent extends Agent
{
public function instructions(): string
{
return 'Vergib passende Tags für den gegebenen Content. Maximal 5 Tags.';
}
}
Das Geniale daran: Du musst keine konkreten Modellnamen kennen oder pflegen. #[UseSmartestModel] wählt automatisch das leistungsfähigste verfügbare Modell deines konfigurierten Providers. #[UseCheapestModel] nimmt das günstigste. Erscheint ein neues Modell, aktualisiert Laravel die Zuordnung – dein Code bleibt unverändert.
Den Agent rufst du dann einfach so auf:
$response = ResearchAgent::respond('Analysiere die aktuellen Trends im PHP-Ökosystem.');
echo $response->text;
Praktische Use-Cases bei redbeed.com
Wir setzen das Laravel AI SDK bei redbeed.com bereits für mehrere Workflows ein:
- Blog-Überarbeitung: Ein Agent mit
#[UseSmartestModel]prüft Entwürfe auf Struktur, Tonalität und Vollständigkeit. Das Ergebnis ist ein konkreter Verbesserungsvorschlag, kein generischer Text. - Quellenrecherche: Ein Research-Agent durchsucht und bewertet Quellen zu einem Thema, bevor wir Content erstellen. Das spart Stunden manueller Recherche.
- Content-Refinement: Bestehende Seiten werden durch einen Agent mit
#[UseCheapestModel]auf SEO-Schwächen und Lesbarkeit geprüft – kostengünstig und im Batch.
Der entscheidende Vorteil: Wir können jederzeit den Provider wechseln, wenn ein Modell bessere Ergebnisse liefert oder günstiger wird. Letzte Woche haben wir für den Research-Agent von OpenAI auf Claude gewechselt – eine Zeile Config, null Code-Änderungen.
Kosten optimieren durch intelligente Modellauswahl
Die Attribute sind nicht nur syntaktischer Zucker. Sie sind eine echte Kostenstrategie. Die Logik dahinter:
- Komplexe Aufgaben (Analyse, Recherche, Code-Review):
#[UseSmartestModel]– hier zählt Qualität. - Einfache Aufgaben (Tagging, Zusammenfassungen, Formatierung):
#[UseCheapestModel]– hier zählt Effizienz.
In der Praxis kann das die KI-Kosten erheblich senken. Ein Tagging-Task, der mit GPT-4o ein paar Cent kostet, erledigt ein günstigeres Modell für einen Bruchteil – bei vergleichbarem Ergebnis.
Setup und erste Schritte mit Laravel AI SDK
Die Installation ist straightforward:
composer require laravel/ai
php artisan install:ai
Das install:ai-Command erstellt die Konfigurationsdatei und richtet alles ein. Danach trägst du deine API-Keys in die .env ein:
AI_PROVIDER=openai
OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...
GOOGLE_API_KEY=...
Erstelle deinen ersten Agent:
php artisan make:agent MyFirstAgent
Und du kannst direkt loslegen. Das SDK kümmert sich um Retry-Logik, Timeouts und das Mapping der Provider-Responses auf ein einheitliches Format.
Häufige Fallstricke und Best Practices
Nach einigen Wochen produktivem Einsatz hier unsere wichtigsten Learnings:
- Agents nach Aufgabe trennen: Ein Agent pro Verantwortung. Kein Gott-Agent, der alles kann. Das macht die Attribute-Zuordnung sinnvoll und die Kosten transparent.
- Fehlerbehandlung nicht vergessen: API-Calls können fehlschlagen. Nutze Try-Catch-Blöcke und plane Fallbacks ein. Das SDK wirft spezifische Exceptions, die du gezielt abfangen kannst.
- Responses cachen: Identische Anfragen müssen nicht doppelt an die API gehen. Laravels Cache-System eignet sich perfekt dafür.
- Prompts versionieren: Behandle deine Agent-Instructions wie Code. Änderungen an Prompts können die Output-Qualität drastisch beeinflussen.
- Kosten monitoren: Auch mit
#[UseCheapestModel]summieren sich API-Calls. Logge Token-Verbrauch und setze Budgetgrenzen.
try {
$response = SummaryAgent::respond($content);
Cache::put('summary_' . md5($content), $response->text, now()->addHours(24));
} catch (\Laravel\Ai\Exceptions\AiException $e) {
Log::error('AI Agent failed: ' . $e->getMessage());
// Fallback-Logik
}
Das Laravel AI SDK ist kein Spielzeug für Demos – es ist eine solide Abstraktion, die KI-Integration in Laravel-Projekten wartbar und kosteneffizient macht. Die Kombination aus einheitlicher API, Agent-Konzept und PHP Attributes nimmt dir genau die Arbeit ab, die bisher bei jedem Provider-Wechsel angefallen ist. Probier es aus – der Einstieg dauert keine fünf Minuten.