Outillez votre agent : le CLI paperwork, les compétences et MCP

Quatre jours de semaine de lancement vous ont donné l’analyseur, la signature, l’audio, et hier toute l’API. Aujourd’hui, on parle de qui l’appelle. De plus en plus, ce n’est pas une personne qui tape du curl. C’est Claude Code, ou Codex, ou un agent que vous avez écrit, qui travaille dans un dossier de PDF pour quelqu’un d’autre.

Les agents sont mauvais avec les documents pour une raison bien ordinaire : un document est gros, et le contexte d’un agent est petit et coûteux. Le réflexe naïf, c’est de faire cat sur le PDF dans la conversation et d’espérer. Ça marche pour une lettre de deux pages. Ça ne marche pas pour un bail, une police d’assurance ou une liasse de mille pages, et ça envoie tout ce qui est sensible directement dans la mémoire de travail d’un modèle.

On a donc bâti l’outillage pour agents autour d’une seule idée : l’agent ne devrait jamais lire le document. Il devrait demander exactement les champs dont il a besoin, les recevoir avec des citations, et passer à autre chose. Trois couches rendent ça possible. Utilisez-en une, deux ou les trois.

Première couche : le CLI

La ligne de commande paperwork enveloppe toute l’API Paperwork. Chaque ressource est une sous-commande, la sortie est en JSON, et l’authentification se fait avec votre compte CloudRaker ou une clé d’API.

brew install cloudraker/tap/paperwork
# ou
curl -fsSL https://paperwork.sh | sh

paperwork auth login          # connexion unique par navigateur, le jeton se rafraîchit seul
paperwork files list-files --limit 1   # n’importe quel 200 veut dire que l’auth marche

Oui, on a acheté paperwork.sh pour ça. Aucun regret. Sur Windows : irm https://paperwork.sh | iex.

Sans écran, en CI ou dans un agent? Sautez le navigateur. Créez une clé sous Admin → Clés d’API et exportez-la dans PAPERWORK_TOKEN. Elle a toujours priorité sur la connexion enregistrée, et un .env dans le répertoire courant est chargé automatiquement.

Ensuite, chaque capacité est une commande. Téléversez un fichier, analysez-le, et un PDF est devenu quelque chose qu’un modèle peut lire :

FILE=$(paperwork files upload ./lease.pdf | jq -r .id)
paperwork parse parse --json "{\"file\": {\"id\": \"$FILE\"}}"

Trois options méritent leur place. La sortie est un tableau quand vous la regardez et du JSON quand vous la pipez. --query prend une expression JMESPath, pour découper une réponse sans sortir jq. Et --dry-run valide une requête localement avant que quoi que ce soit parte sur le réseau.

Deux autres existent pour le monde de l’IA. --schema fait imprimer à chaque commande un schéma JSON lisible par machine d’elle-même : de l’aide pour les humains, des schémas pour les robots, pour qu’un agent découvre toute la surface sans deviner. Et paperwork generate-skills écrit des fichiers SKILL.md à partir de cette surface, si vous voulez faire les vôtres. Vous n’en aurez probablement pas besoin, grâce à la deuxième couche.

Deuxième couche : les compétences

Le CLI dit à l’agent ce qu’il peut faire. Les compétences lui disent comment se comporter. Les documents ont des arêtes vives. Certains appels finissent en une seconde. D’autres prennent des minutes. D’autres encore s’arrêtent et attendent un humain. Un agent qui ne sait pas lequel est lequel gaspille des tours, brûle du contexte, ou relance une personne comme un bouton d’ascenseur coincé.

cloudraker-paperwork-skills, c’est notre ensemble de compétences maintenu, au format ouvert Agent Skills, donc il fonctionne dans Claude Code, Codex et tout ce qui lit ce format.

npx skills add cloudraker/cloudraker-paperwork-skills

Ou, dans Claude Code, comme plugin :

/plugin marketplace add cloudraker/cloudraker-paperwork-skills
/plugin install paperwork

Une compétence par capacité, plus une compétence parapluie qui aiguille entre elles :

• paperwork
• paperwork-parse
• paperwork-extract
• paperwork-classify
• paperwork-fill
• paperwork-redact
• paperwork-sign
• paperwork-compose
• paperwork-pipeline
• paperwork-files
• paperwork-redline
• paperwork-spaces
• paperwork-runs
• paperwork-agents
• paperwork-webhooks

Le style maison qu’elles enseignent

Ces règles ont du sens même si vous n’ouvrez jamais les fichiers.

1. Attendre pour les PDF, interroger pour tout le reste. Un PDF numérique s’analyse à l’intérieur de l’attente par défaut de 60 secondes, alors l’agent attend, tout simplement. Les scans, l’audio, les lots, les pipelines et les signatures partent avec --wait 0 et sont interrogés toutes les dix secondes. Un 202 n’est pas une erreur. C’est l’API qui dit « je travaille là-dessus ».
2. Les documents n’entrent jamais dans le contexte de l’agent. Pas de cat d’un PDF dans la conversation. Pas de transcription collée dans sa propre tête. L’agent extrait avec un schéma, ou cherche dans l’espace, et ne tire que ce dont il a besoin. Votre agent traite un contrat de mille pages sans en lire mille.
3. Un espace par tâche. Un espace est un conteneur persistant et cherchable pour les fichiers. L’agent en crée un, garde l’identifiant, et tout ce qui concerne la tâche vit là.
4. Téléverser une fois, réutiliser l’identifiant de fichier partout. Analyser une fois, exécuter souvent. La plus grosse économie de coût et de latence sur l’API, et votre facture vous dira merci.
5. Les formes répétées deviennent des configs sauvegardées. Les fichiers répétés deviennent des lots. Les tâches à plusieurs étapes deviennent des pipelines. L’agent devrait remarquer quand il fait la même chose deux fois.
6. Les humains vivent à l’échelle humaine. Quand un run a besoin d’une signature ou d’une révision, l’agent vous le dit et passe à autre chose. Il ne reste pas là à relancer une personne. On a tous travaillé avec quelqu’un qui fait ça. Ne bâtissez pas cette personne.
7. Décider garder-ou-expirer dès qu’un run se termine. runs keep-run promeut un résultat dans un espace. Tout le reste est purgé à son TTL, et rien ne s’accumule.

Troisième couche : MCP

Si votre agent parle le Model Context Protocol, ou s’il vit dans une fenêtre de clavardage et ne peut pas exécuter un shell, pointez-le vers https://mcp.cloudraker.com. On a écrit sur sa conception le mois dernier. En bref : au lieu de cinquante outils écrits à la main qui se désynchronisent, le serveur en expose exactement deux, search et execute, générés en direct à partir de la spécification OpenAPI de l’API. L’agent cherche dans la surface, génère un appel et l’exécute. Le code généré tourne dans un worker isolé sans réseau propre. Le vrai appel se fait sur l’hôte avec votre clé injectée là, donc l’identifiant n’entre jamais dans le bac à sable.

claude mcp add --transport http cloudraker https://mcp.cloudraker.com \
  --header "Authorization: Bearer $CLOUDRAKER_API_KEY"

Dans claude.ai ou Claude Desktop, ajoutez https://mcp.cloudraker.com comme connecteur personnalisé. Il découvre OAuth tout seul. Aucun jeton à copier. Neuf compétences guidées sont livrées avec le serveur comme ressources skill://, pour qu’un client de clavardage reçoive le même style maison que l’ensemble CLI donne à un agent de codage.

Il y a un deuxième serveur pour la documentation elle-même, https://docs.cloudraker.com/_mcp/server, pour qu’un agent interroge la documentation au lieu de gratter des pages. Et pour un agent qui écrit une intégration à partir de zéro, docs.cloudraker.com/developers/agents.md contient tout le contrat de l’API dans un seul fichier Markdown, assez court pour tenir en contexte.

À quoi ça ressemble

Donnez le CLI et les compétences à Claude Code, puis demandez quelque chose de vrai :

Extrais le loyer, la durée et l’échéance de lease.pdf, puis envoie le résumé au locataire pour signature.

Voici ce que fait un agent bien élevé. Il crée un espace pour la tâche. Il téléverse le bail une fois et garde l’identifiant de fichier. Il exécute extract avec un petit schéma et citations: true, lance avec --wait 0 parce qu’un scan pourrait avoir besoin d’OCR, et interroge. Il lit trois champs et la page d’où chacun vient. Il compose le résumé à partir d’un gabarit, exécute sign, et quand le run tombe sur needs_input, il vous dit qu’un humain doit signer et passe à la suite.

À aucun moment il n’a ouvert le PDF. C’est tout l’intérêt.

Pour commencer

curl -fsSL https://paperwork.sh | sh
paperwork auth login
npx skills add cloudraker/cloudraker-paperwork-skills

La référence du CLI, c’est paperwork <ressource> --help, et chaque commande répond à --schema. Les compétences sont sur GitHub, sous licence MIT. La configuration MCP et le démarrage rapide pour agents sont sur docs.cloudraker.com/developers/agents. Obtenez une clé sur signup.cloudraker.com.

Allez bâtir quelque chose. De préférence quelque chose qui remplit des formulaires, pour ne plus jamais avoir à le faire vous-même.

Semaine de lancement : Jour 1, rakedoc-nano · Jour 2, RakeSign · SOC 2 Type 2 · Jour 3, rakeaudio-asr · Jour 4, l’API Paperwork · Jour 5, les outils pour agents.