AIDive

Pack vidéo

pi agent toolkit : cinq paquets, recette SDK, tableau de verdicts et checklist du lundi

10 min de lecture

TL;DR

  • pi est un monorepo sous licence MIT qui livre un harnais d'agent de code en cinq paquets distincts : une couche d'API de modèles, la boucle d'agent, une bibliothèque d'interface terminal, l'agent de code lui-même et un paquet de télémétrie. Tu peux prendre une seule brique ou les cinq.
  • Le CLI est un agent de code complet dès le premier jour : quatre outils par défaut, un historique de sessions en arbre avec fork et resume, un compteur de coût en direct, et il lit l'AGENTS.md ou le CLAUDE.md déjà présent dans ton dépôt.
  • La vraie valeur est côté SDK : createAgentSession plus un runtime de modèle plus un gestionnaire de sessions donnent un agent fonctionnel en une dizaine de lignes de TypeScript, et defineTool ajoute un outil personnalisé typé sans processus séparé ni protocole.
  • Le prix de cette transparence, c'est du travail : pas de demandes de permission intégrées, l'isolation est à ta charge, une version pre-1.0 (v0.84) et environ une centaine d'issues ouvertes.
  • Garde ton harnais du quotidien, utilise pi comme banc d'essai qui montre ce que ce harnais cache. Construis des produits dessus seulement si tu acceptes de porter les garde-fous.

Ce que disent les sources

pi est un monorepo : un seul dépôt qui héberge cinq paquets publiés séparément, chacun couvrant une couche du harnais s2. pi-ai est l'API unifiée vers les fournisseurs de modèles (OpenAI, Anthropic, Google et d'autres derrière une seule interface), qui gère le streaming des réponses, les blocs de raisonnement avec leurs niveaux de réflexion et la découverte dynamique des modèles proposés par chaque fournisseur s2. pi-agent-core est la boucle d'agent elle-même : l'état de la conversation et le cycle qui envoie un message, lit les appels d'outils, les exécute et renvoie les résultats s2. pi-tui est une bibliothèque de rendu terminal avec rendu différentiel : elle ne redessine que ce qui a changé à l'écran s2. pi-coding-agent assemble ces briques dans le CLI que tu installes, et pi-telemetry te permet de brancher tes propres métriques d'usage sans dépendre d'un éditeur s3.

Les chiffres d'adoption soutiennent la conception : 92 123 étoiles, 11 400 forks et plus de 5 700 commits, le tout sous licence MIT, qui autorise l'usage, la modification et la redistribution, y compris dans un produit commercial s1. Le rythme de publication a tenu tout l'été : trois versions sur les deux premières semaines d'août, avec la v0.84.2 publiée le 14 s4.

L'installation tient en une commande, npm install -g --ignore-scripts @earendil-works/pi-coding-agent, et le flag ignore-scripts compte : il empêche les dépendances d'exécuter leurs scripts d'installation, l'une des surfaces d'attaque les plus utilisées sur npm s3. Une fois connecté à un fournisseur avec la commande login, la barre du bas affiche le dossier courant, la session, les tokens consommés et le coût en temps réel : chaque requête est chiffrée au moment où elle part, pas en fin de mois s3.

Les sessions sont la fonction distinctive. Chaque conversation est enregistrée en JSONL dans ton dossier personnel, classée par projet, et l'historique est un arbre plutôt qu'une ligne : fork revient à n'importe quel point et part sur une autre branche, tree navigue entre les branches, et resume rouvre n'importe quelle session passée, des semaines plus tard, parce que tout est stocké en local s3. Le modèle ne reçoit que quatre outils par défaut : read, write, edit et bash, très peu comparé aux agents du marché, et c'est voulu s3. La configuration suit la même logique : un settings.json global dans ton dossier personnel, un autre par projet qui le surcharge, et un système de confiance qui demande avant d'appliquer les réglages locaux d'un dossier ouvert pour la première fois. Le CLI charge aussi l'AGENTS.md ou le CLAUDE.md de ton projet comme contexte, donc tes instructions existantes fonctionnent sans réécriture s3.

Côté SDK, createAgentSession prend un ModelRuntime et un SessionManager et renvoie un agent fonctionnel. Le SessionManager est le choix de persistance : en mémoire pour un script jetable, sur disque pour retrouver tes conversations d'un lancement à l'autre, et les sessions créées par le SDK partagent la structure de celles du CLI s8. La liste d'options de createAgentSession te permet aussi de choisir l'ensemble exact d'outils exposés, et même tout le prompt système via un ResourceLoader quand tu veux partir d'une page blanche s8. Les outils personnalisés passent par defineTool : un nom, une description, un schéma de paramètres typé et une fonction execute, passés à createAgentSession dans customTools. L'outil apparaît au modèle exactement comme read ou bash, le schéma typé te donne l'autocomplétion dans l'éditeur et l'agent reçoit des entrées déjà validées. C'est le même mécanisme qu'un serveur MCP, sauf que tout vit dans ton fichier, sans processus séparé ni protocole entre les deux s8.

Le CLI lui-même se personnalise par quatre mécanismes, tous placés dans des dossiers de ton projet ou de ton dossier personnel : les extensions (des modules TypeScript qui enregistrent des outils, des commandes slash, des raccourcis clavier ou des éléments d'interface, chargés au démarrage depuis le dossier extensions), les skills (des paquets de capacités suivant le standard Agent Skills, invoqués par le modèle ou appelés à la main, donc les skills existants se réutilisent tels quels), les modèles de prompt, et les thèmes rechargés pendant que le CLI tourne s3. Le README résume la philosophie en une ligne : adapter pi à tes workflows plutôt que l'inverse, sans forker ni toucher aux internes s3. Là où les gros harnais intègrent sous-agents, mode plan et permissions dans le produit, pi les laisse de côté volontairement, à écrire sous forme d'extensions ou à installer depuis la communauté s3.

Les limites sont documentées par le projet lui-même. Il n'y a pas de demandes de permission intégrées : par défaut, l'agent peut lancer une commande bash sans demander. Le guide officiel de conteneurisation l'assume et propose trois patterns d'isolation, dont Docker, mais en mettre un en place avant de lâcher l'agent sur une machine qui compte, c'est ton travail s5. La maturité est l'autre coût : v0.84 et pas 1.0, environ une centaine d'issues ouvertes, et des API encore marquées expérimentales comme le client de session distante ajouté ces dernières semaines s7. Les mêmes briques servent déjà un autre produit : pi-chat les applique à l'automatisation de conversations s6.

Verdict : garder, essayer ou passer

Élément de pi Verdict Pourquoi
CLI comme banc d'apprentissage à côté de ton harnais du quotidien Garder Sessions locales en arbre, coût en direct, quatre outils : tu vois chaque couche qu'un harnais intégré cache
SDK (createAgentSession + defineTool) pour des produits d'agent Essayer maintenant Dix lignes pour un agent fonctionnel, des outils personnalisés typés sans plomberie MCP, fournisseur interchangeable
CLI comme seul assistant du quotidien Passer pour l'instant Pas de demandes de permission, isolation à ta charge, API pre-1.0 qui bouge
Extensions pour les garde-fous (confirmation bash, politiques) Essayer L'endroit prévu pour une couche de permissions ; versionnée avec ton projet
Dossier skills Garder Standard Agent Skills, tes skills existants se chargent tels quels
API expérimentales (client de session distante) Passer Marquées expérimentales, peuvent bouger avant la 1.0

À faire lundi

  • Installe le CLI avec npm install -g --ignore-scripts @earendil-works/pi-coding-agent, lance pi, connecte un fournisseur avec la commande login, et surveille la barre de coût pendant une vraie tâche.
  • Ouvre un dépôt qui a déjà un AGENTS.md ou un CLAUDE.md et vérifie que pi le prend en compte ; compare les premières réponses de l'agent avec ton harnais habituel sur le même prompt.
  • Mène une conversation, puis fais un fork depuis un nœud antérieur et pars dans une autre direction ; liste ~/.pi/agent/sessions/ pour voir les fichiers JSONL et leurs dossiers de projet.
  • Écris un our-agent.ts de vingt lignes : importe createAgentSession, passe un ModelRuntime et un SessionManager en mémoire, demande-lui ce que contient le dossier courant, lance-le avec npx tsx.
  • Ajoute un defineTool qui lit quelque chose dans ton propre système (une API interne, une vue de base de données, un CSV) et passe-le dans customTools ; vérifie que l'agent l'appelle de lui-même sur une question pertinente.
  • Avant tout lancement avec bash activé sur une machine à laquelle tu tiens, choisis un des trois patterns d'isolation du guide de conteneurisation et mets-le en place.
  • Rédige une première extension qui intercepte les appels bash et demande confirmation sur les commandes destructrices ; garde-la dans le dossier extensions de ton projet, sous contrôle de version.
  • Parcours une fois la liste des issues ouvertes pour savoir quelles parties bougent avant de construire dessus.

Pour aller plus loin

  • Lis la documentation du SDK pour la liste complète des options de createAgentSession : jeu d'outils, prompt système via ResourceLoader, gestionnaires de sessions s8.
  • Étudie les trois patterns d'isolation du guide de conteneurisation avant de livrer quoi que ce soit qui exécute bash sur la machine d'un utilisateur s5.
  • Regarde pi-chat pour voir comment les mêmes cinq paquets sont réarrangés pour l'automatisation de conversations plutôt que pour le code s6.
  • Parcours le dossier packages et lis pi-agent-core seul : c'est la version lisible la plus petite de la boucle que fait tourner chaque harnais intégré s2.
  • Suis la page des releases : de la v0.84.0 à la v0.84.2, tout est sorti en deux semaines d'août, donc attends-toi à des notes de changement qui touchent les extensions s4.
  • Utilise les issues ouvertes comme carte de ce qui est encore expérimental, en commençant par le client de session distante s7.
  • Réutilise les skills que tu as déjà écrits pour d'autres outils : le dossier skills de pi suit le standard Agent Skills s3.

Sources

FAQ

Est-ce que pi peut remplacer mon agent de code du quotidien dès aujourd'hui ?

Pas en remplacement direct. Il est livré sans demandes de permission, l'isolation est à ta charge, et la version est pre-1.0 avec environ une centaine d'issues ouvertes. Garde ton harnais actuel pour le travail et fais tourner pi à côté.

Ai-je besoin de MCP pour donner un outil personnalisé à pi ?

Non. defineTool prend un nom, une description, un schéma de paramètres typé et une fonction execute, et l'outil est passé à createAgentSession dans customTools. Il se comporte comme un outil intégré, sans processus séparé ni protocole.

Mes AGENTS.md, CLAUDE.md et skills existants fonctionneront-ils ?

Oui. Le CLI charge automatiquement l'AGENTS.md ou le CLAUDE.md de ton projet, et son dossier skills suit le standard Agent Skills, donc les skills existants se chargent tels quels.

Pourquoi seulement quatre outils par défaut ?

read, write, edit et bash forment tout le jeu par défaut, bien moins que les agents du marché, et le projet présente cela comme un choix. Tout le reste s'ajoute volontairement via customTools ou une extension.