La plupart des développeurs qui exécutent plusieurs agents IA se heurtent au même mur autour du cinquième agent. Vous avez Claude Code dans un terminal qui réécrit un service backend, Codex dans un autre qui génère des tests, Cursor qui édite un composant, et trois autres onglets que vous avez oublié de vérifier. Personne ne sait ce que fait l'autre. Les coûts s'envolent. Deux agents dupliquent le même travail. L'un tourne pendant six heures et ne produit rien d'utile parce que personne ne lui a donné d'objectif clair.
{% cta https://apidog.com/?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation %} Essayez Apidog dès aujourd'hui {% endcta %}
Paperclip résout ce problème. C'est une plateforme d'orchestration open-source qui transforme vos agents IA dispersés en une entreprise structurée, avec des organigrammes, des rôles assignés, la gestion des tâches, des limites budgétaires et des journaux d'audit. Elle a atteint plus de 35 000 étoiles GitHub en moins de trois semaines, ce qui montre combien de développeurs partageaient la même frustration.
Cet article vous guide à travers sa configuration, la structuration de votre première entreprise d'agents, et son exécution afin que le travail soit réellement fait sans que vous ayez à surveiller chaque terminal.
## Ce qu'est Paperclip (et ce qu'il n'est pas)
Avant d'installer quoi que ce soit, comprenez ce que vous obtenez.
[Paperclip](https://github.com/paperclipai/paperclip) est une **couche d'orchestration**. Il coordonne les agents, suit leur travail, contrôle leurs budgets et leur donne le contexte des objectifs de l'entreprise. Il ne construit pas d'agents, ne remplace pas votre fournisseur d'IA et n'ajoute pas d'interface de chat.
Le modèle mental utilisé par l'équipe Paperclip : « Si Claude Code est un employé, Paperclip est l'entreprise. »
Cela signifie que :
- Les agents ont des **rôles**, pas seulement des invites
- Les tâches ont des **propriétaires**, pas seulement des terminaux ouverts
- Les budgets ont des **limites strictes**, pas seulement des estimations
- Tout est enregistré dans un **journal d'audit**
Paperclip fonctionne avec Claude Code, OpenAI Codex, Cursor, Gemini CLI, et tout agent pouvant recevoir un webhook ou un signal de battement de cœur. Vous apportez les agents. Paperclip gère l'entreprise.
Il n'est explicitement pas :
- Une interface utilisateur de chatbot
- Un constructeur de flux de travail par glisser-déposer comme n8n ou Zapier
- Un framework pour écrire des agents
- Utile pour les cas d'utilisation d'un seul agent
Si vous exécutez un seul agent IA occasionnellement, Paperclip est excessif. Si vous exécutez trois agents ou plus sur des tâches continues, c'est la pièce manquante.
## Installation de Paperclip
Pré-requis : Node.js 20+, pnpm 9.15+. Paperclip inclut une base de données PostgreSQL intégrée, vous n'avez donc pas besoin de configurer un stockage externe.
**Le moyen le plus rapide de démarrer :**
bash
npx paperclipai onboard --yes
Cela télécharge la CLI, effectue l'intégration avec des paramètres par défaut, et démarre le serveur sur le port 3100. Ouvrez `http://127.0.0.1:3100` pour accéder au tableau de bord.
**Pour contribuer ou examiner le code :**
bash
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev
**Via Docker :**
bash
docker compose -f docker-compose.quickstart.yml up --build
**Structure sur le disque :**
Paperclip stocke tout sous `~/.paperclip/instances/default/` :
plaintext
~/.paperclip/instances/default/
config.json — paramètres du serveur et du stockage
db/ — fichiers de données PostgreSQL intégrés
secrets/master.key — clé de chiffrement (auto-générée)
logs/ — journaux du serveur
data/storage/ — pièces jointes
workspaces// — répertoires de travail par agent
Le mode local utilise l'authentification `local_trusted` par défaut, ce qui ignore la connexion et utilise un utilisateur "Board" synthétique. Vous pouvez commencer à utiliser le tableau de bord immédiatement, aucune création de compte n'est nécessaire.
Une fois connecté, exécutez le contrôle de santé :
console
paperclipai doctor
Si quelque chose est mal configuré, `--repair` corrige la plupart des problèmes automatiquement :
console
paperclipai doctor --repair
## Configuration de votre première entreprise
Dans Paperclip, une « entreprise » est le conteneur de haut niveau pour vos agents, tâches, objectifs et budgets. Pensez-y comme à un projet, mais chaque membre du projet est un agent IA avec un rôle et une ligne hiérarchique.
Depuis le tableau de bord, créez une nouvelle entreprise et donnez-lui une déclaration de mission. Ce n'est pas décoratif. Chaque tâche qu'un agent reçoit est liée à la mission de l'entreprise, donnant du contexte à *pourquoi* le travail doit être fait, et pas seulement à *ce qu'il faut faire*. Ce contexte est crucial pour les exécutions agentiques longues.
Exemple de mission :
« Construire et maintenir une API REST pour la gestion des commandes clients. Prioriser la justesse plutôt que la vitesse. Documenter chaque point d'accès public. »
Cette seule déclaration donne à vos agents un filtre pour chaque décision qu'ils prennent.
## Ajouter vos premiers agents
Chaque agent dans Paperclip dispose d'un **adaptateur** qui définit l'outil d'IA qu'il utilise et sa méthode de communication.
Adaptateurs pris en charge nativement :
| Agent | Type d'adaptateur | Paquet |
|-----------------|-----------------------|---------------------------------|
| Claude Code | `claude_local` | `@paperclipai/adapter-claude-local` |
| OpenAI Codex | `codex_local` | `@paperclipai/adapter-codex-local` |
| Gemini CLI | `gemini_local` | `@paperclipai/adapter-gemini-local` |
| Cursor | `cursor` | `@paperclipai/adapter-cursor-local` |
| Webhooks HTTP | Adaptateur HTTP | point de terminaison personnalisé |
Pour ajouter un agent Claude Code via la CLI :
console
paperclipai agent local-cli "Backend Engineer" --company-id
Ceci initialise l'agent, installe ses compétences dans `~/.claude/skills`, et génère les identifiants d'API. L'agent apparaît dans l'organigramme de votre entreprise et peut recevoir des tâches.
**Configuration d'un agent Claude** (par l'UI ou dans la configuration par agent) :
| Champ | Ce qu'il fait |
|---------------------|-----------------------------------------------------------|
| `model` | Modèle Claude utilisé (ex: `claude-sonnet-4-6`) |
| `cwd` | Répertoire de travail de l'agent |
| `promptTemplate` | Invite système avec substitution de `{{variable}}` |
| `maxTurnsPerRun` | Nombre max de tours agentiques par battement de cœur (défaut : 300) |
| `timeoutSec` | Limite d'exécution stricte (0 = pas de délai) |
**Répartition des modèles par rôle** :
- **PDG / orchestration** : Sonnet (raisonnement stratégique)
- **Managers** : Haiku (routage, délégation, rapide)
- **Créatifs / codeurs** : Sonnet (qualité de la production)
- **Génériques** : Haiku (boilerplate, échafaudage, migrations)
Cette allocation réduit généralement les coûts de 40 à 60 % par rapport à Sonnet partout, sans perte de qualité pour les tâches de routine.
## Structurer votre organisation d'agents
Exemple pour un petit projet logiciel :
plaintext
PDG (Sonnet)
├── CTO (Haiku)
│ ├── Ingénieur Backend (Sonnet)
│ ├── Ingénieur Frontend (Sonnet)
│ └── Ingénieur QA (Haiku)
└── Rédacteur Technique (Haiku)
Le PDG détient la mission et la divise en objectifs. Le CTO achemine les objectifs. Les ingénieurs exécutent. Le QA valide. Le rédacteur documente.
Chaque agent a un **intervalle de battement de cœur** : fréquence à laquelle il se réveille, traite ses tâches puis se met en veille. Cela limite les coûts.
**Intervalles recommandés :**
- Agents de codage : 600 sec (10 min)
- Agents à la demande : 86 400 sec (1/jour) + réveil à la demande
- Intervalle minimum sécurité : 30 sec (évitez en dessous)
## Comment fonctionne le battement de cœur
À chaque réveil, un agent suit ce protocole :
1. Confirmer l'identité via `GET /api/agents/me`
2. Gérer les rappels d'approbation en attente
3. Récupérer les tâches via `GET /api/companies/{companyId}/issues`
4. Prioriser : tâches en cours, puis à faire. Ignorer les tâches bloquées sauf si débloquables.
5. Extraire la tâche via `POST /api/issues/{issueId}/checkout` (si déjà prise : 409)
6. Lire le contexte complet et les commentaires
7. Faire le travail
8. Mettre à jour la tâche avec commentaires et statuts
9. Déléguer des sous-tâches si besoin
Le "checkout" à l'étape 5 évite la duplication : un seul agent par tâche.
Paperclip injecte dans chaque exécution :
shell
PAPERCLIP_TASK_ID # tâche déclenchante
PAPERCLIP_WAKE_REASON # raison du réveil (minuterie, mention, assignation)
PAPERCLIP_AGENT_ID # identité de l'agent
PAPERCLIP_API_URL # URL de l'API Paperclip
Utilisez-les pour publier des mises à jour, créer des sous-tâches, demander des approbations, déléguer.
## Assigner des tâches et suivre le travail
Créez une tâche dans la CLI :
console
paperclipai issue create \
--company-id \
--title "Add pagination to the orders endpoint" \
--assignee-agent-id
Les tâches peuvent avoir :
- **Tâches parentes** (découpage)
- **Liens d'objectifs** (rattachement à la mission)
- **Commentaires** (contexte, approbations, statut)
- **@-mentions** (réveil immédiat d'un agent)
Lister les tâches ouvertes :
console
paperclipai issue list
Ou utilisez le tableau de bord pour visualiser propriétaire, statut, dernière exécution.
## Contrôle budgétaire qui fonctionne vraiment
Chaque agent a un budget mensuel de jetons. À 80 %, il se concentre sur les tâches critiques. À 100 %, il se met en pause.
Définissez le budget dans la config de l'agent (20–50 $/mois/agent recommandé). Suivez l'utilisation, le coût par battement de cœur et les dépenses cumulées dans le tableau de bord.
Si le coût par battement de cœur augmente, peaufinez l'affectation (instructions plus précises), pas le budget.
Sans contrôle, un agent mal configuré à 30 sec d'intervalle peut brûler des centaines de dollars rapidement. Paperclip prévient ça automatiquement.
## Compétences d'exécution : enseigner de nouveaux flux de travail
Paperclip permet **l'injection de compétences** : l'adaptateur crée des liens symboliques vers des fichiers `SKILL.md` dans le répertoire de l'agent, transmis via `--add-dir`. L'agent lit le markdown et suit le workflow, sans réécriture d'invite ni redéploiement.
Exemple de compétence :
markdown
COMPÉTENCE : Migrations de bases de données
Lors de la création d'une migration :
- Ne jamais modifier les fichiers de migration existants
- Utiliser des noms descriptifs : AAAAJJMM_description.sql
- Inclure le SQL pour la montée et la descente
- Tester localement avant de commettre
- Ajouter un commentaire expliquant la raison métier du changement
Enregistrez dans le répertoire des compétences, assignez à l'agent backend, et toute exécution future suivra ce processus.
## Si vous testez des API construites par vos agents
Lorsque vos agents construisent des API, testez-les rapidement avec [Apidog](https://apidog.com/?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation). Apidog gère la conception d'API, les serveurs de maquette et les tests automatisés, ce qui permet de valider immédiatement un endpoint livré par un agent backend, sans jongler entre Swagger, Postman et des outils séparés.
Générez automatiquement des suites de tests à partir d'une spécification OpenAPI, exécutez-les, et renvoyez les résultats en commentaire de tâche. L'agent les lira au prochain battement de cœur et corrigera les échecs, automatisant toute la boucle code → test → correction.
Apidog prend en charge REST, GraphQL et gRPC, et il est gratuit pour commencer.
## Gestion de plusieurs instances
Paperclip supporte plusieurs instances isolées sur une machine via `PAPERCLIP_INSTANCE_ID` ou `--instance`. Chaque instance a sa propre config, base, ports et workspace.
Pour le développement local, créez une instance isolée par branche git :
console
paperclipai worktree:make feature/orders-pagination
Cela génère ports, config et base séparés. Vous pouvez tester une entreprise sur une branche de fonctionnalité sans toucher à la prod. Supprimez-la quand vous avez fini.
## Configurations multi-agents qui fonctionnent
Quelques modèles éprouvés :
- **Cascade d'objectifs** : un objectif top-niveau, que le PDG décompose, puis chaque manager décompose en tâches. Les chaînes de buts sont plus efficaces que des instructions isolées.
- **Gates d'approbation** : pour tout ce qui touche la prod/staging/facturation, ajoutez une étape d'approbation. L'agent attend un feu vert manuel, ce qui évite les erreurs coûteuses.
- **Réveil à la demande via @-mention** : privilégiez des intervalles lents et réveillez les agents immédiatement via @-mention quand c'est nécessaire, évitant ainsi le polling coûteux.
- **Workspace isolé** : chaque agent a son dossier sous `workspaces/<agent-id>/`. Gardez-les séparés pour éviter les collisions.
## Le démarrage prend environ 15 minutes
L'intégration initiale prend moins de 15 minutes. Une commande pour installer et démarrer le serveur. Ajouter un agent et créer une tâche prend cinq minutes via le tableau de bord.
Le plus important est de bien structurer votre entreprise : mission claire, bons modèles par rôle, budgets raisonnables. Consacrez 30 minutes à la structure avant d'assigner du travail pour des résultats bien meilleurs.
Si vous utilisez déjà plus de deux agents IA sur un projet, prenez un après-midi pour la configuration. Passer d'un terminal par agent à une entreprise structurée avec contrôles budgétaires, propriété des tâches et journaux d'audit, c'est la différence entre un projet secondaire et une solution scalable sans supervision.
Top comments (0)