Custom Agent

Custom Agents automate recurring, manual workflows for your entire team. They run automatically in the background on set triggers using your existing docs and databases as context.

Set them up once — building a workflow for repetitive tasks like weekly reports or triaging feedback — and it becomes a shared resource the whole team relies on.

Custom Agents live inside Notion and run on your instructions. Once you set them up, they can:

• Read from Notion pages and databases and certain connected apps.

• Run on recurring triggers and workspace events.

• Take actions such as posting reports, filing bugs, updating records, or sending messages.

Unlike Notion Agent, Custom Agents are designed to run automatically in the background based on triggers and schedules.

Custom Agents are built directly into Notion. Agents use your existing docs and databases as context and connect across Slack, increasing productivity. Custom Agents can:

• @mention Agents in Notion pages, database properties, and comments.

• Attach them to database events (for example, when a page is created or updated).

• Let them monitor your workspace and connected tools according to the triggers you configure.

Use triggers for Custom Agents to run without you manually starting them each time. Set a trigger once, then the work happens continuously in the background.

• Run on a schedule (daily, weekly, monthly, and more).

• React to events in Notion and Slack.

• Continue running in the background once you publish them.

This unlocks automated workflows like regular reports, triage queues, and knowledge maintenance, helping you reclaim your time.

Agents act only on the pages, databases, and external apps you explicitly grant access to. They never have full workspace access by default, reducing risk.

• Control who can edit, run, or interact with each Agent.

• View activity logs to see what an Agent did and when.

• Use Version history to review or restore past configurations.

• Keep runs reviewable and reversible so you can safely iterate.

• You must be on Notion’s Business or Enterprise Plan.

• To build or edit Custom Agents, use desktop or web. You can see or interact with Agents on desktop or web.

  • View and interact with any content Agents create in Notion pages and databases on mobile.

  • View Agent posts in Slack through the Slack mobile app.

You can build a Custom Agent from multiple locations. The primary entry point is the Agents section in the sidebar.

1. Go to the Agents section in the left sidebar and select + to create a new Custom Agent.

2. Choose how you want to start:

   • Create from a template

     • Choose a template.

     • Review the draft instructions, triggers, and access that Notion AI generates and iterate.

     • Save.

   • Create with AI chat

     • In the chat, describe what you want the Agent to do using natural language.

     • Review the draft instructions, triggers, and access that Notion AI generates and iterate.

     • Save.

   • Create from scratch

     • Select Create blank.

     • Start from an empty instructions field or chat with you.

     • Craft your instructions manually, following best practices for clear, concrete instructions. Define what the Agent should do, how it should behave, and what work it should handle.

     • Set triggers, access, your AI model until they match your workflow.

     • Save.

Triggers determine when your Agent runs. You can combine multiple trigger types for a single Agent.

Use recurring schedules to run Agents on a cadence.

1. Open your Custom Agent's Settings.

2. Go to the Triggers section.

3. Add a Recurring trigger.

4. Choose when you want the Agent to run:

   • Select a frequency (every day, week, month, or year).

   • Set a specific time, including timezone (for example, "every day at midnight PST").

5. Review the next scheduled run time to confirm the schedule is correct.

6. Save your trigger.

Notion triggers run your Agent based on events in your workspace. You can trigger Agents when:

• A comment is added to a page.

• A page is added to a database.

• A page is updated in a database.

• A page is removed from a database.

• The Custom Agent is @mentioned in a page or comment.

To add a Notion trigger:

1. Open your Custom Agent's Settings and select Triggers.

2. Choose a Notion trigger type.

3. Specify:

   • The page or database to watch.

   • The event (for example, "page created in database").

   • Any additional filters or conditions if available.

4. Save.

Slack triggers allow Agents to watch for events in public Slack channels. Agents can be triggered by a message posted to a channel, an emoji reaction added to a message, a thread started in a channel, or a Custom Agent mention in a message.

To add a Slack trigger:

1. Connect Slack to your Agent during setup if you have not already.

2. In Triggers, add a Slack trigger.

3. Select:

   • The event type.

   • The channel to monitor.

   • Any additional filters or conditions if available.

4. Save.

Custom Agents only use content you explicitly grant them access to for their work. You configure this in each Agent's access settings.

To control what an Agent can see in Notion:

1. Open the Custom Agent's Settings.

2. Go to the Tools and access section.

3. Add specific pages or databases the Agent should use as context:

   • Grant access to Help Center for coverage that includes Notion’s help content.

   • Grant access to Pages shared with everyone in Notion if you want broad coverage that includes content throughout the workspace.

   • Add focused pages and databases for targeted workflows (for example, "Customer tickets," "Bugs," "Incidents").

4. Keep access restricted to "none" or a small set of pages if you want a narrower scope.

Agents can optionally browse the web when needed. Use web access when your workflow depends on external information. Keep it off for strictly internal workflows or when you want stricter control over sources. To control web access:

1. Open Settings for your Agent.

2. Find the Web access toggle.

3. Turn web access on to let the Agent retrieve information from the internet.

4. Turn web access off to restrict the Agent to Notion and configured apps only.

Custom Agents can read and write to Slack through a dedicated integration. Before connecting Slack to your Custom Agent, an admin must first connect the Slack AI connector to your workspace via the Notion AI Settings. Agents can do the following:

• Read from public channels.

• Post messages, replies, and updates to channels.

• React to threads and use information from Slack as context.

To connect Slack:

1. When setting up the Agent, follow the prompt to connect Slack.

2. Make sure the Slack account uses the same email as your Notion account.

3. Approve the requested scopes in Slack's authorization flow.

4. Choose which channels the agent can access.

Custom Agents can run on different large language models. This lets you balance speed, cost, and quality. You can adjust the model over time if your workflow changes or you see different performance needs. Supported models include Claude, GPT, and Gemini. Auto is the recommended default.

To choose a model:

1. Open your agent's Settings.

2. Go to the Model section.

3. Select a specific model if you want consistent behavior, or select Auto to let Notion choose the best model per request.

4. Save.

Custom Agents behave like Notion pages when it comes to sharing with others in your workspace, with a few differences.

When shared, Agents can appear in the sidebar under an Agents section, in search results, and in any workspace area that lists or references agents.

To share an agent:

1. Open the Custom Agent page.

2. Click Share.

3. Add people, groups, or the entire workspace.

Agents use a simplified set of permission levels:

• Full Access Users with Full Access permissions to an Agent can configure instructions, triggers, access, and models, view and manage activity logs, and run or interact with the Agent.

• Can Edit Users with Can Edit permissions to an Agent can modify instructions and configuration and review activity.

• Can View and Interact Users with Can View and Interact permissions to an Agent can run the agent and chat with it and view the Settings page (Triggers, Instructions, Tools & Access) in read-only mode. They cannot edit or share the Agent.

Once your Custom Agent is built, it will appear in the sidebar. Every Custom Agent page has three core tabs. Use these tabs together to design, test, and maintain an agent over time.

1. Chat A private or shared 1:1 conversation area for that specific agent.

   • Useful for testing new instructions, asking the agent to run one-off tasks, and iterating on behavior.

2. Activity A log of every agent run visible for users with Full Access.

   • Logs include what triggered the run, actions taken, and any errors or failures.

3. Settings The control center for the agent.

   • The Settings panel includes Agent Instructions, Triggers, access permissions, and model selection.

1. Open the Agent page.

2. Go to the Settings tab.

3. Update Instructions, Triggers, access to pages, databases, and external tools, or model selection.

4. Save and publish your changes.

5. Use the Chat tab and the Activity tab to verify that the agent behaves as expected after edits.

To restore a previous version of your Custom Agent:

1. Open the Agent page.

2. Access Version history.

3. Review past versions to see:

   • Who made changes.

   • When they were made.

   • What changed in each version.

4. Select a version you want to restore.

5. Confirm to revert the agent to that version.