Patterns de production

Les fonctionnalités les plus fortes du framework sont plus faciles à retenir sous forme de schémas d’échec. Chaque ligne ci-dessous décrit une classe réelle d’incident de production et un mécanisme concret, pas un slogan.

Échec partiel dans une opération en plusieurs étapes

Failure: la première étape réussit, la seconde échoue et l’agent ne peut pas savoir quel effet secondaire a déjà eu lieu.

Mechanism: composez le workflow en une action avec un chemin de compensation explicite. Retournez f.error() avec les actions de récupération disponibles ; ne demandez pas à un agent de deviner s’il peut réessayer sans danger. Une transaction ou une clé d’idempotence appartient à votre handler et à votre base de données.

Hallucination de paramètres

Failure: le modèle invente tenantId, emailAddress ou un autre champ plausible.

Mechanism: chaque schéma d’action est strict. Les clés inconnues sont rejetées avant le middleware et le handler, avec <validation_error> qui explique ce qui a été envoyé et ce qui était attendu. L’identité du tenant doit venir de ctx, jamais de l’entrée de l’outil.

Ruée de requêtes

Failure: de nombreux agents réessaient le même service amont lent jusqu’à épuiser les ressources de votre connecteur.

Mechanism: .concurrency({ maxActive, maxQueue }) limite le travail actif et en file. Une capacité pleine renvoie SERVER_BUSY avec des indications de nouvelle tentative. Associez-le à des délais d’expiration amont et à un limiteur de débit par tenant ou jeton.

Dépassement de la fenêtre de contexte

Failure: une réponse de collection est trop grande, le modèle perd la ligne importante et prend une mauvaise décision.

Mechanism: le Presenter .agentLimit() tronque avant la sérialisation et ajoute un résumé indiquant le nombre de lignes masquées et l’usage des filtres. .enableSelect() permet au modèle de demander uniquement les champs de premier niveau. La garde d’octets de sortie intercepte une réponse textuelle finale trop volumineuse.

Données obsolètes après une mutation

Failure: après une écriture réussie, l’agent voit une ancienne lecture dans son propre contexte.

Mechanism: marquez les lectures avec .cached() ou .stale(), et les écritures avec .invalidates('domain.pattern'). La couche de synchronisation d’état décore les descriptions, émet un marqueur d’invalidation dans le premier bloc et publie les mises à jour de ressources uniquement après une mutation réussie.

Boucles de nouvelles tentatives aveugles

Failure: un modèle répète le même appel invalide parce que l’erreur dit seulement « échec ».

Mechanism: toolError(code, { suggestion, availableActions, retryAfter }) émet un contrat XML structuré de récupération. L’action suivante est nommée, le délai est explicite et le client typé peut l’analyser en MCPFusionClientError.

Fuite de données vers le modèle

Failure: un handler renvoie une ligne de base de données contenant un champ que le modèle ne devrait jamais voir.

Mechanism: attachez un Presenter avec un schéma d’autorisation et .redactPII(). Les champs non déclarés n’entrent jamais dans la sortie validée ; la rédaction masque les chemins sensibles déclarés sur la copie clonée envoyée sur le réseau. Testez result.data avec @mcpfusion/testing.

Courses sur les opérations destructives

Failure: deux agents émettent un remboursement, font avancer un workflow ou mettent à jour le même enregistrement au même moment.

Mechanism: f.mutation() marque l’action comme destructive par défaut et le builder crée un sérialiseur FIFO des mutations par action. Ajoutez aussi l’idempotence dans la couche métier : la sérialisation ordonne les appels, mais ne rend pas une API de paiement externe idempotente.

Liste de contrôle opérationnelle

Avant Deploy :

• entrées strictes et identité du tenant issues du contexte
• Presenter sur chaque outil qui renvoie des données métier
• limites sur chaque collection
• concurrence et limites de débit sur les appels amont
• invalidation sur les écritures
• champs de récupération pour les erreurs attendues
• lockfile et tests dans CI
• télémétrie et collecteur d’audit qui ne stocke jamais de secrets bruts

Étapes suivantes

• Testing: transformez chaque ligne en test de régression
• Contracts: bloquez la dérive dans CI
• Security pipeline: consultez l’ordre d’exécution