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

# Agentmiddleware in de Laravel AI SDK

> Uitvoeringsvolgorde van middleware per modelaanroep, verwerking na de respons en stoppen op basis van cumulatieve tokens in de AI SDK van Laravel 13.

Wanneer een agent meerdere tools gebruikt, wil je soms **het verbruik controleren voordat het model wordt aangeroepen en de respons van elke stap vastleggen**. Middleware in de Laravel AI SDK omhult niet eenmalig de hele agent, maar wordt bij elke stap van de generatie uitgevoerd. Op basis van de officiële documentatie van Laravel 13 en de implementatie van `laravel/ai` `v1.3.0` gaat deze pagina een stap verder dan [de basis van de AI SDK](/nl/ai-sdk) en zet de uitvoeringsvolgorde en stopvoorwaarden op een rij.

## De eenheid waarin middleware wordt uitgevoerd

Wanneer een agent een respons van het model ontvangt, tools uitvoert en het model opnieuw aanroept, is de volgende modelaanroep een **aparte stap**. Vlak voor elke stap gaat de uitvoering door de middleware die `HasMiddleware::middleware()` teruggeeft, in de volgorde waarin die is gedeclareerd.

De `PendingStep` die aan `handle(PendingStep $step, Closure $next)` van de middleware wordt doorgegeven, bevat de array `steps` met reeds uitgevoerde stappen, hun cumulatieve verbruik `usage` en het huidige, vanaf nul tellende stapnummer `number`. Bij de eerste stap bevat `usage` nog niet het verbruik van de huidige modelaanroep.

```mermaid theme={null}
flowchart TD
    A["Volgende PendingStep<br>cumulatieve usage van voltooide stappen"] --> B["Evalueren in declaratievolgorde van middleware()"]
    B --> C{"Voldoet aan Stop-voorwaarde?"}
    C -->|Ja| D["Stoppen zonder het model voor deze stap aan te roepen"]
    C -->|Nee| E["Model aanroepen"]
    E --> F["StepResponse ontvangen"]
    F --> G["then()-callback uitvoeren"]
    G --> H["Tools uitvoeren indien nodig"]
    H --> I{"Volgende stap nodig?"}
    I -->|Ja| A
    I -->|Nee| J["Respons van de agent afronden"]
```

De `then()` die je aan het resultaat van `$next($step)` koppelt, draait **nadat het model heeft geantwoord en voordat toolaanroepen worden uitgevoerd**. Het is geen hook die pas na de uitvoering van tools wordt aangeroepen. Bovendien is `usage` op dat moment het totaal van eerder voltooide stappen en voorspelt het niet het aantal tokens van de lopende request.

## Verwerking per stap registreren

In dit voorbeeld worden alleen het stapnummer en het aantal tot dan toe gebruikte inputtokens gelogd. Sla prompttekst of modeloutput niet zomaar onvoorwaardelijk op in logs.

```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]);
        });
    }
}
```

Implementeer `HasMiddleware` op de agent en geef de instanties terug vanuit `middleware()`.

```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,
        ];
    }
}
```

Zet `Stop` in de volgorde van `middleware()` vooraan. Wanneer de limiet is overschreden en **de volgende stap niet wordt gestart**, wordt de daaropvolgende `LogAgentSteps` voor die stap niet uitgevoerd. Draai je de volgorde om, dan kan het gebeuren dat alleen "starting" wordt gelogd en "model responded" niet. Geef het resultaat van `$next($step)` terug vanuit `handle()`; de callback van `then()` hoeft geen respons terug te geven.

## Stop houdt de volgende modelaanroep tegen

`Stop::when(...)` beëindigt de verwerking vóór de betreffende stap wanneer de voorwaarde true wordt, en `Stop::unless(...)` wanneer de voorwaarde false wordt. Het voorbeeld hierboven doet geen volgende aanroep meer zodra de cumulatieve inputtokens van **voltooide stappen** 50.000 of meer bedragen. Het is geen harde limiet die een enkele modelaanroep geforceerd afbreekt voordat de drempel wordt overschreden.

| Moment van evaluatie | Resultaat als de voorwaarde geldt |
| - | - |
| Vóór het aanroepen van de eerste stap | Het model wordt niet aangeroepen; voltooide stappen en de responstekst zijn leeg |
| Vóór de volgende stap na het uitvoeren van tools | Stopt en behoudt de tot dan toe voltooide stappen en het verbruik |
| Vóór de volgende stap bij streaming | De stopreden van de stream wordt `cancelled` |

> [!WARNING]
>
> `Stop` breekt een lopende request naar de provider niet af. Als je een verbruikslimiet strikt moet garanderen, vertrouw dan niet alleen op de evaluatie vóór de volgende stap, maar overweeg ook limieten aan de kant van het model of de provider.

Middleware die op een eigen voorwaarde wil stoppen, kan ook `Laravel\Ai\Gateway\StepResult::stop()` teruggeven. Vanuit `handle()` geef je het resultaat van `$next($step)`, een `StepResponse` of `StepResult::stop()` terug. Een ander type teruggeven leidt tot een exception.

## De uitvoeringsvolgorde verifiëren

Controleer ten minste de volgende gevallen, zodat je modelresponses en de uitvoering van tools niet door elkaar haalt.

* Bij een generatie van één stap verschijnen de startlog en de log van de modelrespons elk één keer.
* Bij extra stappen na een tool loopt het nummer op vanaf 0 en bevat de `usage` van latere stappen het verbruik van eerdere stappen.
* Als de stopvoorwaarde vanaf het begin geldt, vinden er geen modelaanroep en geen logs van `LogAgentSteps` plaats.
* Als de voorwaarde halverwege wordt bereikt, blijven de stappen tot dat moment behouden en vindt de modelaanroep voor de volgende stap niet plaats.

Test het normale pad en het stoppende pad apart en controleer hoe vaak elke stap wordt uitgevoerd. Ook als `then()` neveneffecten nodig heeft, ontwerp je die in de veronderstelling dat de callback niet wordt aangeroepen op paden die mislukken of stoppen voordat er een modelrespons is.

## Geraadpleegde primaire bronnen

* [Officiële documentatie van Laravel 13: middleware in de AI SDK](https://github.com/laravel/docs/blob/13.x/ai-sdk.md)
* [Laravel AI SDK v1.3.0: waarden van PendingStep](https://github.com/laravel/ai/blob/v1.3.0/src/PendingStep.php#L18-L46)
* [Laravel AI SDK v1.3.0: generatielus](https://github.com/laravel/ai/blob/v1.3.0/src/Gateway/TextGenerationLoop.php#L133-L188) en [uitvoeringsvolgorde van middleware](https://github.com/laravel/ai/blob/v1.3.0/src/Gateway/TextGenerationLoop.php#L441-L468)
* [Laravel AI SDK v1.3.0: StepResult::stop() en 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 voor het stoppen van stappen](https://github.com/laravel/ai/blob/v1.3.0/tests/Feature/AgentMiddlewareTest.php#L300-L345)


## Related topics

- [Geavanceerde onderwerpen](/nl/advanced/index.md)
- [Laravel AI SDK](/nl/ai-sdk.md)
- [Laravel AI SDK-integratie](/nl/packages/laravel-copilot-sdk/ai-sdk.md)
- [Laravel AI SDK-integratie - VOICEVOX for Laravel](/nl/packages/laravel-voicevox/ai-sdk.md)
- [Amazon Bedrock-driver voor de Laravel AI SDK](/nl/packages/laravel-amazon-bedrock.md)


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