Même à l’ère du cloud, le système de fichiers de votre ordinateur reste un outil de travail essentiel.
Les plateformes d’IA comme ChatGPT peuvent analyser les fichiers que vous leur fournissez manuellement, éventuellement se connecter à votre compte Google Drive, mais elles ne proposent pas d’outils pour naviguer dans les dossiers de votre ordinateur. Impossible non plus d’accéder à une copie locale de vos fichiers cloud (Dossier Dropbox, Google Drive for Desktop, serveurs NAS…).
Pourtant, de nombreuses entreprises utilisent ces solutions au quotidien. D’autre part, l’IA agentique permet d’envisager la création de mini-outils optimisés pour la productivité : audit de vos dossiers pour respecter des standards de qualité, identification de fichiers et dossiers manquants, création de documents personnalisés à partir de templates…
Faut-il forcément choisir entre passer sur Microsoft Sharepoint, ou se priver des gains de productivité apportés par l’IA ?
Cet article vous propose une alternative, la création de votre propre agent IA avec des technologies JavaScript : Deno et Mastra.
Nous utiliserons l’API française Mistral pour la partie IA (à ne pas confondre avec le framework Mastra !), mais ce tutoriel fonctionne aussi bien avec une IA LLM en auto-hébergement.
L’objectif : créer un agent d’analyse de fichiers, en ligne de commandes
Dans ce tutoriel, notre objectif est de créer un outil en ligne de commande, que l’on pourra appeler dans n’importe quel dossier de notre machine pour poser des questions à l’IA. Nous l’utiliserons chez LBKE pour gérer les fichiers associés à notre processus Qualiopi.
Exemple d’utilisation :
# Commande exécutée dans le dossier "/home/eric-burel/Audit Qualiopi 2026"
file-agent . "Manque-t-il des fichiers pour valider notre audit Qualiopi ?"
# Réponse de l'IA après analyse
> "Réponse de File Agent : presque, il faut récupérer les feuilles d'émargement pour la session de formation Mastra de janvier"Commençons par nos choix technologiques.
Deno et Mastra, duo de choc pour le développement d’outils CLI agentiques en JavaScript
Deno et Mastra ne sont pas les choix les plus répandus dans l’écosystème JavaScript, alors commençons donc par présenter ces deux technologies formidables dont vous ne pourrez bientôt plus vous passer.
Deno, une alternative à Node.js
Deno est un runtime JavaScript, conçu comme une alternative à Node.js. Un runtime est un programme qui peut exécuter du code JavaScript sur une machine.
Node.js est de très loin le runtime le plus connu, car en situation de quasi-monopole de 2010 jusqu’à 2020 environ. Il est très utilisé pour créer des serveurs web, car le langage JavaScript s’avère très efficace pour gérer des requêtes web avec beaucoup de communications entre systèmes comme d’autres API ou des bases de données (sur le plan technique, on parle de tâches “IO-bound”).
Deno a été créé par Ryan Dahl… qui est aussi le créateur de Node.js ! Le principe de Deno est de s’appuyer sur l’expérience acquise avec Node.js pour repartir sur des bases architecturales plus saines. Deno met par exemple beaucoup plus l’accent sur la sécurité, un avantage indéniable quand on voit les failles de sécurité qui ont encore récemment affecté l’écosystème de packages NPM (ver Shai-Hulud).
Bun est un autre runtime racheté en décembre… par Anthropic. Coïncidence ? Je ne crois pas.
J’ai choisi Deno pour ce projet car son système de compilation Deno Compile et sa librairie standard pour le CLI sont très faciles d’utilisation et apportent de bonnes garanties de sécurité.
Mastra, un framework pour l’IA agentique en JavaScript fondé sur le Vercel AI SDK
Mastra est quant à lui un framework d’IA agentique, c’est-à-dire un framework JavaScript qui permet de construire des agents autonomes et des workflows utilisant des IA génératives de type LLM, via leur API. Il utilise Vercel AI SDK pour les appels LLM bas niveau.
Mastra est un concurrent direct de l’écosystème LangChain. Nous utilisons LangChain en Python, mais nous préférons Mastra pour le développement JavaScript, car il s’agit d’une technologie créée par des développeurs web (les créateurs de Gatsby) plutôt que par des ingénieurs en machine learning. Mastra est plus intuitif pour les développeurs web et s’intègre mieux à l’écosystème JavaScript (React, Next etc.).
Si vous souhaitez utiliser un assistant de développement IA comme Cursor, n’oubliez pas d’indexer la documentation de Deno et la documentation de Mastra. Ces deux technologies évoluent très vite et un LLM mal configuré ne vous générera pas un code de qualité !
Passons à l’installation.
Installation et premier script agentique IA avec Deno et Mastra
Comme dans tout projet, la première étape est l’installation de nos outils et la création d’un premier script. Je vous fournis ici directement les éléments de code.
- Deno s’installe relativement simplement, vous trouverez plusieurs options dans la documentation de démarrage officielle
- Vous pouvez ensuite installer l’extension “Deno” de VS Code et l’activer pour votre projet
- Créez une clé Mistral via le studio IA. Mistral est une API payante, pour une offre gratuite, vous pouvez utiliser Gemini via le Google AI Studio, OpenRouter ou alors héberger votre propre modèle via Ollama.
- Mastra s’installe en tant que module NPM, il faut utiliser l’option
--npmde Deno (qui supporte aussi d’autres fournisseurs de modules comme JSR) :
deno add \
--npm typescript @types/node mastra@latest- Vous pouvez créer votre premier script TypeScript pour tester si tout fonctionne comme attendu :
// Fichier "main.ts"
import { Agent } from "@mastra/core/agent";
// Un Agent Mastra
const fileExplorerAgent = new Agent({
model: "mistral/ministral-3b-latest",
instructions: `
You are a file explorer agent.
Answer user questions about a folder.
You are provided tools to explore the folder,
list files, dive into nested folders.
`,
name: "file-explorer",
})
// La fonction principale
async function main() {
console.log("File Explorer says hi")
const msg = await fileExplorerAgent.generate([
{
role: "user", content: "Say hi"
}
])
console.log("File Explorer says:", msg.text)
process.exit(0)
}
await main()- Ce script s’exécute avec Deno, en activant l’accès à Internet et aux variables d’environnement (une mesure de sécurité qui rend Deno beaucoup moins vulnérable par défaut) :
# Fichier "./run.sh"
deno \
--allow-env=DENO_TRACE_PERMISSIONS,MASTRA_DEV,MASTRA_AUTO_REFRESH_PROVIDERS,OPENAI_BASE_URL,NODE_ENV,MISTRAL_API_KEY,MISTRAL_BASE_URL \
--allow-net \
main.tsNous avons déjà fait des progrès énormes : ces quelques lignes de code constituent les bases d’un agent IA connecté à l’API de Mistral !
Récupérer le prompt et le chemin du dossier à analyser comme arguments du CLI
Deno nous permet de connaître le dossier courant avec la commande Deno.cwd(), de calculer le chemin d’un dossier avec la librairie @std/path, et parser les arguments passés en ligne de commande via Deno.args et la librairie standard @std/cli.
En résumé, récupérer le prompt de l’utilisateur ainsi que le dossier qu’il souhaite explorer s’implémente en quelques lignes de code avec Deno !
Voici un exemple de code basique pour localiser le dossier à traiter et récupérer le prompt de l’utilisateur.
import { resolve, } from "@std/path";
function parseFolder(folder: string) {
const absoluteFolderPath = resolve(Deno.cwd(), folder)
return absoluteFolderPath
}
function parsePrompt(prompt: string) {
if (prompt.length >= 2000) {
throw new Error("Prompt length over 2000 character not yet supported for security reasons.")
}
return prompt
}
export function processArgs() {
if (Deno.args.length === 1) {
const prompt = Deno.args[0]
return { prompt }
}
if (Deno.args.length === 2) {
const folder = parseFolder(Deno.args[0])
const prompt = parsePrompt(Deno.args[1])
return { folder, prompt }
}
throw new Error("Only 2 arguments max accepted")
}Accéder aux fichiers avec un outil fourni au LLM (une fonction JavaScript)
Le prompt système est le premier ingrédient pour créer un agent IA, il explique à notre agent qu’il est en charge de répondre des questions sur les fichiers présents dans un dossier. Le prompt utilisateur fournit des informations plus détaillées sur la tâche à accomplir.
Mais pour aller plus loin, il faut donner à l’agent la possibilité d’agir, et notamment de lire nos dossiers et nos fichiers !
C’est à ça que servent les outils. Vous avez probablement déjà entendu parler du protocole MCP, devenu très populaire car il permet de transformer des APIs distantes ou des programmes en listes outils pour LLM, rendant les agents IA extrêmement puissants.
Cependant, le protocole MCP et ses implémentations ne sont pas encore très robustes en termes de sécurité. Il reste plus intéressant à ce stade d’apprendre à créer vos propres outils.
Dans Mastra, les outils se créent facilement, il s’agit simplement de fonctions JavaScript associés à quelques configurations, qui aident l’agent IA à comprendre quand et comment utiliser l’outil.
Voici un outil simple qui permet d’afficher les fichiers d’un dossier, et de naviguer dans un dossier.
export const scanFolder = (rootFolder: string) => createTool({
id: "scan-folder",
description: `Scans the content of a folder`,
execute: async function ({ runtimeContext }) {
console.log("Explorting folder")
let folderContent = await Array.fromAsync(
walk(runtimeContext.get("rootFolder"), {
followSymlinks: false,
includeDirs: true,
includeFiles: true,
maxDepth: 30
})
)
if (folderContent.length > 100) {
console.warn("More than 100 files/folders found, will generate a prompt will only the first 100 files")
folderContent = folderContent.slice(0, 100)
}
const strRepresentation = folderContent
.map(d => `${d.isDirectory ? "(D)" : "(F)"} ${d.path}`)
.join("\n")
return strRepresentation
}
})On note que notre outil est conçu pour ne pas pouvoir remonter en arrière dans les dossiers, pour empêcher l’agent de fouiller notre machine.
Compilation et essai
La commande deno compile permet de générer une une seule ligne de commande un binaire pour l’application. Il fonctionnera sur la même plateforme que celle utilisée pour la compilation (Linux Ubuntu ici), la compilation vers d’autres cibles est possible avec l’option --target.
Le binaire obtenu est relativement lourd : 314mo pour quelques dizaines de lignes de JavaScript !
Cela s’explique pour deux raisons : le binaire compilé doit d’une part intégrer une version allégée du runtime Deno (ce qui évite à l’utilisateur final d’installer Deno sur sa propre machine) et d’autre part intégrer Mastra, qui malgré son apparente simplicité intègre un puissant moteur de calcul de workflows compatible avec Inngest.
Et le résultat final : on peut poser à File Explorer n’importe quelle question sur le dossier courant !
# Commande
./file-explorer "Summarize the content of this folder"
# Réponse de l'IA :
"> File Explorer says:
- This appears to be a **TypeScript/JavaScript project**
focused on file exploration
(likely a CLI tool or library for interacting with files).
- The presence of `tools.ts` and `load-config.ts`
suggests modular design,
while `build.sh` hints at automation (e.g., for deployment or testing).
- The Git structure indicates active development,
with commits tracked in the `.git/objects` directory."
C’est la bonne réponse, File Explorer peut analyser nos fichiers !
Le code de l’agent est disponible en open source dans le dépôt GitHub lbke/deno-mastra-agentic-file-explorer.
N’hésitez pas à l’adapter pour créer vos propres agents IA en ligne de commande avec Deno et Mastra !
Pour aller plus loin
- Les agents IA peuvent toujours être frappés par des attaques par injection de prompt, qui les rendent malveillants : vos outils d’accès aux fichiers doivent être sécurisés et testés à tout prix ! Par chance, Deno fournit aussi une librairie de test unitaire intégrée au framework.
- Les appels d’API sont facturés par token, il faut donc limiter la quantité d’informations envoyée. Plusieurs approches sont possibles : implémenter les outils pour gérer les dossiers avec trop de fichiers (node_modules par exemple), mettre en place une mémoire pour que l’agent se rappelle des fichiers déjà vus sans systématiquement réanalyser tout le dossier, etc.
- Notre agent se limite à lire les noms de fichiers, mais il serait bien sûr intéressant de lui permettre de copier des fichiers, d’en créer de nouveau, et d’éditer des fichiers textes. Il n’y a pas de limites à la puissance d’un agent IA !
- Mettre en place des tests pour l’agent et du “tracing” : les agents d’IA sont non-détermistes, c’est-à-dire que leur comportement est imprévisible. Il faut les surveiller en permanence !
- Si vous avez déjà exploré l’écosystème IA agentique en JavaScript, vous pouvez vous demander pourquoi ne pas utiliser directement Vercel AI SDK pour créer notre agent. En effet, le AI SDK fournit aussi une syntaxe pour créer des outils. Le problème est que le AI SDK ne va pas jusqu’à la création d’un agent, capable d’appeler plusieurs outils pour répondre à un prompt complexe. Plus précisément, cette fonctionnalité existe mais seulement en version expérimentale, alors que les agents Mastra sont plus matures et clé-en-main.
Un grand merci à Abhi Aiyer (CTO de Mastra) pour m’avoir aidé à finaliser le code de cet article !
