> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Agenten-Middleware im Laravel AI SDK

> Erklärt für das AI SDK in Laravel 13 die Ausführungsreihenfolge von Middleware pro Modellaufruf, die Verarbeitung nach der Antwort und das Anhalten anhand kumulierter Tokens.

Wenn ein Agent mehrere Tools verwendet, möchten Sie möglicherweise **vor dem Modellaufruf den Verbrauch prüfen und die Antwort jedes Schritts protokollieren**. Middleware im Laravel AI SDK umschließt nicht einmalig den gesamten Agenten, sondern wird bei jedem Schritt der Generierung ausgeführt. Auf Basis der offiziellen Laravel-13-Dokumentation und der Implementierung von `laravel/ai` in `v1.3.0` geht diese Seite einen Schritt über die [Grundlagen des AI SDK](/de/ai-sdk) hinaus und ordnet Ausführungsreihenfolge und Abbruchbedingungen ein.

## In welcher Einheit Middleware ausgeführt wird

Wenn ein Agent eine Modellantwort erhält, ein Tool ausführt und das Modell erneut aufruft, ist der nächste Modellaufruf ein **eigener Schritt**. Unmittelbar vor jedem Schritt durchläuft die Anfrage die von `HasMiddleware::middleware()` zurückgegebene Middleware in der deklarierten Reihenfolge.

Das `PendingStep`, das an `handle(PendingStep $step, Closure $next)` der Middleware übergeben wird, enthält das Array der bereits ausgeführten Schritte `steps`, deren kumulierten Verbrauch `usage` und die nullbasierte Nummer des aktuellen Schritts `number`. Beim ersten Mal enthält `usage` den Verbrauch des aktuellen Modellaufrufs noch nicht.

```mermaid theme={null}
flowchart TD
    A["Nächster PendingStep<br>kumulierte usage der abgeschlossenen Schritte"] --> B["Auswertung in der Reihenfolge von middleware()"]
    B --> C{"Stop-Bedingung erfüllt?"}
    C -->|Ja| D["Ohne Modellaufruf für diesen Schritt beenden"]
    C -->|Nein| E["Modell aufrufen"]
    E --> F["StepResponse empfangen"]
    F --> G["then()-Callback ausführen"]
    G --> H["Bei Bedarf Tools ausführen"]
    H --> I{"Nächster Schritt nötig?"}
    I -->|Ja| A
    I -->|Nein| J["Antwort des Agenten festlegen"]
```

Ein an das Ergebnis von `$next($step)` angehängtes `then()` läuft, **nachdem das Modell geantwortet hat und bevor Tool-Aufrufe ausgeführt werden**. Es ist kein Hook, der erst nach der Tool-Ausführung aufgerufen wird. Außerdem ist `usage` zu diesem Zeitpunkt die Summe der zuvor abgeschlossenen Schritte und sagt nicht die Tokenanzahl der laufenden Anfrage voraus.

## Verarbeitung pro Schritt registrieren

Dieses Beispiel protokolliert nur die Schrittnummer und die Anzahl der bis dahin verbrauchten Eingabetokens. Speichern Sie Prompt-Texte oder Modellausgaben nicht bedingungslos im Log.

```php theme={null}
<?php

namespace App\Ai\Middleware;

use Closure;
use Illuminate\Support\Facades\Log;
use Laravel\Ai\Gateway\StepResponse;
use Laravel\Ai\PendingStep;

final class LogAgentSteps
{
    public function handle(PendingStep $step, Closure $next)
    {
        Log::info('AI step starting', [
            'step' => $step->number,
            'input_tokens_used' => $step->usage->inputTokens,
        ]);

        return $next($step)->then(function (StepResponse $response) use ($step): void {
            Log::info('AI model responded', ['step' => $step->number]);
        });
    }
}
```

Implementieren Sie im Agenten `HasMiddleware` und geben Sie die Instanzen aus `middleware()` zurück.

```php theme={null}
<?php

namespace App\Ai\Agents;

use App\Ai\Middleware\LogAgentSteps;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasMiddleware;
use Laravel\Ai\Middleware\Stop;
use Laravel\Ai\PendingStep;
use Laravel\Ai\Promptable;

class SupportAgent implements Agent, HasMiddleware
{
    use Promptable;

    public function instructions(): string
    {
        return 'Answer support questions concisely.';
    }

    public function middleware(): array
    {
        return [
            Stop::when(fn (PendingStep $step): bool => $step->usage->inputTokens >= 50_000),
            new LogAgentSteps,
        ];
    }
}
```

Platzieren Sie `Stop` in der Reihenfolge von `middleware()` zuerst. Wenn das Limit überschritten ist und **der nächste Schritt nicht gestartet wird**, wird das nachfolgende `LogAgentSteps` in diesem Schritt nicht ausgeführt. Bei umgekehrter Reihenfolge kann es passieren, dass nur der „Start“ protokolliert wird, „Modell hat geantwortet“ aber nicht. Geben Sie das Ergebnis von `$next($step)` aus `handle()` zurück. Im Callback von `then()` müssen Sie keine Antwort zurückgeben.

## Stop verhindert den nächsten Modellaufruf

`Stop::when(...)` beendet die Verarbeitung vor dem jeweiligen Schritt, wenn die Bedingung true wird, `Stop::unless(...)`, wenn sie false wird. Im obigen Beispiel erfolgt kein weiterer Aufruf mehr, sobald die kumulierten Eingabetokens der **abgeschlossenen Schritte** 50.000 oder mehr betragen. Es handelt sich nicht um ein hartes Limit, das einen einzelnen Modellaufruf erzwungen abbricht, bevor er den Schwellenwert überschreitet.

| Zeitpunkt der Prüfung | Ergebnis bei erfüllter Bedingung |
| - | - |
| Vor dem Aufruf des ersten Schritts | Das Modell wird nicht aufgerufen, abgeschlossene Schritte und Antworttext bleiben leer |
| Vor dem Aufruf des nächsten Schritts nach einer Tool-Ausführung | Beendet unter Beibehaltung der bis dahin abgeschlossenen Schritte und des Verbrauchs |
| Vor dem Aufruf des nächsten Schritts beim Streaming | Der Beendigungsgrund des Streams ist `cancelled` |

> [!WARNING]
>
> `Stop` bricht keine laufende Anfrage an den Provider ab. Wenn Sie ein Verbrauchslimit strikt garantieren müssen, verlassen Sie sich nicht nur auf die Prüfung vor dem nächsten Schritt, sondern ziehen Sie auch Limits auf Modell- oder Provider-Seite in Betracht.

Middleware, die nach eigenen Bedingungen anhalten soll, kann auch `Laravel\Ai\Gateway\StepResult::stop()` zurückgeben. Aus `handle()` geben Sie das Ergebnis von `$next($step)`, ein `StepResponse` oder `StepResult::stop()` zurück. Die Rückgabe eines anderen Typs löst eine Exception aus.

## Ausführungsreihenfolge überprüfen

Damit Sie Modellantwort und Tool-Ausführung nicht verwechseln, prüfen Sie mindestens die folgenden Fälle:

* Bei einer Generierung mit nur einem Schritt erscheinen Start-Log und Modellantwort-Log jeweils einmal.
* Bei weiteren Schritten nach einem Tool steigt die Nummer ab 0 an, und `usage` der nachfolgenden Schritte enthält den Verbrauch der vorherigen Schritte.
* Ist die Abbruchbedingung von Anfang an erfüllt, erfolgen weder ein Modellaufruf noch Logs von `LogAgentSteps`.
* Wird die Bedingung zwischendurch erreicht, bleiben die bisherigen Schritte erhalten, und der Modellaufruf des nächsten Schritts findet nicht statt.

Trennen Sie den normalen Pfad vom Abbruchpfad und prüfen Sie, wie oft jeder Schritt ausgeführt wird. Auch wenn `then()` Seiteneffekte benötigt, gehen Sie bei Ihrem Design davon aus, dass es in Pfaden, die vor Erhalt einer Modellantwort fehlschlagen oder anhalten, nicht aufgerufen wird.

## Verwendete Primärquellen

* [Offizielle Laravel-13-Dokumentation: Middleware im AI SDK](https://github.com/laravel/docs/blob/13.x/ai-sdk.md)
* [Laravel AI SDK v1.3.0: Werte von PendingStep](https://github.com/laravel/ai/blob/v1.3.0/src/PendingStep.php#L18-L46)
* [Laravel AI SDK v1.3.0: Generierungsschleife](https://github.com/laravel/ai/blob/v1.3.0/src/Gateway/TextGenerationLoop.php#L133-L188) und [Ausführungsreihenfolge der Middleware](https://github.com/laravel/ai/blob/v1.3.0/src/Gateway/TextGenerationLoop.php#L441-L468)
* [Laravel AI SDK v1.3.0: StepResult::stop() und then()](https://github.com/laravel/ai/blob/v1.3.0/src/Gateway/StepResult.php#L37-L59)
* [Laravel AI SDK v1.3.0: Stop-Middleware](https://github.com/laravel/ai/blob/v1.3.0/src/Middleware/Stop.php)
* [Laravel AI SDK v1.3.0: Tests zum Anhalten von Schritten](https://github.com/laravel/ai/blob/v1.3.0/tests/Feature/AgentMiddlewareTest.php#L300-L345)


## Related topics

- [Weiterführende Themen](/de/advanced/index.md)
- [Laravel-KI-Agenten unterstützen MCP-Server](/de/blog/ai-sdk-mcp-client.md)
- [Laravel AI SDK](/de/ai-sdk.md)
- [Benutzerdefinierte Agenten](/de/packages/laravel-copilot-sdk/custom-agents.md)
- [Einen eigenen Agenten für Boost erstellen](/de/advanced/boost-custom-agent.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.