Agents PHP résilients : gérer le fallback LLM avec Neuron AI Router

Vous avez déployé un agent IA en production. Tout fonctionne. Et puis, un matin, OpenAI répond avec une erreur 429 Too Many Requests. Ou Anthropic timeout. Votre agent s'effondre, et avec lui l'expérience utilisateur.

Ce scénario est plus courant qu'on ne le croit. La bonne nouvelle : la nouvelle stratégie de fallback de Neuron AI Router permet de l'éviter proprement, en PHP, sans logique de retry artisanale.

Cet article est inspiré d'un article publié sur dev.to par l'équipe Inspector.dev.

Pourquoi les providers LLM tombent en production

Un provider LLM, c'est un service HTTP externe. À chaque inférence, votre agent envoie une requête à une machine que vous ne contrôlez pas, partagée avec des millions d'autres utilisateurs.

Les causes de défaillance les plus fréquentes :

• Rate limiting (429) : vous avez dépassé votre quota de requêtes par minute ou par jour.
• Timeout : le modèle met trop longtemps à répondre, votre client coupe la connexion.
• Serveur surchargé (503) : le provider est en pic de charge.
• Incident réseau ou maintenance : indisponibilité partielle ou totale.

Ces erreurs sont transitoires : elles ne signifient pas que votre code est cassé, mais que le service est temporairement indisponible. La réponse classique — wrapper le tout dans un try/catch avec un sleep() — est fragile et bloque le thread PHP.

La stratégie de fallback dans Neuron AI Router

Neuron AI Router est une librairie PHP qui permet de router les appels LLM selon différentes stratégies : round-robin, règles métier, ou désormais fallback ordonné.

Le principe du fallback est simple : vous définissez une liste ordonnée de providers. Si le premier échoue avec une erreur transitoire, la même requête est automatiquement rejouée sur le suivant. L'agent ne voit rien, la conversation conserve son état.

Configuration de base

Voici comment configurer un fallback entre OpenAI, Anthropic et Mistral :

use NeuronAI\Router\Router;
use NeuronAI\Router\Strategy\Fallback;
use NeuronAI\Providers\OpenAI\OpenAI;
use NeuronAI\Providers\Anthropic\Anthropic;
use NeuronAI\Providers\Mistral\Mistral;

$router = new Router(
    new Fallback([
        new OpenAI(
            key: $_ENV['OPENAI_API_KEY'],
            model: 'gpt-4o-mini',
        ),
        new Anthropic(
            key: $_ENV['ANTHROPIC_API_KEY'],
            model: 'claude-3-5-haiku-20241022',
        ),
        new Mistral(
            key: $_ENV['MISTRAL_API_KEY'],
            model: 'mistral-small-latest',
        ),
    ])
);

Si OpenAI retourne un 429 ou un 503, Neuron AI bascule automatiquement sur Anthropic. Si Anthropic échoue également, Mistral prend le relais. Le tout de façon transparente pour votre agent.

Intégration avec un agent

L'intégration dans un agent existant ne nécessite aucun refactoring majeur :

use NeuronAI\Agent;

class MyAgent extends Agent
{
    public function provider(): RouterInterface
    {
        return new Router(
            new Fallback([
                new OpenAI(key: $_ENV['OPENAI_API_KEY'], model: 'gpt-4o-mini'),
                new Anthropic(key: $_ENV['ANTHROPIC_API_KEY'], model: 'claude-3-5-haiku-20241022'),
            ])
        );
    }

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

L'agent expose la même interface qu'avec un provider unique. Aucune gestion d'erreur à écrire manuellement.

Ce que le fallback gère (et ce qu'il ne gère pas)

⚠️ Le fallback ne se déclenche que sur les erreurs transitoires : rate limits, timeouts, serveurs surchargés.

Il ne couvre pas :

• Les erreurs de prompt mal formé (erreur 400) : retenter sur un autre provider ne changera rien.
• Les erreurs d'authentification (401, 403) : vérifiez vos clés API.
• Les réponses vides ou incohérentes : ce sont des problèmes de qualité, pas de disponibilité.

Cette distinction est importante pour le débogage. Si votre fallback s'épuise sur tous les providers, l'erreur levée sera celle du dernier provider tenté — ce qui vous aide à diagnostiquer le vrai problème.

Combiner fallback et autres stratégies

Neuron AI Router permet de combiner les stratégies. Par exemple, utiliser du round-robin en temps normal, et activer le fallback uniquement sur certaines routes critiques :

// Route critique : fallback ordonné
$criticalRouter = new Router(
    new Fallback([
        new OpenAI(key: $_ENV['OPENAI_API_KEY'], model: 'gpt-4o'),
        new Anthropic(key: $_ENV['ANTHROPIC_API_KEY'], model: 'claude-opus-4-5'),
    ])
);

// Route standard : round-robin pour répartir la charge
$standardRouter = new Router(
    new RoundRobin([
        new OpenAI(key: $_ENV['OPENAI_API_KEY'], model: 'gpt-4o-mini'),
        new Mistral(key: $_ENV['MISTRAL_API_KEY'], model: 'mistral-small-latest'),
    ])
);

Cette approche permet d'optimiser à la fois la résilience sur les chemins critiques et la distribution de charge sur les traitements courants.

Conclusion

Les erreurs de providers LLM en production ne sont pas une question de si, mais de quand. Implémenter un fallback robuste n'est plus une option pour des agents sérieux.

La stratégie de fallback de Neuron AI Router offre une solution élégante pour PHP : déclarative, transparente pour l'agent, et sans logique de retry à maintenir. En quelques lignes, vous passez d'un agent fragile à un agent résilient face aux aléas des APIs LLM.

Pour aller plus loin, consultez l'article original sur dev.to et la documentation officielle de Neuron AI.