How to build any automation inside Notion - Notion Workers
One of the perils of building AI agents is that the quality of output can vary widely across runs. Variance is often welcome in creative tasks and it is a bug in structured work. Notion Workers give you more control over custom agents output accuracy. In addition, they allow syncing data from external tools into Notion, replacing Make, Zapier, or n8n for many automations.
Workers are tools that run TypeScript code, providing deterministic execution within an AI-orchestrated flow or as a standalone automation. They are hosted in Notion’s infrastructure (Node.js environment), so you just write the code and deploy it, while all the backend is managed by Notion.
When deployed as custom agent tools, they don't make the whole workflow deterministic, but only the parts that need to be (calculations, API calls, data transformations), while letting the AI handle the components that benefit from reasoning (for example, context interpretation and decision-making).
There are two types of Notion Workers, each one with a dedicated syntax, so before building a worker you get to decide which type you will create.
Tools: deterministic code connected to one or multiple custom agents as a tool. Tools are apps and functions the agent can use when it runs in order to achieve the objective and provide quality output. You can connect a Worker like any other tool in the settings of Custom Agents.
Sync: traditional (deterministic) automation to sync data from external tools into Notion. This doesn’t have to do with AI (unless you decide so), and it can replace automation tools such as Zapier, Make, or n8n. Sync workers can run on a schedule or immediately when receiving a webhook from an external tool.
Practical Examples
Worker as Custom Agent Tool
You run a construction firm whose work involves complex project management. You track the status of your projects in Notion, leveraging dependencies and sub-items. But there is no clear way to run calculations on entire projects or to easily shift dates when there is a change of plans.
By creating a Notion custom agent that leverages a Notion Worker, you can automate part of the project management process and keep data up to date for everyone on your team.
Worker as Sync
You want to sync your Google Contacts to a Notion data source so you can manage your CRM data (meetings, contacts, interactions, and so on) in one place. You can build a Notion Worker to sync new, updated, and deleted contacts from Google into Notion. The Worker can run on a schedule you define (for example, every 30 minutes) and keep your data in Notion up to date.
Check out the sample code here.
How to Build a Notion Worker
In this demo, I am building a Notion Worker that syncs the top 10 stories from Hacker News to Notion every three hours. Hacker News has an open API that doesn’t need any authentication. Most other tools you’d sync for real use cases (for example, Jira, Google Workspace, Outlook) require authentication, and you will follow their official API documentation to find out how to implement it in your Worker code.
First, I installed the Notion CLI in my terminal via one of the available installation methods—see here.
Next, I logged into Notion via the CLI to authenticate and select the workspace where I want the Hacker News stories to sync. For this, I used the command ntn login, which opened a browser tab with the screen shown below. Once the authentication is done, a Personal Access Token (PAT) was auto generated in the dedicated section.
browser confirmation screen after running ntn login
Then I used Cursor (an AI tool to generate code) to create and iterate on the Notion Worker, syncing the code in a GitHub repo. Once deployed via ntn workers deploy, the Worker showed up in my Developer Platform account, and a new database for the sync was automatically created in Notion. This database will be used for all future runs to upsert the top 10 Hacker News stories every three hours.
The synced database from the Worker where all the HackerNews stories are stored
Additional Things to Know
You can check the status of Workers and their historical runs in the dedicated section within the Developer Platform, where you can also disable or remove Workers.
Notion Workers are part of the Business and Enterprise plans and must be opted in by a Notion workspace owner via the dedicated settings under the Workers tab.
Workers are billed as an add-on. They consume Notion Credits, just like custom agents, and are generally significantly cheaper. Find out details about pricing here.
Since Notion Workers are TypeScript code, you can store them in GitHub repositories, which act as an archive of the code and facilitate collaboration and migration to other tools. This makes Workers easily portable to other tools if needed as part of a migration.
Conclusion
Many people argue that we are in the AI orchestration era - a world where the main job of knowledge workers is to set up and oversee the work of many AI Agents. Notion is a leading platform for work and agent management, increasingly introducing features that make this paradigm tangible. Workers are one of those forward-looking features.
Many questions remain unanswered, especially with regard to runtime reliability, AI outputs, and principles of effective AI work orchestration. Many of these worries will get resolved as more people adopt these new ways of working. I remain observant of the landscape and skeptical about idealistic claims, continuing to test the tools out for myself and progressively shape my vision of work and life.
