Laravel AI SDK: KI-Modelle austauschen ohne Breaking Changes – mit PHP Attributes.

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.