Notion Workers : exécuter du code pour vos agents

Notion Workers est un environnement d’exécution TypeScript qui permet d’écrire et de déployer du code personnalisé pour vos Custom Agents. Concrètement, vous donnez à vos agents de nouvelles capacités : appeler une API externe, synchroniser un CRM, envoyer des alertes Slack, le tout en quelques lignes de code que Notion héberge et exécute pour vous. Avec 100 millions d’utilisateurs en 2026, l’écosystème Notion avait besoin de cette brique technique.

Lancé en alpha en mars 2026 en partenariat avec Vercel, Workers comble un manque important : jusqu’ici, les Custom Agents étaient limités aux intégrations prédéfinies (Slack, Mail, Calendar) et aux connexions MCP. J’ai testé Workers dès l’ouverture de l’alpha, et le constat est clair : tout développeur peut créer des outils sur mesure sans gérer d’infrastructure. Chaque exécution tourne dans une microVM Firecracker isolée, avec un modèle de sécurité qui empêche toute exfiltration de données sensibles.

Qu’est-ce que Notion Workers ?

Notion Workers est une plateforme d’exécution de code côté serveur, intégrée à l’écosystème Notion. Un Worker est un petit programme TypeScript que vous écrivez, déployez via un CLI dédié (ntn), et que Notion exécute automatiquement dans le cloud.

Workers propose deux types de capacités :

La distinction est simple. Un Tool donne à votre agent un nouveau verbe d’action. Un Sync alimente automatiquement vos bases Notion avec des données externes, sans intervention manuelle.

Si vous connaissez déjà les automations Notion, Workers en est le prolongement technique. Là où une automation exécute une action simple (modifier une propriété, envoyer une notification), un Worker peut contenir de la logique métier arbitraire : conditions complexes, transformations de données, appels API chaînés.

Prérequis et installation

Workers est actuellement en phase alpha. Pour l’utiliser, vous devez remplir trois conditions :

• Un workspace Notion Business ou Enterprise avec les Custom Agents activés
• Un administrateur workspace qui a opté pour l’accès alpha
• Node.js installé sur votre machine de développement

L’installation du CLI se fait en une commande :

npm i -g ntn

Pour créer votre premier projet Worker :

ntn workers new
cd my-worker

Cette commande génère un projet TypeScript prêt à l’emploi avec un fichier src/index.ts, un package.json préconfiguré, et la dépendance @notionhq/workers installée.

Créer un Tool : donner un nouveau pouvoir à votre agent

Un Tool est une fonction que votre Custom Agent peut appeler à la demande. Voici un exemple de Tool qui salue un utilisateur :

import { Worker } from "@notionhq/workers";
import { j } from "@notionhq/workers/schema-builder";

const worker = new Worker();
export default worker;

worker.tool("sayHello", {
  title: "Say Hello",
  description: "Returns a friendly greeting for the given name.",
  schema: j.object({
    name: j.string().describe("The name to greet."),
  }),
  execute: ({ name }) => `Hello, ${name}!`,
});

La structure est claire : vous déclarez un nom, une description (que l’agent lit pour comprendre quand utiliser l’outil), un schéma de paramètres typé, et une fonction execute. Le schema builder j offre une validation automatique avec inférence de types TypeScript.

Cas d’usage concrets pour les Tools

En pratique, j’ai identifié quatre types de Tools qui reviennent souvent :

• Alertes d’erreurs : un Tool qui interroge l’API Sentry et crée un ticket dans une base Notion quand le taux d’erreurs dépasse un seuil
• Communication Slack : un Tool qui formate et envoie un résumé hebdomadaire dans un canal Slack à partir de données Notion
• Vérification de stock : un Tool qui appelle l’API d’un fournisseur et met à jour les quantités dans une base produits
• Envoi de SMS : un Tool qui utilise l’API Twilio pour notifier un client quand sa commande change de statut

Chaque Tool que vous créez étend le vocabulaire de votre agent. Plus vos Tools sont spécifiques et bien documentés (via la description et le schéma), plus l’agent les utilise de manière pertinente.

Créer un Sync : alimenter vos bases Notion automatiquement

Un Sync est un job planifié qui importe des données externes dans une base Notion. Contrairement à un Tool (déclenché par l’agent), un Sync tourne à intervalles réguliers, indépendamment de toute interaction.

Voici un exemple simplifié de Sync qui importe des issues :

const issues = worker.database("issues", {
  type: "managed",
  initialTitle: "Issues",
  primaryKeyProperty: "Issue ID",
  schema: {
    properties: {
      Title: Schema.title(),
      "Issue ID": Schema.richText(),
    },
  },
});

worker.sync("issuesSync", {
  database: issues,
  execute: async () => {
    const items = await fetchIssues();
    return {
      changes: items.map((issue) => ({
        type: "upsert" as const,
        key: issue.id,
        properties: {
          Title: Builder.title(issue.title),
          "Issue ID": Builder.richText(issue.id),
        },
      })),
      hasMore: false,
    };
  },
});

Le Sync déclare d’abord une base de données avec son schéma, puis une fonction execute qui retourne les changements à appliquer. Notion gère automatiquement la création de la base, l’upsert des enregistrements et la suppression des entrées obsolètes.

Modes de synchronisation

Workers propose deux modes de synchronisation :

La fréquence de synchronisation se configure entre 1 minute et 7 jours, avec une valeur par défaut de 30 minutes. Le mode continuous est également disponible pour les cas nécessitant une quasi-temps réel, ainsi que le mode manual pour les déclenchements à la demande via ntn workers sync trigger.

Relations entre bases de données

Workers gère les relations entre bases synchronisées. Si vous synchronisez des projets et des tâches, vous pouvez établir une relation bidirectionnelle :

Project: Schema.relation("projectsSync", {
  twoWay: true,
  relatedPropertyName: "Tasks",
})

Notion crée automatiquement les propriétés de relation dans les deux bases, comme vous le feriez manuellement dans l’interface.

Architecture technique : Vercel Sandbox et microVM

L’infrastructure qui fait tourner les Workers repose sur Vercel Sandbox, un service d’exécution de code conçu spécifiquement pour les charges de travail non fiables. Chaque Worker s’exécute dans une microVM Firecracker éphémère.

Isolation par microVM Firecracker

Firecracker est la technologie de virtualisation développée par Amazon pour AWS Lambda. Chaque microVM démarre son propre noyau Linux, avec un système de fichiers dédié et une pile réseau isolée. Cette isolation est plus forte que celle offerte par les conteneurs Docker classiques, car elle opère au niveau du noyau et non du processus.

En chiffres, Vercel Sandbox offre :

• Démarrage en moins de 125 ms grâce au système de snapshots (spécification Firecracker)
• Jusqu’à 32 vCPU et 64 Go de RAM sur les plans Enterprise
• Runtimes supportés : Node.js 24, Node.js 22, Python 3.13
• Durée maximale d’exécution : 5 heures (plans Pro et Enterprise)

Système de snapshots

Pour éviter de réinstaller les dépendances à chaque exécution, Workers utilise le système de snapshots de Vercel Sandbox. Les dépendances sont installées une première fois, l’état du système de fichiers est capturé, et les exécutions suivantes reprennent à partir de ce snapshot. Le résultat : des temps de démarrage à froid réduits de plusieurs secondes à quelques millisecondes.

Les snapshots expirent après 30 jours par défaut. Cette durée est configurable selon vos besoins.

Sécurité : un modèle zéro confiance

Chaque Worker s’exécute dans une microVM isolée, détruite après chaque exécution.

La sécurité est le point que j’ai le plus scruté. Chaque Worker exécute du code tiers au nom d’un utilisateur Notion, potentiellement dans un workspace d’entreprise. Plus de 50 % des entreprises Fortune 500 utilisent Notion : la sécurité n’est pas optionnelle. Le modèle de sécurité repose sur trois piliers.

Injection de credentials au niveau réseau

Les clés API et tokens d’authentification ne sont jamais exposés au code du Worker. Le proxy réseau de Vercel Sandbox intercepte les requêtes sortantes et injecte les credentials au moment de la transmission. Même si le code est compromis, il ne peut pas lire ni exfiltrer les secrets.

C’est une vraie différence avec l’approche classique (variables d’environnement accessibles au code). Ici, le code utilise les credentials sans jamais y avoir accès.

Politiques réseau dynamiques

Vercel Sandbox supporte des politiques réseau qui évoluent pendant l’exécution, sans redémarrage. Le workflow type est le suivant :

1. Phase d’installation : accès internet ouvert pour télécharger les dépendances npm
2. Phase d’exécution : egress verrouillé aux seuls domaines autorisés
3. Phase de nettoyage : la microVM est détruite

Cette approche en phases élimine le risque qu’un code malveillant communique avec des serveurs non autorisés pendant l’exécution.

Destruction de la VM après exécution

Chaque microVM est éphémère. À la fin de l’exécution, la VM est détruite (ou son snapshot est mis à jour). Aucune donnée ne persiste entre deux exécutions, sauf l’état explicitement sauvegardé via le mécanisme de snapshots.

Workers vs Custom Skills vs Automations

Automations pour tous, Custom Skills pour les avancés, Workers pour les développeurs.

Notion propose désormais trois niveaux d’automatisation. Voici comment les positionner :

Si vous êtes développeur et que vos besoins dépassent ce que les Custom Skills et les connecteurs MCP offrent, Workers est la réponse. Pour les non-développeurs, les automations et les Custom Agents en langage naturel restent les options recommandées. Si vous découvrez l’IA dans Notion, commencez par notre guide Notion IA.

Déploiement et cycle de vie

Le workflow de déploiement d’un Worker suit un cycle classique pour les développeurs :

# Créer un nouveau Worker
ntn workers new

# Développer et tester localement
# (éditer src/index.ts)

# Déployer vers Notion
ntn workers deploy

# Surveiller les syncs
ntn workers sync status

# Déclencher un sync manuellement
ntn workers sync trigger

Après déploiement, vos Tools apparaissent automatiquement dans la liste des outils disponibles pour vos Custom Agents. Vous n’avez pas besoin de configurer manuellement la connexion : Notion détecte les Tools déclarés dans votre Worker et les rend accessibles.

Pour les Syncs, la commande ntn workers sync status fournit un tableau de bord en temps réel avec l’état de chaque synchronisation, la dernière exécution, et les éventuelles erreurs.

Cas d’usage avancés

Synchronisation CRM bidirectionnelle

Un Worker Sync peut importer les contacts et opportunités depuis HubSpot, Salesforce ou Attio dans une base Notion, toutes les 5 minutes. Combiné avec un Worker Tool, un Custom Agent peut ensuite mettre à jour le CRM depuis Notion quand un commercial change le statut d’une opportunité. Si vous utilisez déjà l’intégration Notion Salesforce, Workers permet d’aller au-delà des champs prédéfinis.

Système d’alertes intelligent

Un Worker Tool interroge l’API de monitoring (Datadog, Sentry, PagerDuty) et crée des pages dans une base Notion “Incidents” avec la sévérité, le service impacté et les logs pertinents. Un Custom Agent peut ensuite analyser les tendances et générer un rapport hebdomadaire.

Pipeline de contenu automatisé

Un Worker Sync importe les derniers articles d’un flux RSS ou d’une API de veille. Un Custom Agent les analyse, les classe par pertinence, et rédige un résumé dans une page Notion dédiée. L’ensemble tourne sans intervention humaine.

Tarification et coûts

La tarification de Workers combine deux composantes :

Côté Notion : l’exécution des Custom Agents qui appellent vos Workers consomme des Notion Credits. À partir du 4 mai 2026, le tarif est de 10 dollars pour 1 000 crédits, avec une consommation de 11 à 22 crédits par exécution d’agent selon la complexité de la tâche (centre d’aide Notion).

Côté Vercel Sandbox : l’exécution du code est facturée selon un modèle active-CPU (tarifs Vercel Sandbox). Seul le temps de calcul effectif est compté, les périodes d’attente I/O (requêtes réseau, appels API) ne sont pas facturées. Sur le plan Hobby (gratuit), vous disposez de 5 heures de CPU actif par mois. Au-delà, le tarif Pro est de 0,128 dollar par heure de CPU.

Pour un usage type (quelques syncs quotidiens et des Tools appelés ponctuellement), le coût Vercel reste marginal, souvent couvert par le plan gratuit.

Limites actuelles et perspectives

Workers est en alpha, ce qui implique plusieurs limitations :

• Breaking changes possibles : l’API et le CLI peuvent évoluer sans préavis
• TypeScript uniquement : pas de support Python côté SDK Notion (malgré le support Vercel Sandbox)
• Pas de GPU : les microVM actuelles sont CPU-only. Le support GPU (via krunkit) existe dans l’écosystème microVM, mais n’est pas encore disponible dans Workers
• Région unique : l’exécution se fait exclusivement dans la région iad1 (US East)
• Documentation limitée : le template GitHub et le blog Vercel sont les principales sources

Mon avis : malgré ces contraintes, Workers change la donne pour les développeurs Notion. En ouvrant l’exécution de code, Notion devient une plateforme extensible. Les équipes techniques peuvent construire des intégrations sur mesure, hébergées et sécurisées, sans maintenir d’infrastructure tierce.

Pour suivre l’évolution de Workers, consultez le dépôt GitHub officiel et la documentation de l’API Notion.