Laravel AI SDK - Knowledge of Laravel

Einführung

Das Laravel AI SDK bietet eine einheitliche, ausdrucksstarke API für die Interaktion mit KI-Anbietern wie OpenAI, Anthropic und Gemini. Mit dem AI SDK realisieren Sie unter einer einheitlichen, Laravel-typischen Schnittstelle vielfältige KI-Funktionen: den Aufbau intelligenter Agenten mit Tools und strukturierter Ausgabe, Bildgenerierung, Sprachsynthese und Transkription sowie die Erzeugung von Vektor-Embeddings.

Das Laravel AI SDK ist ein in Laravel 13 hinzugefügtes offizielles Paket. Es wird als laravel/ai bereitgestellt und ermöglicht die Nutzung mehrerer KI-Anbieter über eine einheitliche API.

Übersicht der unterstützten Anbieter

Funktion	Unterstützte Anbieter
Textgenerierung	OpenAI, OpenAI Compatible, Anthropic, Gemini, Azure, Bedrock, Groq, xAI, DeepSeek, Mistral, Ollama, OpenRouter
Bildgenerierung	OpenAI, Gemini, xAI, Azure, Bedrock, OpenRouter
Sprachsynthese (TTS)	OpenAI, ElevenLabs, Gemini
Spracherkennung (STT)	OpenAI, ElevenLabs, Mistral, Gemini
Embeddings	OpenAI, Gemini, Azure, Bedrock, Cohere, Mistral, Jina, VoyageAI, Ollama, OpenRouter
Reranking	Cohere, Jina, VoyageAI
Dateien	OpenAI, Anthropic, Gemini, Azure

Installation

Paket installieren

Installieren Sie das Laravel AI SDK über Composer.

composer require laravel/ai

Konfigurationsdatei und Migrationen veröffentlichen

Veröffentlichen Sie die Konfigurationsdatei und die Migrationen mit dem Artisan-Befehl vendor:publish.

php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"

Migrationen ausführen

Führen Sie die Datenbank-Migrationen aus. Dabei werden die Tabellen agent_conversations und agent_conversation_messages erstellt, die zum Speichern des Konversationsverlaufs dienen.

php artisan migrate

Konfiguration

Umgebungsvariablen

Tragen Sie die API-Schlüssel der KI-Anbieter, die Sie verwenden möchten, in Ihre .env-Datei ein.

ANTHROPIC_API_KEY=
AZURE_OPENAI_API_KEY=
COHERE_API_KEY=
DEEPSEEK_API_KEY=
ELEVENLABS_API_KEY=
GEMINI_API_KEY=
GROQ_API_KEY=
MISTRAL_API_KEY=
OLLAMA_API_KEY=
OPENAI_API_KEY=
OPENROUTER_API_KEY=
JINA_API_KEY=
VOYAGEAI_API_KEY=
XAI_API_KEY=

Die Standardmodelle für Text, Bild, Audio, Transkription und Embeddings können Sie in config/ai.php einstellen.

Benutzerdefinierte Basis-URL

Wenn Sie einen Proxy-Dienst verwenden, können Sie pro Anbieter eine eigene URL festlegen.

'providers' => [
    'openai' => [
        'driver' => 'openai',
        'key' => env('OPENAI_API_KEY'),
        'url' => env('OPENAI_URL'),
    ],
    'anthropic' => [
        'driver' => 'anthropic',
        'key' => env('ANTHROPIC_API_KEY'),
        'url' => env('ANTHROPIC_BASE_URL'),
    ],
],

Benutzerdefinierte Basis-URLs stehen für OpenAI, Anthropic, Gemini, Groq, Cohere, DeepSeek, xAI und OpenRouter zur Verfügung.

OpenAI-kompatible Anbieter

Wenn Sie eine OpenAI-kompatible API verwenden — beispielsweise LM Studio, vLLM, Together, Fireworks oder ein lokales Gateway —, können Sie den Anbieter mit dem Treiber openai-compatible konfigurieren. url ist erforderlich; ein angegebener key wird als Bearer-Token gesendet.

'providers' => [
    'local' => [
        'driver' => 'openai-compatible',
        'url' => env('LOCAL_AI_URL'),
        'key' => env('LOCAL_AI_API_KEY'),
    ],
],

Nach der Einrichtung können Sie den Anbieter genau wie andere Anbieter über seinen Namen ansprechen.

agent()->prompt('What is Laravel?', provider: 'local', model: 'local-model');

Wenn Sie ein Standard-Textmodell konfigurieren, müssen Sie das Modell nicht jedes Mal angeben.

'local' => [
    'driver' => 'openai-compatible',
    'url' => env('LOCAL_AI_URL'),
    'key' => env('LOCAL_AI_API_KEY'),
    'models' => [
        'text' => [
            'default' => env('LOCAL_AI_MODEL'),
        ],
    ],
],

OpenAI-kompatible Anbieter unterstützen Textgenerierung, Streaming, Tools, strukturierte Ausgabe und angehängte Bilder. Wenn Ihr Endpunkt zusätzliche Felder im Request-Body benötigt, nutzen Sie Provider-Optionen.

Lab-Enum

Um Anbieter im Code zu referenzieren, verwenden Sie das Lab-Enum.

use Laravel\Ai\Enums\Lab;

Lab::Anthropic;
Lab::OpenAI;
Lab::Gemini;

Agenten

Agenten sind der grundlegende Baustein des Laravel AI SDK. Mit dem Befehl make:agent erzeugen Sie eine Agentenklasse.

php artisan make:agent SalesCoach

# Agent mit strukturierter Ausgabe erzeugen
php artisan make:agent SalesCoach --structured

Die generierten Agenten werden im Verzeichnis app/Ai/Agents/ abgelegt. Das folgende Beispiel zeigt einen Agenten, der alle wichtigen Interfaces implementiert.

<?php

namespace App\Ai\Agents;

use App\Ai\Tools\RetrievePreviousTranscripts;
use App\Models\History;
use App\Models\User;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\Conversational;
use Laravel\Ai\Contracts\HasStructuredOutput;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Messages\Message;
use Laravel\Ai\Promptable;
use Stringable;

class SalesCoach implements Agent, Conversational, HasTools, HasStructuredOutput
{
    use Promptable;

    public function __construct(public User $user) {}

    public function instructions(): Stringable|string
    {
        return 'You are a sales coach, analyzing transcripts and providing feedback and an overall sales strength score.';
    }

    public function messages(): iterable
    {
        return History::where('user_id', $this->user->id)
            ->latest()
            ->limit(50)
            ->get()
            ->reverse()
            ->map(function ($message) {
                return new Message($message->role, $message->content);
            })->all();
    }

    public function tools(): iterable
    {
        return [new RetrievePreviousTranscripts];
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'feedback' => $schema->string()->required(),
            'score' => $schema->integer()->min(1)->max(10)->required(),
        ];
    }
}

Prompt

Mit der Methode prompt() senden Sie eine Nachricht an den Agenten.

$response = (new SalesCoach)->prompt('Analyze this sales transcript...');
return (string) $response;

Mit der statischen Methode make() können Sie Abhängigkeiten über den Container auflösen und eine Instanz erzeugen.

$agent = SalesCoach::make(user: $user);

Anbieter, Modell und Timeout lassen sich per Argument von prompt() überschreiben.

$response = (new SalesCoach)->prompt(
    'Analyze this sales transcript...',
    provider: Lab::Anthropic,
    model: 'claude-haiku-4-5-20251001',
    timeout: 120,
);

Konversationskontext

Indem Sie das Interface Conversational implementieren und die Methode messages() definieren, geben Sie den bisherigen Konversationsverlauf an die KI weiter. Mit dem Trait RemembersConversations speichern und laden Sie den Konversationsverlauf automatisch in der Datenbank.

use Laravel\Ai\Concerns\RemembersConversations;

class SalesCoach implements Agent, Conversational
{
    use Promptable, RemembersConversations;

    public function instructions(): string
    {
        return 'You are a sales coach...';
    }
}

Mit forUser() beginnen Sie eine Konversation. Über die zurückgegebene conversationId können Sie mit continue() an derselben Konversation weiterarbeiten.

$response = (new SalesCoach)->forUser($user)->prompt('Hello!');
$conversationId = $response->conversationId;

$response = (new SalesCoach)->continue($conversationId, as: $user)->prompt('Tell me more about that.');

Strukturierte Ausgabe

Implementieren Sie das Interface HasStructuredOutput und definieren Sie in schema() ein JSON-Schema, um die Antwort der KI als strukturierte Daten zu erhalten.

public function schema(JsonSchema $schema): array
{
    return ['score' => $schema->integer()->required()];
}

$response = (new SalesCoach)->prompt('Analyze this...');
return $response['score'];

Verschachtelte Objekte

public function schema(JsonSchema $schema): array
{
    return [
        'score' => $schema->integer()->required(),
        'metadata' => $schema->object(fn ($schema) => [
            'confidence' => $schema->string()->enum(['low', 'medium', 'high'])->required(),
            'language' => $schema->string()->required(),
        ])->required(),
    ];
}

Array von Objekten

public function schema(JsonSchema $schema): array
{
    return [
        'feedback' => $schema->array()->items(
            $schema->object(fn ($schema) => [
                'comment' => $schema->string()->required(),
                'score' => $schema->integer()->required(),
            ])
        )->required(),
    ];
}

anyOf (Auswahl aus mehreren Schemata)

Wenn ein Wert einem von mehreren Schemata entsprechen kann, verwenden Sie die Methode anyOf.

public function schema(JsonSchema $schema): array
{
    return [
        'content' => $schema->anyOf([
            $schema->object(fn ($schema) => [
                'type' => $schema->string()->enum(['article'])->required(),
                'title' => $schema->string()->required(),
            ]),
            $schema->object(fn ($schema) => [
                'type' => $schema->string()->enum(['image'])->required(),
                'url' => $schema->string()->required(),
            ]),
        ])->required(),
    ];
}

Anhänge

Mit dem Argument attachments übergeben Sie dem Agenten Dokumente oder Bilder.

use Laravel\Ai\Files;

$response = (new SalesCoach)->prompt(
    'Analyze the attached sales transcript...',
    attachments: [
        Files\Document::fromStorage('transcript.pdf'),
        Files\Document::fromPath('/home/laravel/transcript.md'),
        $request->file('transcript'),
    ]
);

Bildanhänge funktionieren analog.

$response = (new ImageAnalyzer)->prompt('What is in this image?', attachments: [
    Files\Image::fromStorage('photo.jpg'),
    Files\Image::fromPath('/home/laravel/photo.jpg'),
    $request->file('photo'),
]);

Streaming

Mit der Methode stream() senden Sie die Antwort in Chunks zurück — ideal, um lange Antworten in Echtzeit an das Frontend zu übertragen.

Route::get('/coach', function () {
    return (new SalesCoach)->stream('Analyze this sales transcript...');
});

Mit dem Callback then() beschreiben Sie die Verarbeitung nach Abschluss des Streamings.

use Laravel\Ai\Responses\StreamedAgentResponse;

Route::get('/coach', function () {
    return (new SalesCoach)
        ->stream('Analyze this sales transcript...')
        ->then(function (StreamedAgentResponse $response) {
            // $response->text, $response->events, $response->usage...
        });
});

Sie können den Stream auch manuell iterieren.

$stream = (new SalesCoach)->stream('Analyze this sales transcript...');

foreach ($stream as $event) {
    // ...
}

Vercel-AI-SDK-Protokoll

Wenn Sie im Frontend das Vercel AI SDK verwenden, rufen Sie usingVercelDataProtocol() auf.

Route::get('/coach', function () {
    return (new SalesCoach)->stream('Analyze...')->usingVercelDataProtocol();
});

Broadcasting

Die Events eines Streams können Sie an Broadcast-Kanäle wie Laravel Echo senden.

use Illuminate\Broadcasting\Channel;

$stream = (new SalesCoach)->stream('Analyze this sales transcript...');

foreach ($stream as $event) {
    $event->broadcast(new Channel('channel-name'));
}

Mit broadcastOnQueue() können Sie das Broadcasting über eine Queue durchführen.

(new SalesCoach)->broadcastOnQueue(
    'Analyze this sales transcript...',
    new Channel('channel-name'),
);

Große Events überspringen

Manche Broadcast-Plattformen beschränken WebSocket-Nachrichten auf etwa 10 KB. Stream-Events mit großen Datenmengen — etwa umfangreiche Tool-Ergebnisse — können diese Grenze überschreiten und beim Broadcasting scheitern. Mit dem Attribut WithoutBroadcasting schließen Sie bestimmte Event-Typen vom Broadcasting aus.

<?php

namespace App\Ai\Agents;

use Laravel\Ai\Attributes\WithoutBroadcasting;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;
use Laravel\Ai\Streaming\Events\ToolCall;
use Laravel\Ai\Streaming\Events\ToolResult;

#[WithoutBroadcasting(ToolCall::class, ToolResult::class)]
class SearchAgent implements Agent, HasTools
{
    use Promptable;

    // ...
}

Ausgeschlossene Events werden nicht broadcast, aber weiterhin in der Tabelle agent_conversation_messages gespeichert. Dadurch kann das Frontend nach Abschluss des Streams sämtliche Tool-Daten abrufen. Dies funktioniert sowohl über Queue (broadcastOnQueue) als auch synchron (broadcast / broadcastNow).

Queue

Mit der Methode queue() können Sie Prompts in einer Queue einreihen und asynchron verarbeiten.

use Laravel\Ai\Responses\AgentResponse;

Route::post('/coach', function (Request $request) {
    (new SalesCoach)
        ->queue($request->input('transcript'))
        ->then(function (AgentResponse $response) { /* ... */ })
        ->catch(function (Throwable $e) { /* ... */ });

    return back();
});

Tools

Mit Tools ermöglichen Sie es der KI, Funktionen in Ihrem Code aufzurufen. Mit dem Befehl make:tool erzeugen Sie eine Tool-Klasse.

php artisan make:tool RandomNumberGenerator

<?php

namespace App\Ai\Tools;

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;
use Stringable;

class RandomNumberGenerator implements Tool
{
    public function description(): Stringable|string
    {
        return 'This tool may be used to generate cryptographically secure random numbers.';
    }

    public function handle(Request $request): Stringable|string
    {
        return (string) random_int($request['min'], $request['max']);
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'min' => $schema->integer()->min(0)->required(),
            'max' => $schema->integer()->required(),
        ];
    }
}

Registrieren Sie Tools in der Methode tools() des Agenten.

public function tools(): iterable
{
    return [new RandomNumberGenerator];
}

Similarity-Search-Tool

Ein Ähnlichkeitssuche-Tool auf Basis von Vektor-Embeddings lässt sich einfach hinzufügen.

use App\Models\Document;
use Laravel\Ai\Tools\SimilaritySearch;

public function tools(): iterable
{
    return [
        SimilaritySearch::usingModel(Document::class, 'embedding'),
    ];
}

Sie können auch Optionen angeben.

SimilaritySearch::usingModel(
    model: Document::class,
    column: 'embedding',
    minSimilarity: 0.7,
    limit: 10,
    query: fn ($query) => $query->where('published', true),
),

Mit einer Closure lässt sich eine eigene Suchlogik definieren.

new SimilaritySearch(using: function (string $query) {
    return Document::query()
        ->where('user_id', $this->user->id)
        ->whereVectorSimilarTo('embedding', $query)
        ->limit(10)
        ->get();
}),

Mit withDescription() können Sie die Beschreibung des Tools anpassen.

SimilaritySearch::usingModel(Document::class, 'embedding')
    ->withDescription('Search the knowledge base for relevant articles.'),

File-Storage-Tools

Mit der Tool-Factory FileStorage geben Sie einem Agenten Zugriff auf eine Filesystem-Disk von Laravel. Die Methode all liefert einen kompletten Satz an Tools zum Auflisten, Lesen, URL-Generieren, Schreiben, Löschen und Kopieren von Dateien auf der angegebenen Disk.

use Laravel\Ai\Tools\FileStorage;

public function tools(): iterable
{
    return FileStorage::all('local');
}

Um nur lesenden Zugriff zu gewähren, verwenden Sie die Methode readOnly.

return FileStorage::readOnly('local');

Diese Methoden liefern eine Illuminate\Support\Collection zurück, sodass Sie die bereitgestellten Tools weiter einschränken können.

use Laravel\Ai\Tools\Filesystem\DeleteFile;

return FileStorage::all('s3')
    ->reject(fn ($tool) => $tool instanceof DeleteFile);

MCP-Tools

Wenn Sie in Ihrer Anwendung Laravel MCP verwenden, können Sie Tools an Ihren Agenten weitergeben, die von einem Model-Context-Protocol-Server angeboten werden. Über den Laravel MCP-Client verbinden Sie sich mit einem entfernten oder lokalen MCP-Server und übergeben dessen Tools direkt an Ihren Agenten.

Für die Nutzung von MCP-Tools muss das Paket Laravel MCP in Ihrer Anwendung installiert sein.

Die Methode tools des MCP-Clients liefert eine Collection. Verwenden Sie den Spread-Operator ..., um sie in das tools-Array Ihres Agenten zu integrieren.

use App\Ai\Tools\RandomNumberGenerator;
use Laravel\Mcp\Client;

/**
 * Get the tools available to the agent.
 *
 * @return Tool[]
 */
public function tools(): iterable
{
    return [
        ...Client::web('https://mcp.example.com')
            ->withToken($token)
            ->tools(),

        new RandomNumberGenerator,
    ];
}

Das AI SDK wrappt jedes MCP-Tool automatisch, sodass der Agent es wie jedes andere Tool aufrufen kann. Sie können auch benannte MCP-Clients verwenden.

use Laravel\Mcp\Facades\Mcp;

public function tools(): iterable
{
    return [
        ...Mcp::client('github')->tools(),
    ];
}

Oder eine Verbindung zu einem lokalen MCP-Server aufbauen.

use Laravel\Mcp\Client;

public function tools(): iterable
{
    return [
        ...Client::local('php', ['artisan', 'mcp:start'])->tools(),
    ];
}

Details zur Erstellung und Authentifizierung von MCP-Clients (Bearer-Token, OAuth usw.) finden Sie in der Dokumentation zum MCP-Client.

Anbieter-Tools

Dies sind spezielle Tools, die KI-Anbieter nativ implementieren.

Websuche

Fügt eine Websuche zu Ihrem Agenten hinzu. Unterstützt werden Anthropic, OpenAI, Gemini und OpenRouter.

use Laravel\Ai\Providers\Tools\WebSearch;

public function tools(): iterable
{
    return [new WebSearch];
}

Optional lassen sich die Anzahl der Treffer, Domains und der Standort einschränken.

(new WebSearch)->max(5)->allow(['laravel.com', 'php.net']),
(new WebSearch)->location(city: 'New York', region: 'NY', country: 'US');

Web-Fetch

Ein Tool, das den Inhalt einer angegebenen URL abruft. Unterstützt werden Anthropic und Gemini.

use Laravel\Ai\Providers\Tools\WebFetch;

public function tools(): iterable
{
    return [new WebFetch];
}

(new WebFetch)->max(3)->allow(['docs.laravel.com']),

Dateisuche

Ein Tool zum Suchen von Dokumenten in einem Vector Store. Unterstützt werden OpenAI und Gemini.

use Laravel\Ai\Providers\Tools\FileSearch;

public function tools(): iterable
{
    return [new FileSearch(stores: ['store_id'])];
}

// Mehrere Stores angeben
new FileSearch(stores: ['store_1', 'store_2']);

// Filter über Metadaten
new FileSearch(stores: ['store_id'], where: ['author' => 'Taylor Otwell', 'year' => 2026]);

Komplexere Filter lassen sich über eine FileSearchQuery angeben.

use Laravel\Ai\Providers\Tools\FileSearchQuery;

new FileSearch(stores: ['store_id'], where: fn (FileSearchQuery $query) =>
    $query->where('author', 'Taylor Otwell')
          ->whereNot('status', 'draft')
          ->whereIn('category', ['news', 'updates'])
);

Sub-Agenten

Ein Agent kann auch aus der tools()-Methode eines anderen Agenten zurückgegeben werden. Wenn Sie einen Agenten als Tool registrieren, kann der übergeordnete Agent bestimmte Aufgaben an den Sub-Agenten delegieren und dessen Ergebnis in die eigene Antwort einbeziehen. Das ist praktisch, wenn ein generalistischer Agent auf spezialisierte Agenten mit eigenen Anweisungen, Tools, Modelleinstellungen oder Anbieter-Konfigurationen zugreifen soll. Ein Kundensupport-Agent könnte etwa Fragen zur Rückerstattungsrichtlinie an einen spezialisierten Rückerstattungs-Agenten delegieren.

<?php

namespace App\Ai\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

class CustomerSupportAgent implements Agent, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You help customers with account, order, and billing questions. Delegate refund policy questions to the refunds specialist.';
    }

    public function tools(): iterable
    {
        return [
            new RefundsAgent,
        ];
    }
}

Um anzupassen, wie der Sub-Agent dem übergeordneten Agenten präsentiert wird, implementieren Sie im Sub-Agenten das Interface CanActAsTool und definieren einen Namen und eine Beschreibung für das Tool.

<?php

namespace App\Ai\Agents;

use App\Ai\Tools\LookupOrder;
use Laravel\Ai\Attributes\Provider;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\CanActAsTool;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;

#[Provider(Lab::Anthropic)]
class RefundsAgent implements Agent, CanActAsTool, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a refunds specialist. Use order details and the refund policy to give concise eligibility guidance.';
    }

    public function name(): string
    {
        return 'refunds_specialist';
    }

    public function description(): string
    {
        return 'Determine whether an order is eligible for a refund and explain the next step.';
    }

    public function tools(): iterable
    {
        return [
            new LookupOrder,
        ];
    }
}

Für Sub-Agenten, die CanActAsTool nicht implementieren, verwendet Laravel den Klassennamen als Tool-Namen und erzeugt automatisch eine generische Beschreibung. Jeder Aufruf eines Sub-Agenten erfolgt unabhängig, ohne den Konversationsverlauf des übergeordneten Agenten zu übernehmen.

Middleware

Sie können Middleware zu einem Agenten hinzufügen, um Prompts und Antworten abzufangen.

php artisan make:agent-middleware LogPrompts

Implementieren Sie im Agenten das Interface HasMiddleware und registrieren Sie die Middleware in der Methode middleware().

<?php

namespace App\Ai\Agents;

use App\Ai\Middleware\LogPrompts;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasMiddleware;
use Laravel\Ai\Promptable;

class SalesCoach implements Agent, HasMiddleware
{
    use Promptable;

    public function middleware(): array
    {
        return [new LogPrompts];
    }
}

Beispiel für die Implementierung einer Middleware-Klasse:

<?php

namespace App\Ai\Middleware;

use Closure;
use Laravel\Ai\Prompts\AgentPrompt;

class LogPrompts
{
    public function handle(AgentPrompt $prompt, Closure $next)
    {
        Log::info('Prompting agent', ['prompt' => $prompt->prompt]);
        return $next($prompt);
    }
}

Mit then() können Sie auch nachgelagerte Verarbeitung nach der Antwort hinzufügen.

public function handle(AgentPrompt $prompt, Closure $next)
{
    return $next($prompt)->then(function (AgentResponse $response) {
        Log::info('Agent responded', ['text' => $response->text]);
    });
}

Anonyme Agenten

Ohne eine Klasse zu definieren, können Sie mit dem Helper agent() einen anonymen Agenten verwenden.

use function Laravel\Ai\{agent};

$response = agent(
    instructions: 'You are an expert at software development.',
    messages: [],
    tools: [],
)->prompt('Tell me about Laravel');

Auch anonyme Agenten mit strukturierter Ausgabe lassen sich erstellen.

use Illuminate\Contracts\JsonSchema\JsonSchema;

$response = agent(
    schema: fn (JsonSchema $schema) => ['number' => $schema->integer()->required()],
)->prompt('Generate a random number less than 100');

Agentenkonfiguration (PHP-Attribute)

Die Standardkonfiguration eines Agenten lässt sich mit PHP-Attributen deklarativ festlegen.

Attribut	Beschreibung
`#[Provider]`	Legt den zu verwendenden Anbieter fest
`#[Model]`	Legt das zu verwendende Modell fest
`#[MaxSteps]`	Maximale Anzahl der Schritte für Tool-Aufrufe
`#[MaxTokens]`	Maximale Anzahl an Token
`#[Temperature]`	Temperatur-Parameter (0.0–1.0)
`#[TopP]`	Wahrscheinlichkeit für Nucleus Sampling (0.0–1.0)
`#[Timeout]`	Timeout (in Sekunden)
`#[UseCheapestModel]`	Automatische Auswahl des günstigsten Modells
`#[UseSmartestModel]`	Automatische Auswahl des leistungsfähigsten Modells

<?php

namespace App\Ai\Agents;

use Laravel\Ai\Attributes\MaxSteps;
use Laravel\Ai\Attributes\MaxTokens;
use Laravel\Ai\Attributes\Model;
use Laravel\Ai\Attributes\Provider;
use Laravel\Ai\Attributes\Temperature;
use Laravel\Ai\Attributes\Timeout;
use Laravel\Ai\Attributes\TopP;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;

#[Provider(Lab::Anthropic)]
#[Model('claude-haiku-4-5-20251001')]
#[MaxSteps(10)]
#[MaxTokens(4096)]
#[Temperature(0.7)]
#[Timeout(120)]
#[TopP(0.9)]
class SalesCoach implements Agent
{
    use Promptable;
}

Es gibt auch Shortcut-Attribute für die Modellauswahl.

// Günstigstes Modell verwenden
#[UseCheapestModel]
class SimpleSummarizer implements Agent
{
    use Promptable;
}

// Leistungsfähigstes Modell verwenden
#[UseSmartestModel]
class ComplexReasoner implements Agent
{
    use Promptable;
}

Provider-Optionen

Indem Sie das Interface HasProviderOptions implementieren, können Sie anbieterspezifische Optionen übergeben.

<?php

namespace App\Ai\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasProviderOptions;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;

class SalesCoach implements Agent, HasProviderOptions
{
    use Promptable;

    public function providerOptions(Lab|string $provider): array
    {
        return match ($provider) {
            Lab::OpenAI => [
                'reasoning' => ['effort' => 'low'],
                'frequency_penalty' => 0.5,
                'presence_penalty' => 0.3,
            ],
            Lab::Anthropic => [
                'thinking' => ['budget_tokens' => 1024],
            ],
            default => [],
        };
    }
}

Freigabe durch den Menschen (Human Tool Approval)

Um die Tool-Freigabe zu nutzen, benötigen Sie einen Conversational-Agenten mit persistiertem Konversationsverlauf. Der Trait RemembersConversations liefert die notwendige Persistenz, um pausierte Aufrufe wieder aufzunehmen.

Für Tools, die sensible oder nicht rückgängig zu machende Aktionen ausführen — etwa das Löschen von Dateien oder Überweisungen — können Sie vor der Ausführung eine menschliche Freigabe verlangen. Um ein Tool freigabepflichtig zu machen, implementieren Sie den Contract Approvable und verwenden den Trait InteractsWithApprovals. Freigabepflichtige Tools benötigen standardmäßig eine Freigabe.

<?php

namespace App\Ai\Tools;

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Illuminate\Support\Facades\Storage;
use Laravel\Ai\Concerns\InteractsWithApprovals;
use Laravel\Ai\Contracts\Approvable;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;
use Stringable;

class DeleteFile implements Approvable, Tool
{
    use InteractsWithApprovals;

    /**
     * Beschreibung des Tools abrufen.
     */
    public function description(): Stringable|string
    {
        return 'Löscht eine Datei aus dem Speicher.';
    }

    /**
     * Tool ausführen.
     */
    public function handle(Request $request): Stringable|string
    {
        Storage::delete($request['path']);

        return "Gelöscht: [{$request['path']}]";
    }

    /**
     * Schemadefinition des Tools abrufen.
     */
    public function schema(JsonSchema $schema): array
    {
        return [
            'path' => $schema->string()->required(),
        ];
    }
}

Wenn Sie in Abhängigkeit von den Argumenten des Tool-Aufrufs entscheiden möchten, ob eine Freigabe nötig ist, definieren Sie die Methode needsApproval im Tool. Diese Methode kann einen Boolean oder eine Approval-Instanz mit einem Begründungsgrund zurückgeben.

use Laravel\Ai\Approvals\Approval;

/**
 * Entscheidet, ob das Tool für die gegebene Anfrage eine Freigabe benötigt.
 */
protected function needsApproval(Request $request): Approval|bool
{
    return str_starts_with($request['path'], 'temporary/')
        ? false
        : Approval::required('Diese Datei wird endgültig gelöscht.');
}

Sie können die Freigabeanforderung auch beim Rückgeben des Tools aus der tools-Methode des Agenten überschreiben.

public function tools(): iterable
{
    return [
        (new SendNotification)->withoutApproval(),
        (new DeleteFile)->requireApproval('Für die Löschung ist eine Bestätigung erforderlich.'),
    ];
}

Sobald ein freigabepflichtiges Tool aufgerufen wird, pausiert der Agent vor der Ausführung. Anhand von pendingApprovals der Antwort können Sie ID, Toolname, Argumente und Freigabegrund jedes Tool-Aufrufs prüfen.

$response = (new FileAssistant)
    ->forUser($user)
    ->prompt('Bitte lösche die alten Rechnungen.');

if ($response->hasPendingApprovals()) {
    foreach ($response->pendingApprovals as $approval) {
        // $approval->id
        // $approval->tool
        // $approval->arguments
        // $approval->reason
    }
}

Um den Agenten fortzusetzen, setzen Sie die Konversation fort und übergeben eine Decisions-Instanz, die eine Entscheidung für jeden ausstehenden Tool-Aufruf enthält. Mit einer Entscheidung lässt sich der Aufruf freigeben, ablehnen oder die Argumente vor der Ausführung bearbeiten.

use Laravel\Ai\Approvals\Decision;
use Laravel\Ai\Approvals\Decisions;

$response = (new FileAssistant)
    ->continue($conversationId, as: $user)
    ->prompt(Decisions::from([
        'call_abc' => Decision::approve(),
        'call_ghi' => Decision::reject('Diese Rechnung muss archiviert bleiben.'),
    ]));

Die Booleans true und false sind Kurzformen für Freigabe bzw. Ablehnung. Jeder ausstehende Tool-Aufruf muss eine Entscheidung erhalten. Wird eine unbekannte, fehlende oder bereits aufgelöste Tool-Aufruf-ID angegeben, wird eine ApprovalMismatchException geworfen. Mit den Methoden approveRemaining oder rejectRemaining können Sie eine Standardentscheidung für Aufrufe ohne explizite Entscheidung festlegen.

$decisions = Decisions::from([
    'call_abc' => true,
])->rejectRemaining('Nicht freigegeben.');

$response = (new FileAssistant)
    ->continue($conversationId, as: $user)
    ->prompt($decisions);

Wenn Sie mit einem Ergebnis ablehnen — etwa Decision::reject('Nicht freigegeben.') —, wird dieses an das Modell zurückgegeben und die Antwort wird fortgesetzt. Wird ohne Ergebnis abgelehnt, stoppt die Generierungsschleife an dem Punkt, an dem die Ablehnung protokolliert wurde. Die Tool-Freigabe wird von den Methoden prompt, stream, queue, broadcast, broadcastNow und broadcastOnQueue unterstützt. Während des Streamings und Broadcastings wird die Pause als tool_approval_request-Event dargestellt. Wenn Sie das Vercel-AI-SDK-Streaming-Protokoll verwenden, werden Freigabeanforderungen und -ergebnisse als native Tool-Approval-Parts des Protokolls emittiert. Bei in die Queue eingereihten Agenten wird die resultierende Antwort an den then-Callback übergeben; zusätzlich dispatcht Laravel das Event ToolApprovalRequested. Bevor Laravel das Modell zum Fortfahren auffordert, speichert es die Ergebnisse der freigegebenen Tool-Ausführung. Schlägt die Generierung anschließend fehl, sind die Freigaben bereits aufgelöst. Statt dieselben Entscheidungen erneut zu senden, setzen Sie die Konversation mit einem gewöhnlichen Text-Prompt fort.

Vollständiger Freigabe-Ablauf

Die folgenden Routen zeigen einen vollständigen Freigabe-Ablauf. Die GET-Route liefert die Chat-Ansicht, die POST-Route nimmt entweder eine neue Textnachricht aus der Chat-Ansicht oder eine Freigabeentscheidung entgegen. Dieses Beispiel setzt voraus, dass das User-Modell Ihrer Anwendung den Trait HasConversations verwendet.

use App\Ai\Agents\FileAssistant;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Gate;
use Illuminate\Support\Facades\Route;
use Illuminate\Validation\Rule;
use Laravel\Ai\Approvals\Decision;
use Laravel\Ai\Approvals\Decisions;
use Laravel\Ai\Models\Conversation;

Route::get('/chat/{conversation}', function (Request $request, Conversation $conversation) {
    Gate::authorize('view', $conversation);

    return view('chat', [
        'conversation' => $conversation,
    ]);
})->middleware('auth');

Route::post('/chat/{conversation}', function (Request $request, Conversation $conversation) {
    Gate::authorize('view', $conversation);

    $validated = $request->validate([
        'message' => ['nullable', 'string', 'required_without:decisions', 'prohibited_with:decisions'],
        'decisions' => ['nullable', 'array', 'required_without:message', 'prohibited_with:message'],
        'decisions.*.action' => ['required_with:decisions', Rule::in(['approve', 'reject'])],
        'decisions.*.result' => ['nullable', 'string'],
    ]);

    $prompt = isset($validated['decisions'])
        ? Decisions::from($validated->collect('decisions')->map(
            fn (array $decision) => match ($decision['action']) {
                'approve' => Decision::approve(),
                'reject' => Decision::reject($decision['result'] ?? null),
            }
        )->all())
        : $validated['message'];

    $response = (new FileAssistant)
        ->continue($conversation->id, as: $request->user())
        ->prompt($prompt);

    return [
        'conversation_id' => $response->conversationId,
        'status' => $response->hasPendingApprovals() ? 'awaiting_approval' : 'complete',
        'message' => $response->text,
        'approvals' => $response->pendingApprovals,
    ];
})->middleware('auth');

Wenn der Status der Antwort awaiting_approval lautet, muss die Chat-Ansicht die ausstehenden Freigaben anzeigen und die Wahl des Nutzers mit der Tool-Aufruf-ID als Schlüssel an denselben Endpunkt zurücksenden.

{
    "decisions": {
        "call_abc": {
            "action": "approve"
        },
        "call_def": {
            "action": "reject",
            "result": "Diese Rechnung muss archiviert bleiben."
        }
    }
}

Für gewöhnliche Chat-Nachrichten senden Sie stattdessen den message-Wert.

{
    "message": "Bitte lösche die alten Rechnungen."
}

Der Freigabe-Ablauf ist ein Mechanismus, der KI-Agenten mit weitreichenden Rechten ausstattet und dabei eine menschliche Kontrolle vor der Ausführung vorschaltet. Setzen Sie ihn aktiv bei Tools ein, die nicht rückgängig zu machende Aktionen ausführen — etwa Dateilöschungen, Zahlungsabwicklung oder Schreibzugriffe auf externe APIs.

Bildgenerierung

Mit der Klasse Image können Sie Bilder generieren. Unterstützt werden OpenAI, Gemini und xAI.

use Laravel\Ai\Image;

$image = Image::of('A donut sitting on the kitchen counter')->generate();
$rawContent = (string) $image;

Sie können Qualität, Seitenverhältnis und Timeout angeben.

$image = Image::of('A donut sitting on the kitchen counter')
    ->quality('high')
    ->landscape()
    ->timeout(120)
    ->generate();

Sie können auch ein Referenzbild anhängen und dieses bearbeiten lassen.

use Laravel\Ai\Files;

$image = Image::of('Update this photo to be in the style of an impressionist painting.')
    ->attachments([Files\Image::fromStorage('photo.jpg')])
    ->landscape()
    ->generate();

Bild speichern

$path = $image->store();
$path = $image->storeAs('image.jpg');
$path = $image->storePublicly();
$path = $image->storePubliclyAs('image.jpg');

Bildgenerierung per Queue

use Laravel\Ai\Responses\ImageResponse;

Image::of('A donut sitting on the kitchen counter')
    ->portrait()
    ->queue()
    ->then(function (ImageResponse $image) {
        $path = $image->store();
    });

Sprachsynthese (TTS)

Mit der Klasse Audio wandeln Sie Text in Sprache um. Unterstützt werden OpenAI und ElevenLabs.

use Laravel\Ai\Audio;

$audio = Audio::of('I love coding with Laravel.')->generate();
$rawContent = (string) $audio;

Sie können auch das Geschlecht der Stimme, eine konkrete Voice-ID oder Anweisungen zum Sprechstil angeben.

$audio = Audio::of('I love coding with Laravel.')->female()->generate();
$audio = Audio::of('I love coding with Laravel.')->voice('voice-id-or-name')->generate();
$audio = Audio::of('I love coding with Laravel.')->female()->instructions('Said like a pirate')->generate();

Audio speichern

$path = $audio->store();
$path = $audio->storeAs('audio.mp3');
$path = $audio->storePublicly();
$path = $audio->storePubliclyAs('audio.mp3');

Sprachsynthese per Queue

use Laravel\Ai\Responses\AudioResponse;

Audio::of('I love coding with Laravel.')
    ->queue()
    ->then(function (AudioResponse $audio) {
        $path = $audio->store();
    });

Transkription (STT)

Mit der Klasse Transcription wandeln Sie Audiodateien in Text um. Unterstützt werden OpenAI, ElevenLabs und Mistral.

use Laravel\Ai\Transcription;

$transcript = Transcription::fromPath('/home/laravel/audio.mp3')->generate();
$transcript = Transcription::fromStorage('audio.mp3')->generate();
$transcript = Transcription::fromUpload($request->file('audio'))->generate();

return (string) $transcript;

Sprechertrennung (Diarisierung)

Mit diarize() erhalten Sie eine nach Sprechern getrennte Transkription.

$transcript = Transcription::fromStorage('audio.mp3')->diarize()->generate();

Transkription per Queue

use Laravel\Ai\Responses\TranscriptionResponse;

Transcription::fromStorage('audio.mp3')
    ->queue()
    ->then(function (TranscriptionResponse $transcript) { /* ... */ });

Textzusammenfassung (Text Summarization)

Mit der Methode summarize der Laravel-Klasse Stringable können Sie Text zusammenfassen. Standardmäßig wird in maximal drei Sätzen zusammengefasst und dabei das günstigste Textmodell des konfigurierten Anbieters verwendet.

use Illuminate\Support\Str;

$summary = Str::of($article)->summarize();

Sie können auch die maximale Anzahl an Sätzen, Anbieter, Modell und Timeout angeben. Für die Klasse Str gibt es ebenfalls eine statische Variante.

use Laravel\Ai\Enums\Lab;

$summary = Str::of($article)->summarize(
    sentences: 4,
    provider: Lab::Anthropic,
    model: 'claude-sonnet-5',
    timeout: 30,
);

$summary = Str::summarize($article, sentences: 4);

Embeddings

Sie wandeln Text in eine Vektordarstellung um und nutzen diese etwa für Ähnlichkeitssuchen.

use Illuminate\Support\Str;

// Über Stringable
$embeddings = Str::of('Napa Valley has great wine.')->toEmbeddings();

use Laravel\Ai\Embeddings;

// Mehrere Texte auf einmal verarbeiten
$response = Embeddings::for(['Napa Valley has great wine.', 'Laravel is a PHP framework.'])->generate();
$response->embeddings; // [[0.123, 0.456, ...], [0.789, 0.012, ...]]

Sie können auch Anbieter, Modell und Dimensionen angeben.

$response = Embeddings::for(['Napa Valley has great wine.'])
    ->dimensions(1536)
    ->generate(Lab::OpenAI, 'text-embedding-3-small');

Multimodale Embeddings

Die Methode Embeddings::for akzeptiert neben Strings auch Bilder, Audio, Dokumente und Videos als Eingabe und kann so auch für nicht-textuelle Inhalte Embeddings erzeugen. Gemini unterstützt Embeddings für Bilder, Audio, Dokumente und Videos; VoyageAI unterstützt Embeddings für Bilder und Videos.

use Laravel\Ai\Embeddings;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Files\Image;
use Laravel\Ai\Files\Video;

$response = Embeddings::for([
    'A vineyard at sunset.',
    Image::fromStorage('vineyard.jpg'),
    Video::fromPath('/home/laravel/tour.mp4'),
])->generate(Lab::Gemini);

Für multimodale Eingaben verwenden Sie dieselben Dateiklassen wie für Anhänge. Diese Dateien lassen sich aus lokalen Pfaden, Filesystem-Disks, entfernten URLs oder Base64-kodierten Inhalten erstellen. Bilder, Dokumente und Videos können auch aus hochgeladenen Dateien erstellt werden, Dokumente zusätzlich aus rohen Zeichenkettenwerten.

use Laravel\Ai\Files\Audio;
use Laravel\Ai\Files\Document;
use Laravel\Ai\Files\Image;
use Laravel\Ai\Files\Video;

Image::fromPath('/home/laravel/photo.jpg');
Image::fromStorage('photo.jpg');
Image::fromUpload($request->file('photo'));

Audio::fromPath('/home/laravel/clip.mp3');
Audio::fromStorage('clip.mp3');
Audio::fromUpload($request->file('clip.mp3'));

Video::fromPath('/home/laravel/video.mp4');
Video::fromStorage('video.mp4');
Video::fromUpload($request->file('video'));

Document::fromUrl('https://example.com/report.pdf');
Document::fromString('Laravel is a PHP framework.', 'text/plain');
Document::fromUpload($request->file('report'));

VoyageAI erlaubt es nicht, Medien aus entfernten URLs und Base64-kodierte Medien innerhalb desselben Requests zu mischen. Lokale Dateien, Storage-Dateien und hochgeladene Dateien werden als Base64-kodierte Inhalte gesendet, während Texteingaben mit beiden Medienquellen kombiniert werden können. Prüfen Sie in der Dokumentation des jeweiligen Anbieters die verfügbaren multimodalen Modelle und Eingaben.

Vektorsuche (pgvector)

Ein Beispiel für die Konfiguration der Vektorsuche mit PostgreSQL und der pgvector-Erweiterung:

Migration erstellen

Schema::ensureVectorExtensionExists();

Schema::create('documents', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('content');
    $table->vector('embedding', dimensions: 1536);
    $table->timestamps();
});

// HNSW-Index hinzufügen
$table->vector('embedding', dimensions: 1536)->index();

Modell konfigurieren

protected function casts(): array
{
    return ['embedding' => 'array'];
}

Ähnlichkeitssuche

// Suche mit einem Embedding-Vektor
$documents = Document::query()
    ->whereVectorSimilarTo('embedding', $queryEmbedding, minSimilarity: 0.4)
    ->limit(10)
    ->get();

// Bei Übergabe eines Strings wird das Embedding automatisch erzeugt
$documents = Document::query()
    ->whereVectorSimilarTo('embedding', 'best wineries in Napa Valley')
    ->limit(10)
    ->get();

Auch niedrigere Methoden stehen zur Verfügung.

$documents = Document::query()
    ->select('*')
    ->selectVectorDistance('embedding', $queryEmbedding, as: 'distance')
    ->whereVectorDistanceLessThan('embedding', $queryEmbedding, maxDistance: 0.3)
    ->orderByVectorDistance('embedding', $queryEmbedding)
    ->limit(10)
    ->get();

Embeddings zwischenspeichern

Sie können vermeiden, Embeddings für denselben Text mehrfach zu erzeugen, indem Sie das Ergebnis zwischenspeichern. Konfigurieren Sie die Standard-Cache-Einstellung in config/ai.php.

'caching' => [
    'embeddings' => [
        'cache' => true,
        'store' => env('CACHE_STORE', 'database'),
    ],
],

Sie können den Cache auch pro Request steuern.

$response = Embeddings::for(['Napa Valley has great wine.'])->cache()->generate();
$response = Embeddings::for(['Napa Valley has great wine.'])->cache(seconds: 3600)->generate();

// Stringable analog
$embeddings = Str::of('Napa Valley has great wine.')->toEmbeddings(cache: true);
$embeddings = Str::of('Napa Valley has great wine.')->toEmbeddings(cache: 3600);

Reranking

Sie können Suchergebnisse nach Relevanz zur Anfrage neu anordnen. Unterstützt werden Cohere und Jina.

use Laravel\Ai\Reranking;

$response = Reranking::of([
    'Django is a Python web framework.',
    'Laravel is a PHP web application framework.',
    'React is a JavaScript library for building user interfaces.',
])->rerank('PHP frameworks');

$response->first()->document; // "Laravel is a PHP web application framework."
$response->first()->score;    // 0.95
$response->first()->index;    // 1

Mit limit() schränken Sie die Anzahl der zurückgegebenen Einträge ein.

$response = Reranking::of($documents)->limit(5)->rerank('search query');

Reranking von Collections

Sie können Eloquent-Collections direkt reranken.

// Einzelnes Feld
$posts = Post::all()->rerank('body', 'Laravel tutorials');

// Mehrere Felder (werden als JSON gesendet)
$reranked = $posts->rerank(['title', 'body'], 'Laravel tutorials');

// Eigene Textgenerierung per Closure
$reranked = $posts->rerank(fn ($post) => $post->title.': '.$post->body, 'Laravel tutorials');

// Mit Optionen
$reranked = $posts->rerank(
    by: 'content',
    query: 'Laravel tutorials',
    limit: 10,
    provider: Lab::Cohere,
);

Dateiverwaltung

Sie können Dateien zum KI-Anbieter hochladen und später darauf zugreifen.

use Laravel\Ai\Files\Document;
use Laravel\Ai\Files\Image;

// Aus einem Pfad
$response = Document::fromPath('/home/laravel/document.pdf')->put();
$response = Image::fromPath('/home/laravel/photo.jpg')->put();

// Aus dem Storage
$response = Document::fromStorage('document.pdf', disk: 'local')->put();
$response = Image::fromStorage('photo.jpg', disk: 'local')->put();

// Aus einer URL
$response = Document::fromUrl('https://example.com/document.pdf')->put();
$response = Image::fromUrl('https://example.com/photo.jpg')->put();

return $response->id;

Auch Zeichenketten und Formular-Uploads sind möglich.

$stored = Document::fromString('Hello, World!', 'text/plain')->put();
$stored = Document::fromUpload($request->file('document'))->put();

Referenzierung gespeicherter Dateien

Sie hängen eine bereits hochgeladene Datei über ihre ID an einen Agenten an.

use Laravel\Ai\Files;

$response = (new SalesCoach)->prompt(
    'Analyze the attached sales transcript...',
    attachments: [Files\Document::fromId('file-id')]
);

Dateien abrufen und löschen

// Abrufen
$file = Document::fromId('file-id')->get();
$file->id;
$file->mimeType();

// Löschen
Document::fromId('file-id')->delete();

Anbieter angeben

$response = Document::fromPath('/home/laravel/document.pdf')->put(provider: Lab::Anthropic);

Anbieterspezifische Optionen angeben

Mit der Methode withProviderOptions übergeben Sie anbieterspezifische Upload-Optionen. So können Sie z. B. bei OpenAI den Datei-purpose setzen.

use Laravel\Ai\Files\Document;

$response = Document::fromPath('/home/laravel/knowledge.txt')
    ->withProviderOptions(['purpose' => 'assistants'])
    ->put();

Wenn Sie je Anbieter unterschiedliche Optionen setzen möchten, übergeben Sie eine Closure.

use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Files\Document;

$response = Document::fromPath('/home/laravel/training.jsonl')
    ->withProviderOptions(fn (Lab|string $provider) => match ($provider) {
        Lab::OpenAI => ['purpose' => 'fine-tune'],
        default => [],
    })
    ->put();

Vector Stores

Mit Vector Stores lassen sich Dokumente auf Anbieterseite verwalten.

use Laravel\Ai\Stores;

// Erstellen
$store = Stores::create('Knowledge Base');
$store = Stores::create(
    name: 'Knowledge Base',
    description: 'Documentation.',
    expiresWhenIdleFor: days(30),
);
return $store->id;

// Abrufen
$store = Stores::get('store_id');
$store->id;
$store->name;
$store->fileCounts;
$store->ready;

// Löschen
Stores::delete('store_id');
$store->delete();

Dateien zum Store hinzufügen

$store = Stores::get('store_id');

// Dateien auf verschiedene Weise hinzufügen
$document = $store->add('file_id');
$document = $store->add(Document::fromId('file_id'));
$document = $store->add(Document::fromPath('/path/to/document.pdf'));
$document = $store->add(Document::fromStorage('manual.pdf'));
$document = $store->add($request->file('document'));

$document->id;
$document->fileId;

Sie können auch Metadaten hinzufügen.

$store->add(
    Document::fromPath('/path/to/document.pdf'),
    metadata: [
        'author' => 'Taylor Otwell',
        'department' => 'Engineering',
        'year' => 2026,
    ]
);

Dateien aus dem Store entfernen

$store->remove('file_id');

// Datei selbst ebenfalls löschen
$store->remove('file_abc123', deleteFile: true);

Failover

Wenn Sie mehrere Anbieter als Array angeben, wird bei Ausfall des ersten Anbieters automatisch auf den nächsten umgeschaltet.

use App\Ai\Agents\SalesCoach;
use Laravel\Ai\Image;

// Failover für Agenten
$response = (new SalesCoach)->prompt(
    'Analyze this sales transcript...',
    provider: [Lab::OpenAI, Lab::Anthropic],
);

// Failover für die Bildgenerierung
$image = Image::of('A donut sitting on the kitchen counter')
    ->generate(provider: [Lab::Gemini, Lab::xAI]);

Tests

Das Laravel AI SDK stellt Fake-Funktionen für Tests bereit, sodass Sie testen können, ohne echte APIs anzusprechen.

Agenten testen

use App\Ai\Agents\SalesCoach;
use Laravel\Ai\Prompts\AgentPrompt;

// Fake mit festen Antworten
SalesCoach::fake();
SalesCoach::fake(['First response', 'Second response']);

// Dynamische Antworten per Closure
SalesCoach::fake(function (AgentPrompt $prompt) {
    return 'Response for: '.$prompt->prompt;
});

// Assertions
SalesCoach::assertPrompted('Analyze this...');
SalesCoach::assertPrompted(function (AgentPrompt $prompt) {
    return $prompt->contains('Analyze');
});
SalesCoach::assertNotPrompted('Missing prompt');
SalesCoach::assertNeverPrompted();

Auch Queue-Assertions sind verfügbar.

use Laravel\Ai\QueuedAgentPrompt;

SalesCoach::assertQueued('Analyze this...');
SalesCoach::assertQueued(function (QueuedAgentPrompt $prompt) {
    return $prompt->contains('Analyze');
});
SalesCoach::assertNotQueued('Missing prompt');
SalesCoach::assertNeverQueued();

Mit preventStrayPrompts() wird eine Exception ausgelöst, wenn ein Prompt aufgerufen wird, der nicht im Fake definiert ist.

SalesCoach::fake()->preventStrayPrompts();

Wenn Sie einen Agenten mit strukturierter Ausgabe faken, können Sie die Antwort als Array angeben. Der Agent gibt dann eine strukturierte Antwort mit den angegebenen Daten zurück.

SalesCoach::fake([
    ['score' => 87],
]);

Wenn fake() bei einem Agenten mit strukturierter Ausgabe ohne explizite Fake-Daten aufgerufen wird, generiert Laravel automatisch Fake-Daten, die dem definierten Schema entsprechen.

Zum Testen anonymer Agenten verwenden Sie AnonymousAgent::fake().

use Laravel\Ai\AnonymousAgent;

AnonymousAgent::fake(['Test response']);

Bildgenerierung testen

use Laravel\Ai\Image;
use Laravel\Ai\Prompts\ImagePrompt;

Image::fake();
Image::fake([base64_encode($firstImage), base64_encode($secondImage)]);
Image::fake(function (ImagePrompt $prompt) {
    return base64_encode('...');
});

Image::assertGenerated(function (ImagePrompt $prompt) {
    return $prompt->contains('sunset') && $prompt->isLandscape();
});
Image::assertNotGenerated('Missing prompt');
Image::assertNothingGenerated();

Image::assertQueued(fn (QueuedImagePrompt $prompt) => $prompt->contains('sunset'));
Image::assertNotQueued('Missing prompt');
Image::assertNothingQueued();

Image::fake()->preventStrayImages();

Sprachsynthese testen

use Laravel\Ai\Audio;
use Laravel\Ai\Prompts\AudioPrompt;

Audio::fake();
Audio::fake([base64_encode($firstAudio), base64_encode($secondAudio)]);
Audio::fake(function (AudioPrompt $prompt) {
    return base64_encode('...');
});

Audio::assertGenerated(function (AudioPrompt $prompt) {
    return $prompt->contains('Hello') && $prompt->isFemale();
});
Audio::assertNotGenerated('Missing prompt');
Audio::assertNothingGenerated();

Audio::assertQueued(fn (QueuedAudioPrompt $prompt) => $prompt->contains('Hello'));
Audio::assertNotQueued('Missing prompt');
Audio::assertNothingQueued();

Audio::fake()->preventStrayAudio();

Transkription testen

use Laravel\Ai\Transcription;
use Laravel\Ai\Prompts\TranscriptionPrompt;

Transcription::fake();
Transcription::fake(['First transcription text.', 'Second transcription text.']);
Transcription::fake(function (TranscriptionPrompt $prompt) {
    return 'Transcribed text...';
});

Transcription::assertGenerated(function (TranscriptionPrompt $prompt) {
    return $prompt->language === 'en' && $prompt->isDiarized();
});
Transcription::assertNotGenerated(fn (TranscriptionPrompt $prompt) => $prompt->language === 'fr');
Transcription::assertNothingGenerated();

Transcription::assertQueued(fn (QueuedTranscriptionPrompt $prompt) => $prompt->isDiarized());
Transcription::assertNotQueued(fn (QueuedTranscriptionPrompt $prompt) => $prompt->language === 'fr');
Transcription::assertNothingQueued();

Transcription::fake()->preventStrayTranscriptions();

Embeddings testen

use Laravel\Ai\Embeddings;
use Laravel\Ai\Prompts\EmbeddingsPrompt;

Embeddings::fake();
Embeddings::fake([[$firstEmbeddingVector], [$secondEmbeddingVector]]);
Embeddings::fake(function (EmbeddingsPrompt $prompt) {
    return array_map(
        fn () => Embeddings::fakeEmbedding($prompt->dimensions),
        $prompt->inputs
    );
});

Embeddings::assertGenerated(function (EmbeddingsPrompt $prompt) {
    return $prompt->contains('Laravel') && $prompt->dimensions === 1536;
});
Embeddings::assertNotGenerated(fn (EmbeddingsPrompt $prompt) => $prompt->contains('Other'));
Embeddings::assertNothingGenerated();

Embeddings::assertQueued(fn (QueuedEmbeddingsPrompt $prompt) => $prompt->contains('Laravel'));
Embeddings::assertNotQueued(fn (QueuedEmbeddingsPrompt $prompt) => $prompt->contains('Other'));
Embeddings::assertNothingQueued();

Embeddings::fake()->preventStrayEmbeddings();

Reranking testen

use Laravel\Ai\Reranking;
use Laravel\Ai\Prompts\RerankingPrompt;
use Laravel\Ai\Responses\Data\RankedDocument;

Reranking::fake();
Reranking::fake([[
    new RankedDocument(index: 0, document: 'First', score: 0.95),
    new RankedDocument(index: 1, document: 'Second', score: 0.80),
]]);

Reranking::assertReranked(function (RerankingPrompt $prompt) {
    return $prompt->contains('Laravel') && $prompt->limit === 5;
});
Reranking::assertNotReranked(fn (RerankingPrompt $prompt) => $prompt->contains('Django'));
Reranking::assertNothingReranked();

Dateien testen

use Laravel\Ai\Files;
use Laravel\Ai\Contracts\Files\StorableFile;
use Laravel\Ai\Files\Document;

Files::fake();

Document::fromString('Hello, Laravel!', mimeType: 'text/plain')->as('hello.txt')->put();

Files::assertStored(fn (StorableFile $file) =>
    (string) $file === 'Hello, Laravel!' && $file->mimeType() === 'text/plain'
);
Files::assertNotStored(fn (StorableFile $file) => (string) $file === 'Hello, World!');
Files::assertNothingStored();

Files::assertDeleted('file-id');
Files::assertNotDeleted('file-id');
Files::assertNothingDeleted();

Vector Stores testen

use Laravel\Ai\Stores;

Stores::fake(); // Dateiaktionen werden ebenfalls gefakt

$store = Stores::create('Knowledge Base');

Stores::assertCreated('Knowledge Base');
Stores::assertCreated(fn (string $name, ?string $description) => $name === 'Knowledge Base');
Stores::assertNotCreated('Other Store');
Stores::assertNothingCreated();

Stores::assertDeleted('store_id');
Stores::assertNotDeleted('other_store_id');
Stores::assertNothingDeleted();

Auch Assertions für Dateiaktionen am Store sind möglich.

$store = Stores::get('store_id');
$store->add('added_id');
$store->remove('removed_id');

$store->assertAdded('added_id');
$store->assertRemoved('removed_id');
$store->assertNotAdded('other_file_id');
$store->assertNotRemoved('other_file_id');

// Inhalt per Closure verifizieren
$store->add(Document::fromString('Hello, World!', 'text/plain')->as('hello.txt'));
$store->assertAdded(fn (StorableFile $file) => $file->name() === 'hello.txt');
$store->assertAdded(fn (StorableFile $file) => $file->content() === 'Hello, World!');

Events

Das Laravel AI SDK dispatcht die folgenden Events. Über das Abonnieren dieser Events können Sie Logging und Monitoring realisieren.

Agenten-bezogen

PromptingAgent — Vor dem Senden des Prompts
AgentPrompted — Nach dem Senden des Prompts
StreamingAgent — Bei Beginn des Streamings
AgentStreamed — Nach Abschluss des Streamings
InvokingTool — Vor dem Aufruf eines Tools
ToolInvoked — Nach dem Aufruf eines Tools
ToolApprovalRequested — Bei Anfrage einer Tool-Freigabe
ToolApprovalResolved — Nach Auflösung einer Tool-Freigabe

Bild, Audio und Transkription

GeneratingImage — Vor der Bildgenerierung
ImageGenerated — Nach der Bildgenerierung
GeneratingAudio — Vor der Sprachsynthese
AudioGenerated — Nach der Sprachsynthese
GeneratingTranscription — Vor der Transkription
TranscriptionGenerated — Nach der Transkription

Embeddings und Reranking

GeneratingEmbeddings — Vor der Erzeugung von Embeddings
EmbeddingsGenerated — Nach der Erzeugung von Embeddings
Reranking — Vor dem Reranking
Reranked — Nach dem Reranking

Dateien und Stores

StoringFile — Vor dem Speichern einer Datei
FileStored — Nach dem Speichern einer Datei
FileDeleted — Nach dem Löschen einer Datei
CreatingStore — Vor dem Erstellen eines Stores
StoreCreated — Nach dem Erstellen eines Stores
AddingFileToStore — Vor dem Hinzufügen einer Datei zum Store
FileAddedToStore — Nach dem Hinzufügen einer Datei zum Store
RemovingFileFromStore — Vor dem Entfernen einer Datei aus dem Store
FileRemovedFromStore — Nach dem Entfernen einer Datei aus dem Store

Zuletzt geändert am 2. August 2026

Verwandte Themen

Übersicht der neuen Features in Laravel 13 Laravel-Updates März 2026 Laravel AI SDK-Integration Laravel-AI-SDK-Integration - VOICEVOX für Laravel Amazon-Bedrock-Treiber für das Laravel AI SDK

​Einführung

​Übersicht der unterstützten Anbieter

​Installation

​Konfiguration

​Umgebungsvariablen

​Benutzerdefinierte Basis-URL

​OpenAI-kompatible Anbieter

​Lab-Enum

​Agenten

​Prompt

​Konversationskontext

​Strukturierte Ausgabe

​Verschachtelte Objekte

​Array von Objekten

​anyOf (Auswahl aus mehreren Schemata)

​Anhänge

​Streaming

​Vercel-AI-SDK-Protokoll

​Broadcasting

​Große Events überspringen

​Queue

​Tools

​Similarity-Search-Tool

​File-Storage-Tools

​MCP-Tools

​Anbieter-Tools

​Websuche

​Web-Fetch

​Dateisuche

​Sub-Agenten

​Middleware

​Anonyme Agenten

​Agentenkonfiguration (PHP-Attribute)

​Provider-Optionen

​Freigabe durch den Menschen (Human Tool Approval)

​Vollständiger Freigabe-Ablauf

​Bildgenerierung

​Bild speichern

​Bildgenerierung per Queue

​Sprachsynthese (TTS)

​Audio speichern

​Sprachsynthese per Queue

​Transkription (STT)

​Sprechertrennung (Diarisierung)

​Transkription per Queue

​Textzusammenfassung (Text Summarization)

​Embeddings

​Multimodale Embeddings

​Vektorsuche (pgvector)

​Embeddings zwischenspeichern

​Reranking

​Reranking von Collections

​Dateiverwaltung

​Referenzierung gespeicherter Dateien

​Dateien abrufen und löschen

​Anbieter angeben

​Anbieterspezifische Optionen angeben

​Vector Stores

​Dateien zum Store hinzufügen

​Dateien aus dem Store entfernen

​Failover

​Tests

​Agenten testen

​Bildgenerierung testen

​Sprachsynthese testen

​Transkription testen

​Embeddings testen

​Reranking testen

​Dateien testen

​Vector Stores testen

​Events

Einführung

Übersicht der unterstützten Anbieter

Installation

Konfiguration

Umgebungsvariablen

Benutzerdefinierte Basis-URL

OpenAI-kompatible Anbieter

Lab-Enum

Agenten

Prompt

Konversationskontext

Strukturierte Ausgabe

Verschachtelte Objekte

Array von Objekten

anyOf (Auswahl aus mehreren Schemata)

Anhänge

Streaming

Vercel-AI-SDK-Protokoll

Broadcasting

Große Events überspringen

Queue

Tools

Similarity-Search-Tool

File-Storage-Tools

MCP-Tools

Anbieter-Tools

Websuche

Web-Fetch

Dateisuche

Sub-Agenten

Middleware

Anonyme Agenten

Agentenkonfiguration (PHP-Attribute)

Provider-Optionen

Freigabe durch den Menschen (Human Tool Approval)

Vollständiger Freigabe-Ablauf

Bildgenerierung

Bild speichern

Bildgenerierung per Queue

Sprachsynthese (TTS)

Audio speichern

Sprachsynthese per Queue

Transkription (STT)

Sprechertrennung (Diarisierung)

Transkription per Queue

Textzusammenfassung (Text Summarization)

Embeddings

Multimodale Embeddings

Vektorsuche (pgvector)

Embeddings zwischenspeichern

Reranking

Reranking von Collections

Dateiverwaltung

Referenzierung gespeicherter Dateien

Dateien abrufen und löschen

Anbieter angeben

Anbieterspezifische Optionen angeben

Vector Stores

Dateien zum Store hinzufügen

Dateien aus dem Store entfernen

Failover

Tests

Agenten testen

Bildgenerierung testen

Sprachsynthese testen

Transkription testen

Embeddings testen

Reranking testen

Dateien testen

Vector Stores testen

Events