L'agent IA en 12 facteurs : Construire des systèmes IA efficaces et évolutifs

Qu’est-ce qui fait un agent IA efficace ?

Avant d’entrer dans les facteurs, clarifions ce que nous entendons par « agents IA ». Fondamentalement, ce sont des systèmes capables d’interpréter des requêtes en langage naturel, de prendre des décisions basées sur le contexte et d’exécuter des actions spécifiques via des outils ou des API — tout en maintenant des interactions cohérentes et continues.

Les agents les plus puissants combinent les capacités de raisonnement des modèles de langage avec la fiabilité du code déterministe. Mais trouver cet équilibre requiert des choix de conception réfléchis, c’est précisément ce que ces facteurs adressent.

Les 12 facteurs pour construire des agents IA robustes

1. Maîtriser la conversion du langage naturel en appel d’outil

La capacité à transformer des requêtes en langage naturel en appels d’outils structurés est au cœur du fonctionnement d’un agent. C’est ce qui permet à un agent de prendre une commande simple comme « crée un lien de paiement de 750 $ pour Terri pour la rencontre des AI Tinkerers de février » et de la convertir en un appel API correctement formaté.

Image URL

{
  "function": {
    "name": "create_payment_link",
    "parameters": {
      "amount": 750,
      "customer": "cust_128934ddasf9",
      "product": "prod_8675309",
      "price": "prc_09874329fds",
      "quantity": 1,
      "memo": "Hey Jeff - see below for the payment link for the February AI Tinkerers meetup"
    }
  }
}

La clé pour que cela fonctionne de façon fiable est d’utiliser du code déterministe pour gérer la sortie structurée de votre modèle de langage. Validez toujours les charges utiles API avant exécution pour éviter les erreurs, et assurez-vous que votre LLM renvoie des formats JSON cohérents pouvant être analysés de façon fiable.

2. Prenez la pleine possession de vos prompts

Vos prompts sont l’interface entre votre application et le modèle de langage — considérez-les comme du code de première classe. Bien que les frameworks qui abstraient les prompts puissent sembler pratiques, ils masquent souvent la façon dont les instructions sont transmises au LLM, rendant l’ajustement difficile voire impossible.

À la place, gardez le contrôle direct sur vos prompts en les écrivant explicitement :

function DetermineNextStep(thread: string) -> DoneForNow | ListGitTags | DeployBackend | DeployFrontend | RequestMoreInformation {
  prompt #"
    {{ _.role("system") }}
    You are a helpful assistant that manages deployments for frontend and backend systems.
    ...
    {{ _.role("user") }}
    {{ thread }}
    What should the next step be?
  "#
}

Cette approche vous offre plusieurs avantages :

• Contrôle total pour écrire des instructions précises adaptées à votre cas d’usage
• Possibilité de construire des évaluations et des tests pour les prompts comme pour tout autre code
• Transparence pour comprendre exactement ce que reçoit le LLM
• Liberté d’itérer en fonction des métriques de performance

3. Concevez stratégiquement votre fenêtre de contexte

La fenêtre de contexte sert d’entrée au LLM, englobant prompts, historique de conversation et données externes. L’optimisation de cette fenêtre améliore la performance et l’efficacité des tokens.

Image URL

Allez au-delà des formats standard basés sur les messages vers des structures personnalisées qui maximisent la densité d’information :

<slack_message>
    From: @alex
    Channel: #deployments
    Text: Can you deploy the backend?
</slack_message>
<list_git_tags>
    intent: "list_git_tags"
</list_git_tags>
<list_git_tags_result>
    tags:
      - name: "v1.2.3"
        commit: "abc123"
        date: "2024-03-15T10:00:00Z"
</list_git_tags_result>

Cette approche offre plusieurs avantages :

• Utilisation réduite de tokens grâce à des formats compacts
• Meilleur filtrage des données sensibles avant transmission au LLM
• Flexibilité pour expérimenter des formats améliorant la compréhension du LLM

4. Implémentez les outils comme des sorties structurées

Au fond, les outils sont simplement des sorties JSON du LLM qui déclenchent des actions déterministes dans votre code. Cela crée une séparation nette entre la prise de décision de l’IA et la logique d’exécution.

Définissez clairement les schémas d’outils :

class CreateIssue {
  intent: "create_issue";
  issue: {
    title: string;
    description: string;
    team_id: string;
    assignee_id: string;
  };
}

class SearchIssues {
  intent: "search_issues";
  query: string;
  what_youre_looking_for: string;
}

Construisez ensuite une analyse fiable des sorties JSON du LLM, utilisez du code déterministe pour exécuter les actions, et réinjectez les résultats dans le contexte pour des workflows itératifs.

5. Unifiez l’exécution et l’état métier

Beaucoup de frameworks d’agents séparent l’état d’exécution (ex : étape actuelle d’un processus) de l’état métier (ex : historique des appels d’outils et leurs résultats). Cette séparation ajoute une complexité inutile.

À la place, stockez tout l’état directement dans la fenêtre de contexte, en déduisant l’état d’exécution de la séquence d’événements :

<deploy_backend>
    intent: "deploy_backend"
    tag: "v1.2.3"
    environment: "production"
</deploy_backend>
<error>
    error running deploy_backend: Failed to connect to deployment service
</error>

Cette approche unifiée offre :

• Une simplicité avec une seule source de vérité pour l’état
• Un meilleur débogage grâce à l’historique complet en un seul endroit
• Une reprise facilitée en rechargeant le fil à tout moment

Mettre les agents IA en production

6. Concevez des API pour le lancement, la pause et la reprise

Les agents de niveau production doivent s’intégrer parfaitement aux systèmes externes, pouvant se mettre en pause pour des tâches longues et reprendre lorsqu’ils sont déclenchés par des webhooks ou d’autres événements.

Implémentez des API permettant de lancer, mettre en pause et reprendre les agents, avec un stockage d’état robuste entre les opérations. Cela permet :

• Un support flexible des workflows asynchrones
• Une intégration propre avec les webhooks et autres systèmes
• Une reprise fiable après interruption sans tout redémarrer

7. Permettez la collaboration humaine via les appels d’outils

Les agents IA ont souvent besoin d’une intervention humaine pour des décisions critiques ou des situations ambiguës. L’utilisation d’appels d’outils structurés rend cette interaction fluide :

class RequestHumanInput {  
  intent: "request_human_input";  
  question: string;  
  context: string;  
  options: {  
    urgency: "low" | "medium" | "high";  
    format: "free_text" | "yes_no" | "multiple_choice";  
    choices: string[];  
  };  
}

Image URL

Cette approche permet une spécification claire du type d’interaction et de l’urgence, supporte les contributions de plusieurs utilisateurs et se combine bien avec les API pour des workflows durables.

8. Contrôlez le flux de votre agent

Un flux de contrôle personnalisé vous permet de mettre en pause pour une validation humaine, de mettre en cache les résultats ou d’implémenter un contrôle de débit — adaptant ainsi le comportement de l’agent à vos besoins spécifiques :

Image URL

async function handleNextStep(thread: Thread) {
  while (true) {
    const nextStep = await determineNextStep(threadToPrompt(thread));
    if (nextStep.intent === 'request_clarification') {
      await sendMessageToHuman(nextStep);
      await db.saveThread(thread);
      break;
    } else if (nextStep.intent === 'fetch_open_issues') {
      const issues = await linearClient.issues();
      thread.events.push({ type: 'fetch_open_issues_result', data: issues });
      continue;
    }
  }
}

Avec cette approche, vous gagnez :

• La possibilité d’interrompre pour une validation humaine avant les actions critiques
• Des options de personnalisation pour la journalisation, la mise en cache ou la synthèse
• Une gestion fiable des tâches longues

9. Compactez les erreurs dans le contexte pour l’auto-guérison

Inclure les erreurs directement dans la fenêtre de contexte permet aux agents IA d’apprendre de leurs échecs et d’ajuster leur approche :

try {
  const result = await handleNextStep(thread, nextStep);
  thread.events.push({ type: `${nextStep.intent}_result`, data: result });
} catch (e) {
  thread.events.push({ type: 'error', data: formatError(e) });
}

Pour que cela fonctionne efficacement :

• Limitez le nombre de tentatives pour éviter les boucles infinies
• Faites remonter l’erreur à un humain après plusieurs échecs
• Formatez clairement les erreurs pour que le LLM comprenne ce qui s’est passé

Bonnes pratiques architecturales

10. Construisez de petits agents spécialisés

Les petits agents qui traitent 3 à 20 étapes maintiennent des fenêtres de contexte gérables, améliorant la performance et la fiabilité du LLM. Cette approche offre :

• De la clarté avec un périmètre bien défini pour chaque agent
• Un risque réduit que l’agent perde le fil
• Des tests et validations plus simples de fonctions spécifiques

Image URL

À mesure que les LLM s’améliorent, ces petits agents pourront élargir leur périmètre tout en maintenant la qualité, assurant la scalabilité à long terme.

11. Activez les déclencheurs depuis plusieurs sources

Rendez vos agents accessibles en autorisant les déclencheurs depuis Slack, l’email ou des systèmes d’événements — en les rendant disponibles là où les utilisateurs travaillent déjà.

Implémentez des API qui lancent les agents depuis différents canaux et répondent via le même support. Cela permet :

• Une meilleure accessibilité grâce à l’intégration sur les plateformes préférées des utilisateurs
• Le support de workflows d’automatisation déclenchés par événement
• Des workflows de validation humaine pour les opérations critiques

12. Concevez les agents comme des réducteurs sans état

Traiter les agents comme des fonctions sans état qui transforment le contexte d’entrée en actions de sortie simplifie la gestion de l’état, les rendant prévisibles et plus faciles à déboguer.

Image URL

Cette approche conceptuelle considère les agents comme des fonctions pures sans état interne, offrant :

• Un comportement prévisible pour des entrées données
• Une traçabilité facilitée des problèmes via l’historique du contexte
• Des tests et validations simplifiés

Construire pour l’avenir

Le domaine des agents IA évolue rapidement, mais ces principes de base resteront pertinents même à mesure que les modèles s’améliorent. En commençant par de petits agents spécialisés respectant ces pratiques, vous créez des systèmes apportant de la valeur dès aujourd’hui tout en s’adaptant aux avancées futures.

Rappelez-vous que les agents IA les plus efficaces combinent les capacités de raisonnement des modèles de langage avec la fiabilité du code déterministe — et ces 12 facteurs vous aident à trouver cet équilibre.

Comment FlowHunt a appliqué la méthodologie des 12 facteurs

Chez FlowHunt, nous avons mis ces principes en pratique en développant notre propre agent IA qui crée automatiquement des automatisations de workflow pour nos clients. Voici comment nous avons appliqué la méthodologie des 12 facteurs pour construire un système fiable et prêt pour la production