# Notion AI Hub - Full Documentation

> Complete documentation content for LLMs.
> For a summary with links, see https://21notion.ai/llms.txt

---

# Notion AI Hub Docs (https://21notion.ai/en/docs)

import { Brain, Zap, Bot, BookOpen, MessageSquare, Sparkles } from 'lucide-react';

Welcome to Notion AI Hub documentation! This is your starting point for learning and mastering Notion AI.

## Coming Soon

Documentation is being actively written. Stay tuned!

We will cover the following topics:

* **Notion AI Basics** — AI Chat, AI Q\&A, AI Writing Assistant
* **Notion Agents** — Custom Agent Building Guide
* **Automation Workflows** — AI-powered automation for productivity
* **Real-world Cases** — AI application scenarios in practice


---

# Automation (https://21notion.ai/en/docs/automation)

# Automation

Notion Automation combined with Custom Agent enables powerful automated workflows. This section focuses on Agent-Automation integration scenarios and practical tips.

## Coming Soon

This section is being written and will cover:

* **Agent × Automation Integration Guide** — How to make Agent and Automation work together
* **Key Technique: Chaining Automations with Agent** — Methods for building complex automation flows


---

# Best Practices (https://21notion.ai/en/docs/best-practices)

# Best Practices

A collection of lessons learned and methodologies from our Notion AI practice, helping you avoid common pitfalls.

## Coming Soon

This section will be gradually filled as we accumulate more hands-on experience. Planned topics include:

* Incremental vs. stock content strategies
* Avoiding over-automation
* Agent memory page techniques
* Manual vs. automatic trigger selection
* Cost management methodology


---

# Create Your First Agent (https://21notion.ai/en/docs/custom-agent/create-first-agent)

# Create Your First Agent

This guide walks you through creating a Notion Custom Agent from scratch, covering the four core configuration areas so you can get your first Agent up and running quickly.

## Prerequisites

Custom Agent requires a Notion Business plan. If you are on the Free or Plus plan, you will need to upgrade to Business before the Agent creation option becomes available.

## How to Create an Agent

Open Notion and click the "New Agent" button in the upper-left corner to open the Agent setup panel.

![Create Custom Agent button](https://pic.eryinote.com/PicGo/20260308122546.webp)

A settings panel will appear with the four core configuration areas for your Agent.

![Agent settings panel](https://pic.eryinote.com/PicGo/20260303213048.webp)

## Four Core Configuration Areas

### Trigger

The trigger determines when your Agent starts working — think of it as the Agent's "work schedule."

You can set an Agent to run automatically under specific conditions, such as when a new record is added to a database, when a property value changes, or on a fixed time interval.

If you skip the trigger setup, the Agent can only be run manually.

### Instruction

The instruction is your Agent's "operating manual" — it defines what the Agent should do and how it should do it.

A good instruction includes: the task you want the Agent to accomplish, rules and criteria for processing data, and the expected output format. The clearer and more specific your instructions, the more consistent and reliable the Agent's behavior.

### Model

The model is your Agent's "brain" — it determines how well the Agent understands context and reasons through problems.

Notion offers several models to choose from. More capable models generally handle complex tasks better, but they consume more Tokens per run, which means higher cost. For simple categorization and organization tasks, a basic model works fine. For tasks involving complex reasoning or content generation, a more powerful model is recommended.

### Tools & Access

Tools and access are the Agent's "computer and key card" — they determine which resources the Agent can operate on and which capabilities it can use.

You can authorize an Agent to read and write specific databases and pages, and enable built-in tools like web search and email sending. Follow the principle of least privilege: only grant the permissions the Agent actually needs to complete its task, and avoid over-provisioning.

## Beyond Notion

Custom Agent is not limited to working inside Notion. Through MCP and Workers, an Agent can connect to external services and call third-party APIs, enabling cross-platform automation workflows.

For example, you can have an Agent automatically sync content from a Notion database to another platform, or pull data from an external source and write it into Notion.

## Quick Tips

Don't aim for perfection with your first instruction. Start with a simple instruction, run the Agent, observe its actual behavior, and then refine iteratively based on the results. Iterating is more efficient than trying to get everything right on the first attempt, and it makes it much easier to spot issues early.


---

# Credits (https://21notion.ai/en/docs/custom-agent/credits)

# Credits

Custom Agent uses a Credits-based billing system.

## Billing System

* Tentative pricing: 1000 Credits / $10
* Currently in beta, Credits fees are waived
* Official billing begins after May 4, 2026
* BYOK (Bring Your Own Key) is not currently supported — you cannot use your own API Key

## Real-World Usage Cost Reference

* Heavy users (over a dozen Agents running continuously + extensive testing): approximately 50,000 Credits/month
* Normal usage (excluding test cases): approximately 30,000 Credits/month, roughly $300
* For comparison, $300 could cover subscriptions to both ChatGPT Pro and Claude Max 5X

![Credits consumption statistics](https://pic.eryinote.com/PicGo/20260308130002.webp)

## Factors Affecting Credits Consumption

* Model selection: higher-end models consume more Credits; lower-end models are cheaper
* Trigger frequency: scheduled triggers are more controllable than event-based triggers
* Instruction complexity: the more context read and the more complex the steps, the higher the consumption
* Number of Agents: each Agent consumes Credits every time it is triggered

## Tips for Saving Credits

* Use low-cost models like MiniMax 2.5 for simple tasks (Credits consumption can be reduced by roughly two-thirds)
* Pre-filter with email labels to prevent irrelevant emails from triggering Agents (labels are applied by Notion AI for free and do not consume Custom Agent Credits)
* Use the routing pattern with a single entry Agent to distribute work, avoiding multiple Agents being triggered simultaneously
* Split instructions into sub-pages loaded on demand to reduce context per execution
* Regularly evaluate whether each Agent is necessary and remove those that are not essential

![MiniMax 2.5 low-cost model](https://pic.eryinote.com/PicGo/20260308133019.webp)

## Future Outlook

The Notion CEO has stated that more models will be added. As more low-cost models become available, Credits pressure is expected to ease.

![More models coming soon](https://pic.eryinote.com/PicGo/20260308134240.webp)


---

# Debugging & Optimization (https://21notion.ai/en/docs/custom-agent/debugging)

# Debugging & Optimization

Creating an Agent might only take ten minutes, but the real effort lies in the training period that follows. Think of it like onboarding a new employee — you can't expect everything to go perfectly on day one.

## Iterative Development Workflow

1. **Get it running first** — Write only the core steps in your first version of instructions. Don't aim for perfection.
2. **Observe the results** — Review the Agent's output and note where it falls short of expectations.
3. **Fix the edge cases** — You'll inevitably miss some edge cases. Add them in gradually.
4. **Review regularly** — Periodically verify the Agent's output and evaluate whether it's still necessary.
5. **Clean up decisively** — If an Agent feels dispensable, delete it. Otherwise, over time, too many notifications pile up and useful information gets buried in noise.

## Memory Page Pattern

Create a dedicated memory page for your Agent:

* The Agent reads it before each execution to understand historical context
* After execution, it writes key information back to the page
* Essentially, a Notion page serves as the Agent's external memory
* The content doesn't need to look polished — accuracy is what matters

Through incremental adjustments, you can gradually refine a rough Agent into a truly reliable virtual employee.

![Agent memory page example](https://pic.eryinote.com/PicGo/20260308013624.webp)

## Common Troubleshooting

### Agent Didn't Trigger as Expected

* Check whether the trigger settings are correct
* Confirm that page access permissions haven't been lost (permissions can silently fail)
* Review the Agent's execution logs

### Agent Output Is Unsatisfactory

* Check whether the instructions are clear and specific enough
* Confirm the Agent can access the required databases and pages
* Consider switching to a more capable model
* Check whether the knowledge base covers the relevant scenarios

### Abnormal Credits Consumption

* Check if any Agent is being triggered too frequently by mistake
* Review whether instructions are loading unnecessary context
* Consider using the routing pattern to reduce unnecessary triggers

### Silent Permission Failure

* The Agent appears to be running normally, but has actually stopped working
* There are no error messages — you need to proactively check the execution logs
* Solution: Re-authorize access permissions for the relevant pages


---

# Custom Agent (https://21notion.ai/en/docs/custom-agent)

# Custom Agent

Notion Custom Agent lets you create AI assistants tailored to your specific needs. This section covers everything from getting started to advanced features.

## Getting Started

* [Create Your First Agent](/docs/custom-agent/create-first-agent) — Build a working Agent from scratch
* [Instruction Writing Guide](/docs/custom-agent/instruction-guide) — How to write effective Agent instructions
* [Debugging & Optimization](/docs/custom-agent/debugging) — Methods for diagnosing issues and continuously improving Agents

## Feature Reference

* [Knowledge Base](/docs/custom-agent/knowledge) — Add dedicated knowledge sources to your Agent
* **Tools** — Available tools and capabilities for Agents (coming soon)
* [Triggers](/docs/custom-agent/triggers) — Five trigger types explained with selection guide
* [Model Selection](/docs/custom-agent/model-selection) — AI model characteristics and cost trade-offs
* **MCP Integration** — Extend Agent capabilities via MCP protocol (coming soon)
* [Routing](/docs/custom-agent/routing) — Multi-Agent routing and cost optimization strategies

## Management & Reference

* [Credits](/docs/custom-agent/credits) — Pricing, real-world costs, and tips to save Credits
* [Known Limitations](/docs/custom-agent/limitations) — Worker boundaries, permission issues, and ecosystem lock-in
* **FAQ** — Frequently asked questions (coming soon)


---

# Instruction Writing Guide (https://21notion.ai/en/docs/custom-agent/instruction-guide)

# Instruction Writing Guide

Instructions are the Custom Agent's "operating manual" and directly determine the quality of its output. Clear instructions lead to consistent, reliable results. Vague instructions lead to chaos.

## Basic Instruction Structure

A good Agent instruction should include four parts:

**Define the task objective** — Tell the Agent exactly what to do. Don't say something vague like "help me process this." Instead, be specific: "Read the page content and write a 3-sentence summary in the Summary field."

**Specify input sources** — Which database and which fields to read from. The Agent won't automatically know where to look; you need to be explicit.

**Set the output format** — Where to write the results and in what format. For example, which property to write to, whether to use a list or paragraphs, character limits, etc.

**Establish execution rules** — Boundary conditions and error handling. For example, what to do when a field is empty, or whether to skip or flag uncertain situations.

### Example

A task follow-up Agent: reads all page content (title, body, status, schedule, linked notes, etc.), evaluates comprehensively, and writes 3 actionable next-step suggestions in the "What to do next" field.

![Agent instruction example](https://pic.eryinote.com/PicGo/20260306123052.webp)

## Sub-Page Reference Tips

When instructions get long and cover multiple scenarios, you can use @ references to sub-pages to organize them.

The benefit: the Agent only loads sub-page content when it hits the corresponding route, rather than stuffing all instructions into the context every time. This saves Credits, reduces irrelevant noise, and helps the Agent stay focused on the current task.

![Sub-page reference pattern](https://pic.eryinote.com/PicGo/20260305153043.webp)

## Memory Page Pattern

Each Agent execution is independent — by default, the Agent doesn't remember what it did last time. If you need your Agent to have "memory," you can create a dedicated memory page for it.

Here's how: in the instructions, tell the Agent to read the memory page before each execution, and write key information back to it after completing its task. This effectively uses a Notion page as the Agent's external memory.

The memory page doesn't need to look pretty — it just needs to be accurate and truthful. It's for the Agent to read, not for humans.

![Agent memory page](https://pic.eryinote.com/PicGo/20260308013624.webp)

## Iterative Optimization Principles

Writing Agent instructions doesn't require perfection on the first try. Iteration is the right approach:

**Get it running first** — The first version of your instructions should only cover the core steps. Let the Agent run and see if the general direction is correct.

**Refine incrementally** — After each run, identify what went wrong and add specific boundary conditions and details. Change only one thing at a time so you can easily judge the effect.

**Review periodically** — Step back every now and then to review the Agent's execution results and verify it's still working as expected. Business scenarios evolve, and instructions need to evolve with them.

**Delete decisively** — If an Agent feels dispensable after running for a while, delete it without hesitation. Imprecise notifications only create noise and add to your information processing burden.


---

# Knowledge Base (https://21notion.ai/en/docs/custom-agent/knowledge)

# Knowledge Base

The knowledge base is your Custom Agent's "reference material," determining what information the Agent can draw on when answering questions and executing tasks.

## What Is a Knowledge Base

* A knowledge base consists of the Notion pages and databases you designate for the Agent to reference
* The Agent retrieves relevant content from the knowledge base when executing tasks
* The quality of your knowledge base directly determines the quality of the Agent's output

## How Knowledge Base Quality Matters

Take a customer support scenario as an example:

* If the knowledge base is well-organized and covers common questions, the Agent's replies will be accurate and helpful
* If the knowledge base is sparse or messy, the Agent will give vague or even incorrect answers

![How knowledge base quality affects response quality](https://pic.eryinote.com/PicGo/20260304202729.webp)

## Knowledge Base Configuration Tips

1. **Organize with structure** — Categorize content by topic and scenario so the Agent can find relevant information more easily
2. **Cover common questions** — Make sure high-frequency scenarios all have corresponding reference content
3. **Keep it updated** — Regularly maintain knowledge base content by removing outdated information and adding new material
4. **Keep it concise and accurate** — A bigger knowledge base isn't necessarily better. Redundant information can actually interfere with the Agent's judgment
5. **Verify in practice** — After adding new content, test with real scenarios to confirm the Agent can reference it correctly

## Typical Use Cases

* **Customer support** — Product FAQs, pricing information, refund policies, etc.
* **Topic research assistant** — Past notes, web clippings, reading notes, and other reference materials
* **Content generation** — Brand voice guidelines, writing style guides, historical articles, etc.

## Working with Other Capabilities

* Knowledge base + email trigger = automatically reply to customer inquiries
* Knowledge base + page edit trigger = auto-generate outlines based on source materials
* Knowledge base + manual chat = query internal knowledge on demand

Building a solid knowledge base is one of the most important prerequisites for using Custom Agent effectively. In many scenarios, maintaining a high-quality knowledge base matters more than building the Agent itself.


---

# Known Limitations (https://21notion.ai/en/docs/custom-agent/limitations)

# Known Limitations

Custom Agent is powerful, but as a feature still in beta, there are some limitations worth knowing about.

## 1. Worker Capability Boundaries

* Workers can only communicate with external services through public HTTP requests
* They cannot access internal network resources or call local services
* Workers execute on demand and exit when done — they cannot maintain persistent connections
* They cannot manipulate local files, run local models, or interact with LAN devices
* In short: Workers give Agents the ability to "travel," but they can only do business via public HTTP — they can't roam freely

## 2. Permission Stability

* Page access permissions granted to an Agent occasionally disappear without explanation
* On the surface, the workflow appears to be running normally, but it has actually stalled due to permission issues
* You won't receive any error notification — this kind of "silent failure" is harder to detect than an outright error
* It's recommended to periodically check the Agent's execution logs to confirm permissions are intact
* This doesn't happen often, but when it does, you'll need to manually re-authorize

![Silent permission failure example](https://pic.eryinote.com/PicGo/20260308015323.webp)

## 3. Notion Ecosystem Lock-in

* The value of Custom Agent is highly tied to how deeply you've built within Notion
* The Agent's perception, reasoning, and actions all revolve around your Notion workspace
* Outside the Notion ecosystem, an Agent's value drops rapidly
* By comparison, general-purpose agents like Claude Code or OpenClaw don't depend on a specific platform and offer greater flexibility
* If your Notion workspace only has a few scattered pages, Custom Agent's value will be significantly diminished
* Conversely, the deeper your Notion investment (more databases, richer notes), the more resources the Agent can leverage, and the greater its value

## 4. Still Rapidly Evolving

* Custom Agent is still in Beta — both features and pricing may change
* The good news: more low-cost models are being added, and costs are expected to decrease


---

# Model Selection (https://21notion.ai/en/docs/custom-agent/model-selection)

# Model Selection

Custom Agent supports multiple AI models, each differing in intelligence level and Credits consumption. Choosing the right model is key to balancing performance and cost.

## Core Principles

* More capable models handle complex tasks better, but consume more Credits
* Simple tasks only need low-cost models; reserve high-end models for complex tasks

## Available Models

The following is based on models available during the beta period and may change after official release:

* High-end models (such as Claude and GPT-5 class): suitable for complex reasoning, multi-step tasks, and content generation
* MiniMax 2.5: the first domestic model introduced by Notion, reducing Credits consumption by roughly two-thirds, suitable for simple scheduled recurring tasks

![Model selection interface](https://pic.eryinote.com/PicGo/20260308133019.webp)

## Selection Recommendations

* Content generation, translation, complex reasoning → use high-end models
* Scheduled briefings, simple field filling, formatting → use low-cost models like MiniMax 2.5
* Multi-step workflows (such as an 11-step blog publishing process) → use high-end models to ensure each step executes accurately
* Email classification, label matching, and pattern recognition → low-cost models are usually sufficient

## More Models Coming Soon

The Notion CEO has stated that more models will be continuously added. In the future, there may be more domestic models and low-cost options, giving users more flexibility across different scenarios.

![Notion CEO statement on models](https://pic.eryinote.com/PicGo/20260308134240.webp)


---

# Routing Pattern (https://21notion.ai/en/docs/custom-agent/routing)

# Routing Pattern

As your number of Agents grows, efficiently managing their triggers and coordination becomes a key challenge. The routing pattern is the core strategy for solving this problem.

## The Problem: Multi-Agent Waste

Imagine you have three email Agents — one for orders, one for customer service, and one for Newsletters. Every time an email arrives, all three Agents wake up, each parsing the email independently. In the end, only one is actually relevant. The other two did work for nothing, wasting Credits.

## The Solution: Single Entry Point Routing

The overall idea is to use just one Agent as the entry point, responsible for identifying and routing.

### Layer 1: Email Label Pre-Filtering (Free)

* If you subscribe to Notion AI, the official Notion Mail app can automatically label emails using AI
* This step does not consume Custom Agent Credits
* Change your email trigger to "When a label is applied to an email" — only matching emails will trigger the Agent

![Notion Mail AI auto-labeling](https://pic.eryinote.com/PicGo/20260306171627.webp)

![Email trigger set to label-based](https://pic.eryinote.com/PicGo/20260306172036.webp)

### Layer 2: Instruction Sub-Pages Loaded on Demand

* Each sub-scenario's execution rules are written in separate sub-pages
* The main instruction references these sub-pages via @
* The Agent only loads the corresponding sub-page content when it matches a route
* When processing a Stripe order, the Agent won't read the Newsletter archiving rules

![Sub-scenario instruction documents](https://pic.eryinote.com/PicGo/20260305153043.webp)

## Benefits of the Routing Pattern

* Agents that shouldn't wake up don't wake up — saving Credits
* Email labels filter out irrelevant messages before the Agent even starts
* Instructions are loaded on demand rather than in full, reducing context consumption
* Easier to maintain and extend: adding a new scenario only requires a new sub-page

## Design Principle

Before creating a new Agent, beyond thinking about "what should it do," it's also worth asking "when should it NOT be woken up."


---

# Triggers (https://21notion.ai/en/docs/custom-agent/triggers)

# Triggers

Notion Custom Agent supports multiple trigger types that determine when an Agent automatically starts. Choosing the right trigger ensures your Agent intervenes at the right moment.

## Five Trigger Types

### Scheduled

Runs on a fixed schedule, such as every day at 9 AM or every Monday at 2 PM.

Use cases: daily briefings, weekly summaries, periodic data cleanup.

![Scheduled trigger settings](https://pic.eryinote.com/PicGo/20260306115239.webp)

### Page Edited

Automatically triggers when a database page is edited. The Agent executes roughly three minutes after the page stops being edited, so it won't jump in while you're still writing.

Use cases: auto-filling fields, content summary generation, data validation.

![Page edited trigger](https://pic.eryinote.com/PicGo/20260304223233.webp)

### Email Received

Triggers when a new email arrives. You can combine this with email labels to pre-filter messages and avoid consuming Credits on every single email.

Use cases: order logging, email summaries, automatic archiving.

![Email trigger](https://pic.eryinote.com/PicGo/20260306133142.webp)

### Property Changed

Triggers when a specific property in a database page is modified — for example, when a status changes from "To Do" to "In Progress."

Use cases: status-driven workflows, publishing pipelines, approval chains.

![Property changed trigger](https://pic.eryinote.com/PicGo/20260305123618.webp)

### Manual Chat

Open the Agent directly and have a conversation. After you submit a question, it executes based on its preset instructions. This is the most flexible option when you don't need automation.

Use cases: on-demand queries, knowledge base Q\&A, ad-hoc tasks.

![Manual chat trigger](https://pic.eryinote.com/PicGo/20260307154110.webp)

## Choosing the Right Trigger

Different triggers suit different types of tasks:

* **Scheduled** is best for "routine tasks" — anything that needs to run on a fixed cadence, like daily briefings or weekly summaries
* **Page Edited** is best for "real-time responses" — when you want the Agent to step in right after you finish writing
* **Email Received** is best for "external inputs" — workflows driven by external events like incoming emails
* **Property Changed** is best for "process-driven flows" — status changes trigger the next step, chaining together an entire workflow
* **Manual Chat** is best for "on-demand use" — no automation needed, just open and chat whenever you want

## Trigger Design Tips

A well-designed trigger should be driven by "current events" (such as a new email, a new topic, or a status change) rather than firing randomly without purpose. If a trigger's timing isn't precise enough, the Agent's output becomes noise that adds to your workload instead of reducing it.


---

# Notion AI Basics (https://21notion.ai/en/docs/notion-ai-basics)

# Notion AI Basics

Notion comes with a rich set of built-in AI features covering chat, writing, search, autofill, and more. This section walks through each feature's usage and tips.

## Coming Soon

This section is being written and will cover:

* **AI Chat** — Converse with Notion AI for information and inspiration
* **AI Writing** — Use AI to draft, rewrite, and polish text
* **AI Autofill** — Automatically extract and generate database property content
* **AI Search** — Intelligently search information across your workspace
* **Connectors** — Connect external data sources to extend AI capabilities
* **Blurb Mechanism** — Understand Notion AI's context summarization mechanism
* **Pricing** — Notion AI pricing models and cost planning


---

# Workers (https://21notion.ai/en/docs/workers)

# Workers

Notion Workers let you extend Custom Agent capabilities by writing code, enabling tasks that Agents can't do natively — like calling external APIs, processing files, and pushing content to other platforms.

## In This Section

* **[Quick Start](/docs/workers/quick-start)** — Environment setup, creating your first Worker, deployment & testing, OAuth, and debugging
* **Example: One-click Blog Publishing** (coming soon) — Use the publishBlogPost Worker to auto-publish from Notion to your website

For a real-world look at Workers in action, check out [this hands-on blog post](/blog/notion-worker-in-practice).


---

# Quick Start (https://21notion.ai/en/docs/workers/quick-start)

# Quick Start

Workers let Custom Agents reach beyond the Notion ecosystem by running your own code to call any external API. This guide walks you through setting up your environment, creating your first Worker, deploying it to Notion, and testing it end to end.

## Worker vs MCP

Before diving in, let's clarify the difference between Workers and MCP:

* **MCP** is "using a bridge someone else built." Notion provides pre-built MCP servers for services like Stripe, GitHub, and Figma — you can connect them with a few clicks, but you're limited to the tools others have defined.
* **Worker** is "building your own bridge." You define tool behavior in code, with full control over the requests you send, the parameters you pass, and how you handle the responses.

In short: Workers fill the gaps that MCP can't cover. If you want to see Workers in action, check out [this hands-on walkthrough](/blog/notion-worker-in-practice).

## Prerequisites

Worker development requires the following:

* **Node.js** >= 22
* **npm** >= 10.9.2
* A **Notion Business** plan (Worker access requires a Business subscription)

Once your environment is ready, install the Notion CLI:

```bash
npm i -g ntn
```

Then log in to your Notion workspace:

```bash
ntn login
```

## Create Your First Worker

Notion provides an official template repository. Clone it locally to get started:

```bash
npx degit makenotion/workers-template my-worker
cd my-worker
npm install
```

Open `src/index.ts` and you'll see the project's core structure is straightforward:

```ts
import { Worker } from "@notionhq/workers";

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

worker.tool("sayHello", {
  title: "Say Hello",
  description: "Return a greeting",
  schema: {
    type: "object",
    properties: {
      name: { type: "string" }
    },
    required: ["name"],
    additionalProperties: false
  },
  execute: ({ name }, _context) => `Hello, ${name}`,
});
```

This is a minimal Worker. It does one thing: takes a name and returns a greeting.

Each `tool` is a capability the Agent can invoke. Here's what each part does:

* `title` and `description` appear in the Notion Agent's tool list and help the Agent understand what the tool is for.
* `schema` defines the parameters the Agent must provide when calling the tool (in JSON Schema format).
* `execute` contains the actual logic that runs.

## Deploy

Once your code is ready, deploy with a single command:

```bash
ntn workers deploy
```

After deployment, the Worker's tools will automatically appear in the Custom Agent tool list within your Notion workspace.

If your Worker needs sensitive information like API keys, set them as environment variables:

```bash
ntn workers env set API_KEY=your-api-key
```

Access them in your code via `process.env.API_KEY`.

## Test

After deploying, you can test your tools directly from the command line:

```bash
# Test the deployed remote Worker
ntn workers exec sayHello -d '{"name": "World"}'

# Test locally (no deployment needed; .env files are loaded automatically)
ntn workers exec sayHello --local -d '{"name": "World"}'
```

Local testing is ideal during development — edit your code and run it immediately without redeploying each time.

## OAuth Integration

If your Worker needs to act on behalf of a user with a third-party service (e.g., posting tweets or managing GitHub repos), you'll need to configure OAuth:

```ts
const myOAuth = worker.oauth("myOAuth", {
  name: "my-provider",
  authorizationEndpoint: "https://provider.example.com/oauth/authorize",
  tokenEndpoint: "https://provider.example.com/oauth/token",
  scope: "read write",
  clientId: "your-client-id",
  clientSecret: process.env.MY_OAUTH_SECRET ?? "",
});
```

After deploying a Worker with OAuth, you also need to configure the callback URL on the third-party platform. Run the following command to get the redirect URL assigned by Notion:

```bash
ntn workers oauth show-redirect-url
```

Then enter this URL in the third-party platform's OAuth application settings.

## Debugging

Once your Worker is deployed, use `ntn workers runs` to view execution history and logs:

```bash
# List recent runs
ntn workers runs list

# View detailed logs for a specific run
ntn workers runs logs <runId>

# Quickly view logs from the most recent run
ntn workers runs list --plain | head -n1 | cut -f1 | xargs -I{} ntn workers runs logs {}
```

The `--plain` flag outputs plain text, making it easy to pipe into other commands for further processing.

To troubleshoot CLI configuration issues, run:

```bash
ntn debug
```

## Feature Availability

Workers are currently in Alpha. Here's the status of each feature:

* ✅ **Agent Tools** — Public; this is the core functionality covered in this guide
* ✅ **OAuth (User Management)** — Public; used to connect third-party services that require authorization
* 🔧 **OAuth (Notion Management)** — In private beta
* 🔧 **Syncs (Data Synchronization)** — In private beta
* 🔧 **Automations** — In private beta

Workers are free to use during the Alpha phase. Pricing for the general release has not been announced.

## Next Steps

Now that your environment is set up and you understand the basics, you can:

* Read [Worker in Practice: Automated Blog Publishing](/blog/notion-worker-in-practice) for a complete real-world example
* Try wrapping your frequently used third-party APIs as Worker tools
* Visit the [Custom Agent docs](/docs/custom-agent) to learn how to add Worker tools to your Agent