La vision

Imagine ton matin ideal : tu te reveilles, et ton organisation IA a travaille toute la nuit. Le CEO fait son briefing a la direction, le designer a produit des maquettes, l'ingenieur a corrige des bugs. Toi, tu n'as qu'a superviser.

C'est exactement ce que Paperclip AI rend possible. Pas un chatbot. Pas un assistant. Une entreprise entiere, pilotee par des agents IA.

Ce que tu vas apprendre aujourd'hui

• La difference fondamentale entre un employe IA et une entreprise IA
• Pourquoi Paperclip permet de diriger une entreprise plutot que d'utiliser un assistant
• A quoi ressemble une journee type de patron d'une organisation IA
• La feuille de route du cours sur 7 jours

Assistant IA vs Entreprise IA : la difference fondamentale

Le schema classique d'utilisation de l'IA

L'interaction typique : ouvrir ChatGPT, retrouver son prompt sauvegarde, poser une question, obtenir une reponse, fermer. Repeter pour chaque nouvelle requete.

Les utilisateurs avances deploient des assistants IA (comme OpenClaw) pour gerer les emails, coordonner le calendrier et generer du code -- fonctionnant comme des super-employes 24h/24.

Le probleme fondamental

Qu'est-ce que Paperclip AI ?

Paperclip AI est un systeme d'exploitation pour entreprise IA open-source (licence MIT, 13k+ etoiles GitHub). Ce n'est ni un chatbot, ni un framework d'assistant IA classique.

Les 6 capacites fondamentales

1. Organigramme : Definir CEO, CTO, Ingenieur, Designer avec des lignes hierarchiques
2. Alignement des objectifs : La mission cascade en projets, puis en taches ; chaque agent comprend son 'pourquoi'
3. Controle budgetaire : Limites de tokens par agent, budgets mensuels, coupe-circuit automatique
4. Heartbeat : Les agents travaillent selon un planning automatique sans intervention manuelle
5. Gouvernance : Portails d'approbation, logs d'audit complets, pause ou arret instantane
6. Isolation multi-entreprises : Plusieurs entreprises sur un seul deploiement, totalement isolees

Une journee dans la vie d'un patron Paperclip

8h00 -- Briefing matinal

L'agent CEO (Atlas) declenche son heartbeat automatiquement : il verifie la progression de tous les agents pendant la nuit, resume le statut de 3 projets, remarque qu'un ingenieur est bloque et escalade au CTO.

10h30 -- Decisions uniquement

Tu examines les 3 maquettes du Designer. Tu approuves la version B en un clic. La tache depassant le budget de l'Ingenieur te presente trois options : augmenter le budget, baisser les exigences de qualite, ou annuler. Tu ajoutes 20$ au budget ; la tache reprend automatiquement.

12h00 -- Rien a faire

Les agents travaillent de maniere autonome. Le CTO revoit le code de l'Ingenieur. Le Designer affine la maquette approuvee. Le patron part dejeuner.

21h00 -- Recap de la journee

Verification rapide du tableau de bord : 3 taches terminees, 2 en cours. Depenses du jour : 18,30$. Log d'audit : chaque action tracee. Le rapport du CEO est genere automatiquement pour demain.

Pourquoi 'maintenant' est le meilleur moment pour commencer

1. Les modeles IA sont deja assez puissants : Claude et GPT (2025) comprennent des instructions complexes, ecrivent du code de qualite production et raisonnent sur des problemes multi-etapes.
2. La couche d'orchestration est le vrai avantage : N'importe qui peut appeler une API. L'avantage competitif reside dans la collaboration multi-agents, le fonctionnement autonome, le controle des couts et l'assurance qualite.
3. Plus tu commences tot, plus ton entreprise murit : Les agents accumulent du contexte par l'execution. Les hierarchies d'objectifs, les strategies budgetaires et les workflows d'approbation s'ameliorent de maniere iterative.

Ce que tu vas construire en 7 jours

• Jour 1 (aujourd'hui) : Comprendre ce qu'est une entreprise IA
• Jour 2 : Construire un organigramme -- embaucher CTO, Ingenieur, Designer
• Jour 3 : Definir la mission, decomposer en projets et taches
• Jour 4 : Configurer budgets, limites de tokens, coupe-circuits
• Jour 5 : Activer le heartbeat -- les agents travaillent automatiquement
• Jour 6 : Mettre en place portails d'approbation et logs d'audit
• Jour 7 : Lancer un projet complet, decouvrir le CLI paperclipper

Points cles a retenir

• Assistant IA =/= entreprise IA : Un assistant accelere ton travail ; une entreprise fonctionne de maniere autonome
• Les 6 piliers de Paperclip : Organigramme + alignement objectifs + controle budget + heartbeat + gouvernance + multi-entreprises
• Tu es le patron, pas l'operateur : Les decisions t'appartiennent ; l'execution appartient aux agents
• Plus tu commences tot, plus c'est mature : Les agents et les processus s'ameliorent iterativement

Ce que tu vas apprendre aujourd'hui

• Lancer le serveur : Initialiser ton entreprise locale avec une seule commande
• Apporter tes propres employes : Les employes peuvent etre Claude, Cursor ou des scripts Docker
• Former ton equipe : Embaucher des dirigeants et etablir les lignes hierarchiques

Lancement en une commande

Pour demarrer ton entreprise IA, une seule commande suffit :

npx paperclipai onboard --yes

Le processus cree une base de donnees locale avec PGlite et configure un tableau de bord visuel. Toutes tes donnees restent locales -- rien n'est envoye dans le cloud. La migration vers un Postgres distant est supportee pour plus tard.

✓ Server port: Port 3100 is available
9 passed
All checks passed!
Starting Paperclip server...

Recruter ton premier dirigeant : le CEO

Etape 1 : Nommer ton entreprise

Dans le tableau de bord, entre un nom accrocheur pour ton entreprise.

Etape 2 : Creer ton premier agent

Cree un agent nomme CEO et selectionne un modele. Le tutoriel suggere Opus 4 comme etant le modele le plus puissant disponible.

Etape 3 : Assigner la premiere tache

Assigne une tache qui permet au CEO de creer des fichiers de metadonnees : AGENTS.md, SOUL.md, HEARTBEAT.md, TOOLS.md.

Etape 4 : Publier et approuver

Le CEO repond dans la boite de reception en demandant l'approbation d'embauche. Tu approuves.

L'organigramme : placer tes employes

Le tutoriel oppose la gestion individuelle (une personne jonglant avec 20 fenetres de chat) a la hierarchie d'entreprise. Avec Paperclip, tu delegues au CEO, qui distribue le travail vers le bas.

Configuration d'un agent

Chaque agent dispose de parametres configurables :

• Nom et titre : Ex: 'Elon' au lieu de 'CEO', avec un titre affiche sur l'organigramme
• Capacites : Ce que l'agent sait faire
• Type d'adaptateur : CLI, OpenClaw Gateway, processus spawn ou webhook HTTP
• Repertoire de travail : Utilise des chemins absolus
• Fichier d'instructions : Chemin vers le AGENTS.md de l'agent
• Modele : Assigner differents modeles pour economiser des tokens
• Boss : A qui l'agent rend compte
• Fiche de poste (JD) : Description du role

Le repertoire de chaque agent contient des fichiers modifiables :

memory/
.rw-r--r--@ 1.2k AGENTS.md
.rw-r--r--@ 2.9k HEARTBEAT.md
.rw-r--r--@ 2.6k SOUL.md
.rw-r--r--@   86 TOOLS.md

Le guide du patron

Code secret : tout effacer et recommencer

Pour reinitialiser toutes les donnees locales et repartir de zero :

rm -rf ~/.paperclip

Puis relance npx paperclipai onboard --yes.

Ce que tu vas apprendre aujourd'hui

• Le glossaire Paperclip AI : les concepts cles (Entreprise, Objectif, Projet, Agent, Issue)
• Definir la quete principale : creer des missions d'entreprise avec des objectifs en cascade
• Pourquoi l'IA arrete de derailler : comment le contexte empeche les erreurs
• L'approbation strategique du patron : soumission de strategie par le CEO et supervision du president

Le glossaire Paperclip AI

Entreprise (Company)

L'entite commerciale dans Paperclip, comparable a une 'sauvegarde'. Elle contient : un nom, un objectif ultime, la liste des employes (agents), l'organigramme et l'allocation budgetaire.

Objectif (Goal)

Il existe trois niveaux d'objectifs :

• Objectifs d'entreprise : Vision comme 'Devenir financierement independant de mon salaire grace a des projets annexes'
• Objectifs d'equipe : Cibles concretes comme 'Construire une app de prise de notes IA a 1M$ MRR'
• Objectifs d'agent : Objectifs individuels de chaque employe

Projet (Project)

Les 'quetes secondaires' qui decomposent les grands objectifs. Par exemple pour une app de prise de notes IA :

• Projet A : Developpement de l'editeur principal
• Projet B : Collaboration en temps reel
• Projet C : Strategie de croissance utilisateurs

Agent (Employe)

Les employes IA avec noms, titres, lignes hierarchiques et fiches de poste. Le choix du modele varie selon le role (CEO sur Opus, CTO sur Codex, etc.).

Issue (Tache / Ticket)

Les plus petites unites de travail. Exemples :

• Designer le protocole de messages WebSocket
• Implementer l'algorithme de resolution de conflits
• Ecrire des tests end-to-end

Statuts possibles : backlog -> todo -> in_progress -> in_review -> done

Comment tout s'emboite

Entreprise
 └── Objectif : 'App de notes IA a 1M$ MRR'
      ├── Projet A : Editeur principal
      │    ├── Issue : Architecture editeur → CTO
      │    ├── Issue : Rendu Markdown → Ingenieur
      │    └── Issue : Maquettes UI → Designer
      ├── Projet B : Collaboration temps reel
      │    ├── Issue : Protocole WebSocket → CTO
      │    └── Issue : Resolution conflits → Ingenieur
      └── Projet C : Croissance utilisateurs
           ├── Issue : Texte de lancement → CMO
           └── Issue : Landing page → Designer

Definir la condition de victoire de ton entreprise

Bons vs mauvais objectifs

Que fait le CEO apres avoir recu les ordres ?

Le CEO recoit l'objectif et cree un plan strategique :

1. Il decompose l'objectif ultime en projets
2. Il subdivise les projets en issues
3. Il soumet un memo pour approbation

L'approbation strategique : tu es le dernier verrou

Le processus d'approbation implique que le CEO soumette son plan avec la decomposition en projets, les objectifs, les priorites et le calendrier. Le president (toi) choisit : Approuver, Demander des modifications ou Rejeter.

Alignement top-down : pourquoi l'IA arrete enfin de tourner en rond

Le defaut fatal de l'IA traditionnelle

L'IA traditionnelle recoit un contexte minimal, ce qui produit des resultats 'acceptables' mais sous-optimaux. Exemple : un endpoint WebSocket cree sans comprendre les besoins de l'edition collaborative.

La solution Paperclip : le contexte voyage automatiquement

Chaque issue remonte a travers le projet jusqu'a l'objectif de l'entreprise, injectant automatiquement le contexte. L'ingenieur sait que le WebSocket est pour l'edition collaborative, comprend les exigences de faible latence et fiabilite, et pense a la gestion de files, des salles et de la reconnexion.

Comment les objectifs descendent

1. Le president definit la mission : 'Construire une app de notes IA a 1M$ MRR'
2. Le CEO redige le plan strategique : Decompose en 3 projets, soumet pour approbation
3. Le president approuve : Feu vert pour l'execution
4. Le CEO distribue vers le bas : Le CTO recoit le Produit, le CMO recoit la Croissance
5. Le CTO continue a decomposer : Les ingenieurs recoivent des taches specifiques
6. L'ingenieur commence a travailler : Contexte auto-injecte, production de haute qualite
7. Les rapports remontent : Ingenieur -> CTO -> CEO -> President (visibilite complete)

Pieges courants : les erreurs du patron debutant

• Piege 1 : Assigner les taches personnellement -- Le micro-management perturbe le rythme organisationnel ; delegue au CEO
• Piege 2 : Les objectifs vagues favorisent la creativite -- C'est l'inverse ! Les objectifs flous produisent des strategies floues et du gaspillage
• Piege 3 : L'approbation ralentit l'execution -- 5 minutes d'examen d'approbation economisent des dizaines d'heures de retouches
• Piege 4 : Plusieurs projets simultanement -- Concentre-toi sur un seul projet avant d'etendre

Pourquoi le controle budgetaire est essentiel

Le tutoriel presente le controle budgetaire comme essentiel pour la gestion des agents IA. Il met en avant la Panique Agentique (Boucles Infinies) comme un risque critique : un agent IA bloque peut declencher des appels API excessifs, coutant potentiellement des milliers d'euros pendant la nuit.

Budgets mensuels independants

Chaque agent recoit une allocation budgetaire mensuelle separee en fonction de son role. Tu as une visibilite complete des depenses par agent ou par projet. Contrairement aux limites globales de cle API, Paperclip offre un controle financier granulaire.

Les lignes de defense

Mecanismes d'application du budget

• 80% d'utilisation : declenchement d'une alerte jaune sur le tableau de bord
• 100% du seuil : mise en pause automatique de l'agent individuel
• Cycles de reinitialisation mensuels appliques automatiquement

Garde-fous d'execution

• timeoutSec : Secondes max avant kill force (0 = illimite)
• graceSec : Temps d'attente avant terminaison forcee (defaut : 15s)
• maxTurnsPerRun : Limite de conversations LLM (defaut : 300)
• maxConcurrentRuns : Executions heartbeat simultanees (defaut : 1)
• cooldownSec : Secondes min entre les executions (defaut : 10s)

Configuration via API

Etape 1 : Recuperer les IDs

L'endpoint companies retourne la structure organisationnelle avec le suivi budgetaire en centimes.

Etape 2 : Definir le budget de l'entreprise

curl -X PATCH http://localhost:3100/api/companies/{companyId}/budgets \
  -H "Content-Type: application/json" \
  -d '{"budgetMonthlyCents": 10000}'

Cela definit un budget mensuel de 100$ pour l'entreprise (10000 centimes).

Etape 3 : Assigner des budgets par agent

• CEO : 60$/mois (6000 centimes) -- utilise un modele puissant
• Ingenieur junior : 30$/mois (3000 centimes) -- utilise un modele economique
• Budget 0 = depenses illimitees (a eviter !)

Etape 4 : Rapports de couts

Trois endpoints API disponibles pour consulter les couts :

• Vue d'ensemble : resume total des depenses
• Par agent : ventilation des couts par employe
• Par projet : ventilation des couts par projet

Etape 5 : Cadre decisionnel

Quand le seuil de 80% est declenche, deux options s'offrent a toi :

• Augmenter le budget via API : l'agent reprend automatiquement
• Pause jusqu'au mois prochain : contenir les couts

Points cles a retenir

• Les plafonds budgetaires controlent les depenses totales
• Les limites d'execution empechent les spirales de couts
• Le leadership prend des decisions eclairees basees sur les rapports financiers
• Pas besoin de surveiller l'utilisation API en permanence

C'est l'heure de la pratique

Apres quatre jours de theorie, il est temps de faire tourner ton entreprise IA en completant un vrai projet : construire une landing page personnelle. L'objectif est de demontrer le pipeline complet, de la planification a la livraison.

Pourquoi une landing page ?

• Couverture complete du pipeline : Planification -> Design -> Developpement -> Livraison
• Resultats immediatement visibles : Tu peux ouvrir le fichier dans ton navigateur
• Collaboration multi-roles : Plusieurs agents travaillent ensemble
• Pieges reels lies aux lecons precedentes

Check-list avant le decollage

• Serveur Paperclip en marche (npx paperclipai onboard --yes)
• Organigramme avec CEO et Ingenieur
• Heartbeat du CEO active
• Budget adequat (10$ entreprise, 5$ par agent minimum)

Etape 1 : Assigner une mission

Cree un objectif d'entreprise avec des exigences specifiques :

• Un seul fichier HTML (pas de ressources externes, CSS inline)
• Sections requises : Hero, A propos, 3 cartes de projets, Informations de contact
• Theme sombre, design minimaliste, responsive mobile
• Emplacement de sortie specifie

Etape 2 : Le CEO decompose la strategie

Le CEO automatiquement :

1. Lit l'objectif de l'entreprise
2. Cree un Projet
3. Decompose en Issues
4. Soumet une demande d'approbation pour revue

Etape 3 : Observer le moteur Heartbeat

Declenchement manuel

• Via l'UI : Page detail de l'agent -> Bouton Run Heartbeat
• Via l'API : curl -X POST http://localhost:3100/api/agents/{agentId}/heartbeat/invoke

Le rythme Diastole-Systole

L'execution suit un schema de battement de coeur :

• Diastole : Le CEO se reveille, decouvre les Issues, les assigne
• Systole : L'Ingenieur prend le travail, execute, met a jour le statut

Configuration du heartbeat

curl -X PATCH http://localhost:3100/api/agents/{agentId} \
  -H "Content-Type: application/json" \
  -d '{
    "runtimeConfig": {
      "heartbeat": {
        "enabled": true,
        "intervalSec": 120,
        "cooldownSec": 30,
        "wakeOnDemand": true,
        "maxConcurrentRuns": 1
      }
    }
  }'

Reference des parametres heartbeat

• intervalSec : Frequence de reveil (tutoriel : 120 = 2 min)
• cooldownSec : Ecart minimum entre les executions (30)
• wakeOnDemand : Possibilite de declenchement manuel (true)
• maxConcurrentRuns : Executions paralleles (1)

Etape 4 : Inspecter le livrable

Resultats attendus :

• Toutes les Issues passees a 'done'
• Fichier index.html genere
• Le CEO envoie un resume final

open ~/day5landing_page/index.html
# Linux : xdg-open ~/day5landing_page/index.html

Etape 5 : Iterer comme un patron

Cree une nouvelle Issue pour les ameliorations (ex: polish visuel). Ne modifie pas le code directement. L'entreprise gere le cycle d'execution suivant.

• Impact visuel de la section Hero
• Harmonie et coherence de la palette de couleurs
• Elements visuels d'arriere-plan
• Hierarchie typographique
• Polish general et espacement

Retrospective : ce qui s'est reellement passe

1. Reception de l'objectif strategique (Objectif d'entreprise)
2. Decomposition autonome des taches (CEO -> Projet -> Issues)
3. Portail d'approbation de gouvernance
4. Execution auto-planifiee via heartbeat
5. Livraison d'un artefact tangible
6. Application des contraintes budgetaires
7. Iteration basee sur les retours

Correspondance avec les lecons

• Jour 1 : Entreprise IA vs Assistant -> Gestion en equipe
• Jour 2 : Organigramme -> Delegation CEO vers Ingenieur
• Jour 3 : Alignement objectifs -> Generation contextualisee de la page
• Jour 4 : Controle budgetaire -> Alertes et limites de depenses
• Jour 5 : Integration -> Execution autonome complete

Rapport de couts

Ventilation approximative d'une execution reelle :

• CEO (decomposition + 3 cycles heartbeat) : ~6,13$
• Ingenieur (generation HTML + 1 iteration) : ~1,26$
• Total : ~7,39$

Manuel d'urgence : problemes courants

• Aucune activite apres approbation : intervalSec trop eleve -> Clique sur Run Heartbeat manuellement
• Agent bloque en cours : Limite maxTurnsPerRun atteinte -> Augmente a 500
• Fichier au mauvais endroit : Objectif trop vague -> Ajoute le chemin absolu de sortie
• Page generique/moche : Objectif pas assez detaille -> Inclus des specifications de design
• Alerte budget precoce : Budget trop bas -> Augmente ou accepte le resultat actuel
• Editions concurrentes : Pas de garde d'execution -> Mets maxConcurrentRuns a 1