Agentspan est une couche d'exécution open source pour les agents d'IA dont le travail doit survivre aux pannes de processus, aux déploiements, aux longues attentes et aux approbations humaines. Au lieu de conserver l'intégralité de la boucle de l'agent dans la mémoire de l'application, il stocke l'état d'exécution sur un serveur Agentspan et délègue le travail des outils aux travailleurs connectés. Le projet est construit par Orkes sur le moteur de workflow Conductor et est actuellement sous licence MIT et auto-hébergé.
La distinction est importante : Agentspan ne rend pas un agent faible intelligent, ne choisit pas d'autorisations sûres ou ne valide pas un résultat commercial. Cela change le modèle d’échec. Une exécution obtient une identité durable, les étapes terminées ont un historique, l'approbation en attente peut attendre côté serveur et un travailleur de remplacement peut se reconnecter. Les équipes doivent l'évaluer en tant qu'infrastructure de systèmes distribués, et non en tant que bibliothèque d'invites.
Qu'est-ce qui change lorsque l'état quitte le processus d'agent
| Préoccupation | Boucle d'agent en cours de processus | Modèle Agentspan | L'opérateur possède toujours |
|---|---|---|---|
| Crash du processus | La mémoire et la position actuelle peuvent disparaître | Le serveur conserve l'état du flux de travail et reprend le travail | Disponibilité des travailleurs et outils idempotents |
| Approbation humaine | L'application doit conserver ou reconstruire l'état en attente | Le workflow peut s'interrompre côté serveur et recevoir une réponse plus tard | Identité de l'approbateur, délai d'expiration et politique d'escalade |
| Nouvelles tentatives | Boucle personnalisée, souvent à gros grain | La nouvelle tentative par étape est une primitive de workflow | Quelles erreurs peuvent être réessayées et si les effets secondaires sont sans danger |
| Histoire | Journaux spécifiques à l'application | Les entrées, les sorties, le timing et les étapes sont interrogeables | Rédaction, conservation et contrôles d’accès |
| Échelle | Etat et planification couplés à un seul processus | Le serveur coordonne les travailleurs et les exécutions | Capacité, location, files d'attente et reprise après sinistre |
| Planification/événements | Plomberie cron ou message séparée | Conductor planification et intégrations d'événements | Comportement de chevauchement, de déduplication et d'événements manqués |
Le chemin d'exécution, dessiné comme une limite de défaillance
utilisateur / événement
|
v
.--------------------. état durable .----------------------.
| code d'application | --------------------> | Agentspan / Conductor|
| Agent + outils | <--- task delegation ---- | run, step, history |
'--------------------' '----------+-----------'
| worker may die |
| and reconnect | calls
v v
custom tool process LLM / HTTP / MCP tools
| |
'---------------- results + side effects ---------------'
Durable checkpoint ≠ transaction over every external side effect
La dernière ligne constitue la mise en garde opérationnelle la plus importante. Un moteur de workflow peut se souvenir qu'il a demandé une mutation de paiement, d'e-mail ou de référentiel, mais il ne peut pas automatiquement rendre transactionnelle une action externe arbitraire. Si un travailleur réussit à distance et plante avant d'accuser la fin, une nouvelle tentative peut répéter l'action. Chaque outil en mutation a besoin d’une clé d’idempotence, d’une requête de réconciliation ou d’un chemin de décision humaine.
Faites le crash test avant la démo happy-path
Une preuve de concept utile tue délibérément le travailleur à différentes frontières. Exécutez une tâche de recherche en lecture seule, une tâche avec un effet secondaire contrôlé et une tâche soumise à approbation. Conservez l'ID d'exécution, redémarrez sur une autre machine, reconnectez-vous et comparez l'état final avec une exécution de contrôle ininterrompue.
| Point d'injection | Preuve attendue | Échec qui devrait bloquer le déploiement |
|---|---|---|
| Lors d'une demande de LLM | Nouvelle tentative limitée et une continuation cohérente | Dépenses illimitées en jetons ou contexte dupliqué |
| Une fois l'outil en lecture seule terminé | Reprendre sans perdre le résultat précédent | Exécuter les redémarrages depuis le début |
| Après écriture à distance, avant acquittement | La clé d'idempotence empêche un doublon | Deux tickets, paiements, messages ou commits |
| En attendant l'approbation | Le redémarrage préserve les demandes en attente et l'identité d'audit | Approbation implicite, demande perdue ou mauvais approbateur |
| Pendant le déploiement | Les anciens et les nouveaux travailleurs n'exécutent pas la même étape exclusive | Effets secondaires du cerveau divisé |
| Après le redémarrage du serveur | L’objectif de rétablissement documenté est atteint | L'historique ou l'état du flux de travail est irrécupérable |
Les tentatives nécessitent un contrat à effets secondaires
Classez les outils avant d’activer les tentatives automatiques. Les fonctions pures et les lectures répétables peuvent généralement réessayer. Les écritures nécessitent une clé d’opération stable adaptée au flux de travail et à l’étape. Les actions non répétables nécessitent un adaptateur « requête avant nouvelle tentative » ou une file d’attente de réconciliation manuelle. Ne demandez pas à un LLM de déduire si un paiement ou un message a déjà eu lieu à partir d'un contexte conversationnel.
- Réessayez en toute sécurité : calculer une somme de contrôle, lire une page publique ou interroger par ID immuable.
- Sûr sous condition : créez un ticket avec une clé d'idempotence appliquée par le serveur ou mettez à jour un enregistrement connu avec la vérification de version.
- Non sécurisé par défaut : envoyez un e-mail, publiez du contenu, transférez de l'argent ou exécutez un changement de production sans déduplication.
- Indemnisation : réserver une ressource lorsqu’une opération d’annulation testée et un chemin de remontée responsable existent.
L'approbation humaine est un système politique, pas un bouton pause
Agentspan documente les outils marqués pour approbation et les réponses CLI, API ou UI. La politique de production doit en outre définir qui peut approuver, quels arguments exacts sont gelés, comment l'identité est authentifiée, quand la demande expire et si une action modifiée crée une nouvelle approbation. Montrez à l'approbateur l'effet secondaire proposé, la destination, la divulgation des données, le coût estimé et une différence lisible par l'homme.
Séparez les demandeurs des approbateurs pour les actions à fort impact. Le refus doit mettre fin ou restreindre l’action ; cela ne doit pas inciter le modèle à contourner la porte avec un autre outil. Enregistrez la version de la politique et l'artefact d'approbation parallèlement à l'exécution afin qu'une rediffusion ne puisse pas appliquer une ancienne décision à de nouveaux arguments.
La compatibilité du framework ne signifie pas une sémantique identique
La documentation officielle présente son propre agent API et ses intégrations avec LangGraph, les agents OpenAI SDK et Google ADK. Testez l’adaptateur exact et la version que vous prévoyez de déployer. Vérifiez le streaming, l'annulation, les agents imbriqués, les ID d'appel d'outil, la sortie structurée, la propagation du contexte et le mappage des erreurs. Un wrapper peut préserver l’interface appelable tout en modifiant le comportement du point de contrôle ou de la nouvelle tentative.
| Choix d'intégration | La meilleure raison de l'utiliser | Question de validation |
|---|---|---|
| Agent Agentspan natif | Plus petite surface conceptuelle et primitives documentées | Son abstraction modèle/outil couvre-t-elle le comportement requis ? |
| LangGraph | Graphique, nœuds et conception d'état existants | Quelle couche possède les points de contrôle, les tentatives et les interruptions ? |
| OpenAI Agents SDK | Agents existants, transferts et conventions de traçage | Les événements d’outil et d’approbation sont-ils mappés sans perte ? |
| Kit ADK de Google | Implémentation d'un agent Google existant | L’état de la session et les artefacts sont-ils représentés de manière durable ? |
| Outil HTTP/OpenAPI | Appel côté serveur sans code de travail personnalisé | Où les informations d’identification, les limites de débit et les schémas de réponse sont-ils appliqués ? |
| Outil MCP | Réutiliser la surface de capacités d'un serveur MCP | Chaque méthode exposée peut-elle être délimitée et auditée indépendamment ? |
Identifiants et données d'exécution stockées
Agentspan prend en charge les clés de fournisseur via la configuration de l'environnement et les outils HTTP, OpenAPI et MCP exécutés par le serveur. L'exécution centrale peut réduire les secrets copiés sur chaque travailleur, mais elle concentre également l'autorité. Utilisez un gestionnaire de secrets, des informations d'identification de courte durée, des identités par environnement et des listes d'autorisation sortantes. Ne placez jamais d’informations d’identification dans des invites, des schémas d’outils ou des résultats persistants.
L'historique d'exécution peut contenir le texte du client, les documents récupérés, le code source, les réponses du modèle, les arguments de l'outil et les erreurs. Décidez quels champs sont rédigés avant le stockage, qui peut rechercher ou relire les exécutions, comment les locataires sont séparés et comment les demandes de suppression se propagent aux sauvegardes et aux exportations d'observabilité. Chiffrez le transport et le stockage, auditez l’accès en lecture et testez la restauration plutôt que de supposer que la persistance est égale à la récupérabilité.
Une observabilité qui mène à l’action
Les traces brutes ne sont utiles que si elles répondent à des questions opérationnelles. Attachez un ID de corrélation entre le déclencheur, le flux de travail, les appels de modèle et les mutations externes. Enregistrez le modèle/la version, la version de la politique d'invite, le nombre de jetons, la latence de l'outil, le motif de la nouvelle tentative, le délai d'approbation et la classification du terminal. Évitez les secrets à cardinalité élevée dans les étiquettes.
| Métrique | Pourquoi c'est important | Alerte suggérée |
|---|---|---|
| Des résultats commerciaux réussis | Sépare les flux de travail terminés des résultats corrects | Abandon par rapport à la référence spécifique à la tâche |
| Effets secondaires en double | Détecte l'idempotence brisée | Tout doublon confirmé pour les outils critiques |
| Nouvelles tentatives par étape | Trouve des outils instables et des coûts cachés | Augmentation soutenue par outil/version |
| Âge d'approbation | Montre le travail bloqué et la charge opérationnelle | SLA de politique passé ou expiration |
| Succès de la récupération | Mesure la promesse de durabilité fondamentale | Toute exécution éligible irrécupérable |
| Coût par résultat accepté | Combine les coûts du modèle, du calcul et du réviseur | Workflow de régression ou de contrôle |
Liste de contrôle de déploiement et de mise à niveau
- Épinglez les versions SDK, serveur et Conductor ; enregistrer la matrice de compatibilité.
- Séparez les informations d’identification, les files d’attente et les magasins de données de développement, de préparation et de production.
- Sauvegardez les métadonnées du flux de travail et testez une restauration dans un environnement isolé.
- Définissez les budgets de concurrence, de jeton, de temps, de nouvelle tentative et de récursion par agent et locataire.
- Configurez les vérifications de l'état pour les serveurs, les travailleurs, les files d'attente, les bases de données et les fournisseurs de modèles.
- Utilisez Canary Workers pour les mises à niveau et conservez les anciennes définitions de flux de travail disponibles pour les exécutions en cours.
- Définissez la sémantique d’annulation : arrêtez les travaux futurs, révoquez les informations d’identification et réconciliez les effets secondaires partiels.
- Injection rapide d’un modèle de menace, SSRF, sortie d’outils malveillants et exposition trop large à MCP/OpenAPI.
Alternatives et limite de sélection honnête
| Options | Choisissez-le quand | Compromis |
|---|---|---|
| Agentspan | Vous souhaitez des API spécifiques à l'agent sur Conductor, un auto-hébergement et des intégrations | Nouveau plan de contrôle et surface de projet évolutive |
| LangGraph persistance | Votre application est déjà profondément graphique | Vous possédez plus de choix d’orchestration de production |
| Temporel | L'organisation gère déjà des flux de travail durables à grande échelle | Les adaptateurs d'agent et le code sécurisé nécessitent une ingénierie |
| Conductor directement | Vous avez besoin de primitives de workflow générales au-delà des agents | Moins de commodité spécifique à l'agent |
| Modèles de retraitement ou DBOS | Vous souhaitez des fonctions/transactions durables proches du code de l'application | Écosystème et modèle d'intégration différents |
| Machine à états de file d'attente + base de données | Le flux de travail est petit, déterministe et stable | Nombre de dépendances le plus bas, mais la récupération personnalisée et l'interface utilisateur fonctionnent |
| Plateforme d'agents gérés | Un fonctionnement rapide compte plus que le contrôle de l’infrastructure | Contraintes du fournisseur, des données et de la personnalisation |
N'ajoutez pas un runtime durable simplement parce qu'un workflow utilise un LLM. Un assistant synchrone court sans effets secondaires peut avoir besoin uniquement de demandes de journalisation et de tentatives. Agentspan devient convaincant lorsque les exécutions sont longues, que les approbations attendent au-delà de la durée de vie d'un processus, que des événements déclenchent un travail ou que l'historique de récupération est une exigence du produit.
Un plan d'évaluation de deux semaines
La première semaine devrait établir un flux de travail de contrôle et une intégration. Sélectionnez une tâche limitée comportant trois à dix étapes, une approbation et une écriture externe réversible. Mesurez le succès et les coûts ininterrompus, puis injectez des plantages. La deuxième semaine devrait se concentrer sur les cas hostiles et opérationnels : événements en double, approbations retardées, sortie d'outil mal formée, limites de taux des fournisseurs, remplacement de travailleurs, redémarrage du serveur et mise à niveau avec une exécution en cours.
Promouvoir uniquement si un autre ingénieur peut reproduire le déploiement et la récupération à partir d'instructions écrites, si chaque outil en mutation a une politique d'effets secondaires testée, si l'historique sensible est régi et si le taux de résultats acceptés s'améliore suffisamment pour justifier la charge du serveur et des astreintes.
Questions fréquemment posées
Agentspan est-il un framework d'agent ?
Il inclut un agent API, mais son différenciateur est le runtime durable sous l'agent. Il peut également exécuter des agents créés avec des frameworks externes pris en charge.
Qu'est-ce que le moteur d'exécution ?
Le projet indique que les définitions d'agent sont compilées en flux de travail sur Conductor, qui fournit un état durable, un historique, des tentatives et des primitives de flux de travail.
Peut-il s'auto-héberger ?
Oui. Le site officiel le décrit comme étant sous licence MIT et auto-hébergable. Les opérateurs doivent toujours valider les dépendances, les magasins de données, les mises à niveau et les attentes en matière de support.
La récupération sur incident empêche-t-elle les écritures en double ?
Non. Une orchestration durable réduit les états perdus, mais les écritures externes nécessitent toujours une idempotence, une réconciliation ou une compensation.
Les approbations sont-elles automatiquement sécurisées ?
Non. Les équipes doivent définir l’authentification, l’autorisation, la liaison des arguments, l’expiration, la séparation des tâches et la conservation des audits.
Cela élimine-t-il le besoin d’un cadre d’agent ?
Non. Il peut compléter les définitions d’agents existantes. Choisissez un propriétaire clair pour l’état, les tentatives et les interruptions afin d’éviter les conflits sémantiques.
Quelle devrait être la première charge de travail de production ?
Un flux de travail limité, réversible et à faible sensibilité avec un succès mesurable et une escalade claire : pas de paiements, de modifications de production ou d'accès étendu aux données.
Sources primaires
- Site officiel Agentspan et démarrage rapide
- Documentation officielle
- Explication officielle de l'architecture et de la durabilité
- Concepts d'exécution d'agent
- Types d'outils et exécution côté serveur
- Fournisseurs de modèles et configuration pris en charge
- CLI, approbations et historique d’exécution
- Dépôt de sources officiel
- Conseils OWASP pour les risques liés aux applications LLM
Dernière révision le 25 juillet 2026. Agentspan évolue rapidement. Vérifiez la version exacte de SDK/serveur, la licence, l'adaptateur de structure et les instructions de déploiement avant de l'adopter.
