Custom Agents: Build Your Own AI Teammates

The standard Notion Agent responds when you ask it to. Custom Agents, the headline feature of Notion in 2026, go one step further: they are named, reusable AI teammates you configure once and that run on a schedule or a trigger. A Custom Agent has its own instructions, its own toolkit, and its own reason for existing, like "every Monday morning, compile last week's completed tasks into a status report." This lesson shows you how to think about, design, and safely run Custom Agents.

What You'll Learn

• What a Custom Agent is and how it differs from the on-demand agent
• The building blocks: name, instructions, tools, and triggers
• Realistic examples of agents worth building
• How the credit system works and how to control cost

A Reusable Teammate, Not a One-Off Request

When you use the standard agent, the request disappears once it is done. A Custom Agent is a permanent entity in your workspace. You give it a name, a system prompt describing its job, a set of tools it is allowed to use, and either a schedule or a trigger that starts it.

Custom Agents arrived with Notion 3.3 in early 2026 and let teams build specialized, repeatable AI workflows instead of re-typing the same request every week.

The Four Building Blocks

1. Name. Give it a clear, role-based name like Weekly Reporter, Inbox Sorter, or Onboarding Buddy so teammates know what it does.

2. Instructions. This is the agent's job description, its system prompt. Be explicit and include guardrails, for example: "You compile a weekly status report. Read the Tasks database, list tasks completed in the last 7 days grouped by project, and create a new page titled 'Weekly Report [date]'. Never delete or edit existing pages."

3. Toolkit. Decide which actions the agent may take, such as reading certain databases, creating pages, or using connected apps. Grant only what the job needs.

4. Trigger. Choose how it starts:

• A schedule — runs at a set time, like every Monday at 9am.
• An event trigger — runs when something happens, like a new row being added to a database.

Agents Worth Building

Some patterns pay for themselves quickly:

• Weekly status reporter — on a schedule, compiles completed work into a shareable report.
• Inbox sorter — when a new item lands in a capture database, reads it and assigns a project tag.
• Meeting prep agent — the morning of a meeting, gathers the relevant notes and drafts an agenda.
• Content repurposer — when a blog draft is marked "ready," produces a summary and a few social posts.
• Onboarding buddy — when a new person is added, creates their starter pages from a template.

Notice these are all recurring, rule-based jobs. That is the sweet spot: work that is predictable enough to define once and valuable enough to want done reliably.

The Credit System and Cost Control

Custom Agents are more powerful and more resource-intensive than single commands, so Notion meters them. As of 2026, Custom Agent usage runs on a credit system, priced around $10 per 1,000 monthly Notion credits on top of your Business or Enterprise seats, and credits do not roll over. Standard AI Agents and Ask Notion remain included in the Business plan; the metered credits apply to heavier Custom Agent usage.

Because pricing and packaging change, confirm the current details on Notion's pricing page before you commit a team to heavy automation. To keep costs sane:

• Scope tightly. An agent that reads one focused database costs less than one that scans your whole workspace every run.
• Right-size the schedule. A daily agent uses far more than a weekly one. Run it only as often as the job truly needs.
• Prefer triggers over frequent polling when you only need action on specific events.
• Monitor usage. Check how many credits your agents consume and prune ones that are not earning their keep.

Designing a Custom Agent Well

A few principles separate a reliable agent from a risky one:

1. One job per agent. A narrow, well-defined role is predictable. A vague, do-everything agent is not.
2. Guardrails in the instructions. Spell out what it must never do, especially around deleting or overwriting.
3. Test before scheduling. Run it manually a few times and review the output before you turn on the schedule.
4. Name and document it. Future teammates should understand what each agent does and why it exists.
5. Review periodically. Workspaces change; an agent built for an old process can quietly produce wrong output.

A Practical Exercise

Design (on paper or in a test workspace) a Weekly Reporter agent:

1. Name: Weekly Reporter.
2. Instructions: "Each Monday, read the Tasks database, list tasks completed in the last 7 days grouped by project, and create a page titled 'Weekly Report [date]'. Do not edit or delete existing pages."
3. Toolkit: read the Tasks database, create pages.
4. Trigger: schedule for Monday 9am.
5. Run it manually once and review the report before enabling the schedule.

That is a complete, safe Custom Agent design, and the template applies to any recurring job you want to automate.

Key Takeaways

• A Custom Agent is a named, reusable AI teammate with its own instructions, toolkit, and trigger, unlike the on-demand agent.
• The four building blocks are name, instructions (its system prompt with guardrails), toolkit, and trigger (a schedule or an event).
• The best agents automate recurring, rule-based jobs like weekly reports, inbox sorting, and meeting prep.
• Custom Agents run on a metered credit system as of 2026, so scope them tightly, right-size the schedule, and monitor usage.
• Give each agent one clear job, add guardrails, test before scheduling, and review it periodically.