Présentation

AgentRun est un langage de description de workflows (DSL) dédié aux agents d'IA. Distribué sous licence Apache‑2.0, il s’installe via npm install @parcha/agentrun-dsl@beta et nécessite Node 22.19+ ou supérieur. Le projet propose un interpréteur capable de chaîner des appels d’outils, des décisions basées sur le moteur Jev et des interactions avec un agent existant, le tout sans exposer les clés d’API du modèle.

Architecture et fonctionnement

Le cœur d’AgentRun repose sur un interpréteur JavaScript qui lit une définition JSON ou TypeScript du workflow. Chaque nœud possède un type (call ou judge), un label, des arguments et un délai d’exécution (deadline_s). Le nœud call invoque un outil externe (ex. help.search) et stocke le résultat dans un schéma nommé (answer). Le nœud judge applique une règle de décision Jev, évaluant la confiance d’une réponse (ex. seuil 0.8) et renvoie un état (Fit) qui détermine la suite du flux.

{
  "node": "call",
  "label": "find-answer",
  "via": "tool",
  "tool": "help.search",
  "args": { "request": "{request}" },
  "out": "Candidate",
  "as": "answer",
  "deadline_s": 10
},
{
  "node": "judge",
  "label": "check-existing-answer",
  "state": { "request": "{request}", "answer": "{answer}" },
  "out": "Fit",
  "as": "fit"
}

Le constructeur TypeScript, basé sur Zod, génère automatiquement les types d’entrée et de sortie, garantissant la cohérence à la compilation. À l’exécution, l’interpréteur valide les chemins d’état intermédiaires, empêchant les incohérences de schéma.

Intégration et utilisation

Pour intégrer AgentRun, l’application doit fournir trois adaptateurs : runEffect pour les outils, runNode pour l’agent et createJevRunner() pour les décisions. Après l’installation des paquets @parcha/agentrun-dsl et @parcha/agentrun-jev, le développeur enregistre les fonctions d’appel et lance le workflow via runWorkflow. Le README montre un scénario de support client où le workflow décide, selon la confiance, de renvoyer une réponse, de réessayer ou d’escalader vers un examen humain.

npm install @parcha/agentrun-dsl@beta
npx agentrun demo

Le démonstrateur demo:support exécute un flux complet sans clé d’API ; il imprime un tableau récapitulatif (demande, appels d’agent, décisions). Les tests automatisés (npm run test:support) valident les chemins d’escalade et les codes de sortie (ex. code 2 pour escalade).

Analyse des limites et perspectives

AgentRun impose plusieurs contraintes : la dépendance à Node 22.19+ limite l’adoption dans des environnements legacy, et le besoin d’une clé TYPESAFE_API_KEY pour les décisions Jev en temps réel ajoute une couche de configuration. Le DSL ne supporte pas encore les boucles non bornées ; les boucles sont limitées par un compteur interne, ce qui évite les blocages mais restreint les scénarios de recherche exhaustive. La validation runtime des schémas augmente la charge CPU, surtout lorsqu’un workflow comporte de nombreux nœuds de décision. Enfin, la sécurité repose sur le contrôle d’accès aux adaptateurs : une mauvaise implémentation de runEffect pourrait exposer des secrets d’API aux outils externes.

Malgré ces limites, AgentRun fournit une abstraction claire pour transformer des agents en processus réutilisables, tout en conservant la flexibilité du code JavaScript/TypeScript. Son approche type‑safe et son moteur de décision configurable offrent un cadre robuste pour les équipes cherchant à standardiser les interactions agent‑outil sans recoder chaque logique métier.