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

Introduction

Notion has expanded beyond a collaborative workspace into a full-fledged developer platform, enabling teams to build AI-powered workflows and agents directly within their existing Notion environment. With the launch of Notion Workers, database sync, external agent APIs, and workflow triggers, developers can now extend Notion with custom code, integrate external data, and orchestrate AI agents—all without managing separate infrastructure. This step-by-step guide will walk you through setting up and using these capabilities, from installing the CLI to deploying your first Worker and connecting third-party agents.

What You Need

• A Notion workspace (any plan; some features may be in beta)
• Access to the Notion Developer Portal (free sign-up)
• Node.js (v18+) installed on your machine
• Basic knowledge of JavaScript/TypeScript
• API keys or authentication for external services (e.g., Salesforce, Zendesk) if using database sync
• Notion account with owner or admin permissions for workspace-scoped integrations

Step-by-Step Build Process

Step 1: Access the Notion Developer Portal

Navigate to the Notion Developer Portal at developers.notion.com. Sign in with your Notion account and complete onboarding. This portal provides your workspace-specific credentials (OAuth client IDs, personal access tokens) and houses the rebuilt documentation for all new features.

Step 2: Install the Notion CLI

Open your terminal and run:

npm install -g @notionhq/cli

Verify installation with notion --version. The CLI allows you to log into workspaces, act on Notion content, build and deploy Workers, and extend the platform programmatically.

Step 3: Authenticate with Your Workspace

Run notion login and follow the browser prompt to authorize the CLI. For automated or CI/CD environments, use personal access tokens (generated in the developer portal) via environment variables. Workspace-scoped OAuth is also available for multi-user integrations.

Step 4: Create Your First Notion Worker

Workers are hosted runtimes for custom code. Initialize a new Worker:

notion worker init my-agent-worker
cd my-agent-worker

This creates a src/index.ts file with sample code. Key properties: Workers are deterministic (more reliable than LLM reasoning), low-cost in token usage, and can respond to webhooks, sync data, or add custom logic to agent tools.

Step 5: Write and Deploy the Worker

Edit the worker code. For example, create a simple function that fetches data from an external API and writes it to a Notion database:

import { notion } from '@notionhq/worker';

export default async () => {
  const data = await fetch('https://api.example.com/leads');
  const json = await data.json();
  await notion.pages.create({
    parent: { database_id: 'your-database-id' },
    properties: { Title: { title: [{ text: { content: json.name } }] } }
  });
};

Deploy with notion worker deploy. During the beta, Workers are free; after August 11, usage runs on Notion credits. Monitor your credit consumption in the developer dashboard.

Step 6: Configure Database Sync (Beta)

Database sync pulls external data into Notion databases automatically. In the developer portal, navigate to Integrations → Database Sync. Select an external service (Salesforce, Zendesk, or custom API) and map fields. Teams can then use that synchronized data in workflows and agents without manual importing. The sync runs on Workers behind the scenes.

Step 7: Connect External Agents (Alpha)

The External Agents API allows third-party or internally built AI agents to operate inside Notion. To add an out-of-the-box agent (e.g., Claude, Codex, Decagon), navigate to workspace settings → Integrations → Agents and authorize. For custom agents, use the API endpoints to define tool calls and context permissions. This turns Notion into a reasoning and action hub for agentic workflows.

Step 8: Set Up Workflow Triggers

Workers can be triggered by events: database updates, page creations, or external webhooks. In your Worker configuration (inside the notion.worker.json file), define triggers:

{
  "triggers": [
    { "event": "page.created", "database_id": "..." },
    { "webhook": { "url": "https://hooks.example.com/notify" } }
  ]
}

Deploy again to activate. This enables automated responses—e.g., when a new lead is added, trigger an agent to analyze it and send a Slack alert.

Step 9: Test and Monitor

Use the developer portal’s Logs tab to view Worker execution output and errors. For local testing, run notion worker invoke with a test payload. The CLI also supports debugging with breakpoints in supported IDEs.

Step 10: Manage Security and Governance

For enterprise adoption, configure workspace-scoped OAuth and personal access tokens with minimal permissions. Audit Worker code via the portal. Notion’s platform is designed to meet CIO expectations for production use, but you should implement encryption for sensitive external API keys and adhere to governance guidelines in the developer docs.

Tips for Success

• Start with a simple use case—e.g., syncing a customer database from Salesforce—before adding AI agents.
• Leverage deterministic Workers for critical logic to avoid LLM unpredictability; reserve AI agents for tasks like summarization or triage.
• Monitor credit usage in the developer dashboard, especially after the free beta ends. Optimize Worker calls by caching API responses.
• Combine tools: Workers + database sync + external agents can create powerful automations comparable to low-code platforms like Zapier, but with more control and deeper Notion integration.
• Review the MCP support updates to connect Notion with other agent frameworks.
• Join community forums for early access to upcoming features and best practices from other developers.