12 Factor Agents - 12 principes pour construire des applications LLM fiables

Vue d'ensemble

12 Factor Agents est une méthodologie de principes pour la construction de logiciels basés sur les LLM et prêts pour la production, développée par Dex Horthy et l'équipe HumanLayer.

Contexte et Motivation

Pourquoi ces principes sont-ils nécessaires ?

Après avoir échangé avec plus de 100 bâtisseurs de SaaS (principalement des fondateurs techniques), les auteurs ont constaté que la plupart des développements d'agents IA rencontrent un "goulot d'étranglement de qualité de 70-80%" :

1. Progrès rapide initial : Atteindre rapidement 70-80% des fonctionnalités avec les frameworks existants.
2. Goulot d'étranglement de la qualité : Constater que 80% n'est pas suffisant pour des fonctionnalités orientées client.
3. Limitations du framework : Pour dépasser 80%, il faut faire de la rétro-ingénierie sur les frameworks, les prompts, les processus, etc.
4. Recommencer à zéro : Finalement, devoir abandonner le framework et recommencer.

Idées Clés

• La plupart des "agents IA" de niveau production réussis ne sont en réalité pas si "agentiques".
• Ce sont principalement des systèmes logiciels soigneusement conçus qui utilisent intelligemment les LLM à des points clés.
• La méthode la plus rapide pour que les clients utilisent des logiciels IA de haute qualité est d'adopter des concepts petits et modulaires et de les intégrer dans les produits existants.

12 Principes Fondamentaux

Facteur 1 : Langage Naturel vers Appels d'Outils

Langage Naturel vers Appels d'Outils

La superpuissance fondamentale des LLM est de transformer le langage naturel en données structurées (JSON). Toute opération d'agent devrait commencer par cette transformation de base.

// Modèle central
const response = await llm.generateToolCall(userMessage, availableTools);
// response est un JSON structuré, pas du texte libre

Facteur 2 : Maîtrisez vos prompts

Maîtrisez vos prompts

Considérez les prompts comme des actifs de code critiques et versionnés, plutôt que comme des entrées uniques.

• Gérez les prompts dans la base de code de l'application.
• Prenez en charge les tests systématiques, le déploiement et les retours en arrière.
• Assurez la cohérence, la reproductibilité et une évolution contrôlée.

Facteur 3 : Maîtrisez votre fenêtre de contexte

Maîtrisez votre fenêtre de contexte

Gérez activement et intentionnellement la fenêtre de contexte du LLM.

• Assurez-vous que la fenêtre de contexte ne contient que les informations directement pertinentes pour la tâche actuelle.
• Éliminez les données inutiles pour éviter la "dérive de contexte".
• Améliorez les performances du LLM et réduisez l'utilisation des tokens.

Facteur 4 : Les outils ne sont que des sorties structurées

Les outils ne sont que des sorties structurées

Considérez les "outils" comme des JSON structurés issus de la sortie du LLM, et validez-les.

// Un appel d'outil n'est qu'une validation de schéma JSON
const toolCall = validateToolCall(llmOutput, toolSchema);
const result = await executeValidatedTool(toolCall);

Facteur 5 : Unifiez l'état d'exécution et l'état métier

Unifiez l'état d'exécution et l'état métier

Assurez-vous que l'"état d'exécution" interne du LLM reste cohérent avec l'"état métier" réel de l'application.

• Empêchez le LLM d'opérer sur des informations obsolètes ou incorrectes.
• Évitez les hallucinations ou les opérations invalides.
• Persistez l'état d'exécution à côté de l'état métier.

Facteur 6 : Lancer/Mettre en pause/Reprendre avec des API simples

Lancer/Mettre en pause/Reprendre avec des API simples

Concevez des agents LLM avec des interfaces de programmation claires, prenant en charge la gestion du cycle de vie.

interface AgentControl {
  launch(config: AgentConfig): Promise<AgentInstance>;
  pause(instanceId: string): Promise<void>;
  resume(instanceId: string): Promise<void>;
}

Facteur 7 : Contacter les humains via des appels d'outils

Contacter les humains via des appels d'outils

Traitez les interactions humaines comme des appels d'outils de première classe.

• Acheminez les étapes à haut risque pour examen humain.
• Le feedback humain est renvoyé au système comme une entrée structurée.
• Des flux de collaboration homme-machine fluides.

Facteur 8 : Maîtrisez votre flux de contrôle

Maîtrisez votre flux de contrôle

Maintenez le flux de contrôle dans du code ordinaire ou votre propre moteur de workflow.

• Exécutez des boucles OODA explicites (Observer-Orienter-Décider-Agir).
• Utilisez des heuristiques de convergence plutôt que des prompts imbriqués.
• Évitez de laisser le LLM gérer des flux de contrôle complexes.

Facteur 9 : Compacter les erreurs dans la fenêtre de contexte

Compacter les erreurs dans la fenêtre de contexte

Compacter les informations d'erreur dans le prompt suivant pour boucler la boucle de feedback.

• Permettre au LLM d'apprendre des erreurs et de s'en remettre.
• Fournir des informations d'erreur structurées.
• Soutenir les capacités d'auto-réparation.

Facteur 10 : Agents petits et ciblés

Agents petits et ciblés

Construisez des agents petits et à usage unique, plutôt que de grands chatbots monolithiques.

// Bonne pratique : petits agents ciblés
class EmailSummaryAgent {
  async summarize(email: Email): Promise<Summary> { /* ... */ }
}

class PriorityClassificationAgent {
  async classify(email: Email): Promise<Priority> { /* ... */ }
}

Facteur 11 : Déclencher de n'importe où, rencontrer les utilisateurs là où ils se trouvent

Déclencher de n'importe où, rencontrer les utilisateurs là où ils se trouvent

Déclenchez les agents depuis l'endroit où les utilisateurs travaillent déjà : CLI, webhook, cron, etc.

• Intégration dans les workflows existants.
• Multiples mécanismes de déclenchement.
• Points d'accès conviviaux.

Facteur 12 : Faites de votre agent un réducteur sans état

Faites de votre agent un réducteur sans état

L'application gère l'état, l'agent reste sans état.

// Modèle d'agent sans état
class StatelessAgent {
  step(state: State): Promise<State> {
 
  }
}

Modèles d'Architecture Technique

Simplification de la Boucle Centrale

Chaque agent se résume essentiellement à :

const prompt = "Instructions for next step selection";
const switchFunction = (json) => routeToFunction(json);
const context = manageWhatLLMSees();
const loop = whileNotDone();

Distinction avec les DAG traditionnels

• DAG traditionnel : L'ingénieur logiciel code chaque étape et chaque cas limite.
• Approche Agent : Donner à l'agent un objectif et un ensemble de transformations, et laisser le LLM décider du chemin en temps réel.
• Réalité : Les implémentations les plus réussies utilisent intelligemment le modèle d'agent au sein d'un DAG déterministe plus large.

Scénarios d'Application

Scénarios les mieux adaptés

• Tâches structurées nécessitant la compréhension du langage naturel.
• Workflows nécessitant une collaboration homme-machine.
• Processus métier complexes en plusieurs étapes.
• Environnements de production nécessitant une haute fiabilité.

Scénarios non adaptés

• Tâches déterministes simples (il est préférable d'écrire directement du code).
• Tâches critiques nécessitant une précision de 100%.
• Environnements avec des ressources extrêmement limitées.

Recommandations d'Implémentation

Adoption Progressive

1. Commencez petit : Choisissez un principe pertinent pour votre défi actuel.
2. Implémentez et observez : Constater les effets de l'amélioration.
3. Ajoutez progressivement : Puis ajoutez un autre principe.
4. Optimisez continuellement : Affinez et ajustez constamment.

Pile Technologique Recommandée

• Langage : TypeScript (recommandé par les auteurs, mais d'autres langages comme Python sont également pris en charge).
• Bibliothèque clé : BAML (pour l'analyse d'alignement de schéma).
• Déploiement : Prend en charge le cloud-native et Kubernetes.

Ressources Associées

Ressources Officielles

• Dépôt GitHub
• Site officiel HumanLayer
• Blog The Outer Loop

Lectures Complémentaires

• Building Effective Agents (Anthropic)
• Méthodologie originale des 12 Factor Apps
• Function Calling vs Structured Outputs vs JSON Mode

Résumé

12 Factor Agents offre une approche systématique pour construire des applications LLM véritablement prêtes pour la production. Il ne s'agit pas de créer des frameworks plus magiques, mais d'appliquer de meilleures pratiques d'ingénierie logicielle aux capacités des LLM. Retenez le concept central : Les agents sont des logiciels ; traitez-les comme tels, et ils vous récompenseront par leur fiabilité, leur maintenabilité et des capacités que vos concurrents ne pourront égaler.