How to Build AI Agents and Workflows Using Notion's Developer Platform

By ● min read

Introduction

Notion has evolved beyond a simple workspace tool. With its new Developer Platform, you can now build AI-enabled workflows and agents that interact directly with your enterprise data and workspace content. This guide walks you through the steps to set up custom code execution, sync external databases, and connect third-party agents—all within Notion. Whether you're a developer or a power user, you'll learn how to extend Notion's capabilities and automate repetitive tasks.

What You Need

• A Notion account with workspace admin permissions
• Basic knowledge of JavaScript/TypeScript for writing Workers
• Access to a code editor (e.g., VS Code)
• Node.js installed on your machine (for the Notion CLI)
• API keys or OAuth tokens for external services (e.g., Salesforce, Zendesk) if using database sync
• An account on partner platforms (Claude, Codex, Decagon) if using pre-built agents

Step-by-Step Guide

Step 1: Set Up Your Workspace and Developer Access

First, ensure you have a Notion workspace with the appropriate permissions. Navigate to the Developer Portal (available from your workspace settings). Here you can create an integration, generate a personal access token, and define workspace-scoped OAuth permissions. This token will be used to authenticate all API calls.

Step 2: Install and Configure the Notion CLI

The Notion Command Line Interface (CLI) is your primary tool for interacting with the platform. Install it globally via npm:

npm install -g @notionhq/cli

After installation, run notion login and authenticate using your access token. The CLI allows you to sign into workspaces, view content, and deploy Workers.

Step 3: Create Your First Notion Worker

Workers are serverless functions that run custom code in Notion's hosted runtime. They are deterministic and cost-efficient compared to LLM-based reasoning. To create a Worker:

1. Use the CLI: notion worker init my-first-worker
2. This generates a basic JavaScript file with a handler function.
3. Write your logic—for example, fetching data from an external API and updating a Notion database.
4. Deploy with notion worker deploy --name my-first-worker.

Workers can respond to webhooks, schedule tasks, or serve as tools for AI agents.

Step 4: Set Up Database Sync

Database Sync (currently in beta) lets you pull data from external systems into Notion databases. To use it:

1. Open your Notion database and go to the Sync tab.
2. Choose a source (e.g., Salesforce, Zendesk, or any REST API).
3. Map fields between the external data and your Notion database columns.
4. Enable automatic sync intervals (e.g., every hour).

This brings live data into your workspace, making it available for workflows and agents without manual updates.

Step 5: Connect External AI Agents

Notion's External Agents API (alpha) allows third-party or internally built agents to operate inside your workspace. To connect an agent:

1. Register your agent in the Developer Portal under External Agents.
2. Provide an endpoint URL where Notion can send events (e.g., page created, database updated).
3. Use OAuth tokens to grant the agent permission to read/write specific content.

Notion has partnered with Claude, Codex, and Decagon for out-of-the-box agents. You can also build custom agents using the API.

Step 6: Implement Workflow Triggers and Webhooks

Workers can be triggered by webhooks from other applications. For example, when a new row is added in a connected database, your Worker can process it. To set up a webhook:

1. In your Worker code, expose an HTTP endpoint (the default handler).
2. Copy the Worker's URL from the CLI output.
3. In the external service (e.g., Slack, GitHub), create a webhook pointing to that URL.
4. Test the trigger by sending a sample event.

This creates an event-driven automation pipeline between Notion and your other tools.

Step 7: Monitor and Iterate

Use the Developer Portal to view logs, error reports, and usage statistics for your Workers and agents. Adjust code, permissions, or sync intervals based on performance. Remember that Workers are free during beta but will require Notion credits after August 11—plan accordingly.

Tips for Success

• Start small: Begin with a single Worker that performs a simple task (e.g., counting pages) before building complex multi-step workflows.
• Governance matters: Enterprise adoption hinges on security. Use workspace-scoped OAuth and limit permissions to the minimum needed for each integration.
• Leverage existing data: Database sync from Salesforce or Zendesk can bring real-time customer data into your Notion workspace—ideal for support teams.
• Combine with AI agents: Use Claude or Codex agents to analyze synced data and generate summaries automatically.
• Monitor costs: Notion credits will apply to Worker executions after beta. Check the pricing page and optimize your code to reduce execution time.
• Community and documentation: Notion has rebuilt its developer docs and MCP support. Bookmark the portal for updates and best practices.