Notion Custom Agents can turn recurring knowledge work into a shared, background workflow. The difficult part is not creating an agent page. It is designing a bounded job that runs on the right events, reads only the right sources, writes a predictable result, exposes enough evidence for review, and stays inside an intentional credit budget.
This guide presents a production design for Custom Agents: job contract, permissions, triggers, output schema, test matrix, operating controls, and total cost.
A production agent needs explicit contracts for outcome, trigger, access, procedure, output, review, and budget.
The short answer
A reliable Notion Custom Agent needs seven explicit contracts:
Job: one recurring outcome with a clear completion condition.
Trigger: a schedule or event narrow enough to avoid irrelevant runs.
Access: the minimum pages, databases, Slack channels, and tools required.
Instructions: ordered steps, decision rules, stop conditions, and examples.
Output: a stable destination and schema with owner, evidence, and status.
Review: activity inspection, permission tests, failure handling, and rollback.
Budget: expected runs multiplied by measured cost per run, with a workspace limit and pause plan.
If any of these are implicit, the agent may appear useful in a demo while remaining unsafe or expensive in production.
What a production Custom Agent actually is
A Custom Agent is a specialized team agent inside Notion. It can run from recurring schedules, Notion events, and selected Slack events; use explicitly granted Notion and connected sources; take actions; and expose its configuration and run history through Settings, Chat, and Activity.
The correct mental model is not “a long prompt.” It is a small operated service whose control plane happens to live in Notion.
Service concept | Custom Agent equivalent |
|---|---|
Service purpose | Job and outcome in Instructions |
Event subscription | Recurring, Notion, or Slack trigger |
Service identity | The Custom Agent and its granted access |
Input contract | Pages, database properties, channels, and tools |
Business logic | Instructions, examples, and selected model |
Output contract | Record, report, message, or page schema |
Observability | Activity log, Insights, errors, credit dashboard |
Deployment | Save and publish |
Rollback | Version history or disable the agent |
Capacity budget | Notion credits and workspace limits |
This framing forces a team to make operating decisions before granting broad access or enabling background runs.
Start with a job contract
Write the job contract before opening the agent builder.
A useful contract answers:
What business event creates work?
What exact result should exist when the run is complete?
Which source is canonical when information conflicts?
Which actions are allowed?
Which actions require human review?
Where does evidence appear?
What causes the agent to stop without writing?
Who owns quality and access?
What volume and cost are acceptable?
Weak contract
“Watch support issues and help the team.”
This leaves severity, scope, destination, evidence, and completion undefined.
Strong contract
“When a record enters the ‘Needs triage’ view, read the issue description and linked customer context, assign one severity from the approved rubric, propose an owner, create a triage checklist, and set ‘Agent review’ to Ready. If the source lacks customer impact or reproducible evidence, set ‘Agent review’ to Needs information and do not assign severity.”
The strong version defines the event, sources, allowed decisions, output fields, and safe failure state.
Step 1: design the input boundary
Custom Agents use only content and tools explicitly granted through Tools and access. Linking a page in Instructions does not itself grant access.
Create an input inventory:
Input | Why it is needed | Required access | Canonical? | Sensitivity |
|---|---|---|---|---|
Intake database | Trigger and work record | Read/write | Yes | Internal |
Severity rubric | Classification policy | Read | Yes | Internal |
Customer account page | Impact context | Read | Reference | Restricted |
Slack escalation channel | Clarifying context | Read | No | Restricted |
Triage output fields | Store result | Write | Yes | Internal |
Then remove every input that is merely convenient.
Broad access increases three risks:
The agent may retrieve irrelevant or contradictory context.
A person interacting with the agent may receive information from sources they cannot open directly.
More retrieval and reasoning can increase usage cost.
Start with a small source set and expand only when observed failures prove another source is necessary.
Step 2: choose the right trigger
Notion currently documents recurring schedules, Notion workspace events, and Slack events.
Recurring schedules
Use a schedule when the job is naturally a batch:
Weekly project summary.
Daily sales or support brief.
Monthly policy review.
Morning market-intelligence digest.
Specify cadence, time, and timezone. A daily run should define whether it processes all records or only changes since the previous operating window.
Notion events
A Custom Agent can respond when a page is added to a database, a property changes, a page is removed, or a comment is added.
Use a filtered event when one state transition creates the job. For example:
Status becomes “Needs triage.”
A record appears in a specific view.
A review comment contains a designated phrase.
Avoid “any property changed” unless every change truly requires work.
Slack events
After administrators connect Slack and authorize channels, triggers can watch messages, reactions, mentions, and optionally thread replies.
Use keyword, channel, or mention filters to reduce noise. Anyone in a channel may see messages the agent posts there, so channel selection is also an output-permission decision.
A dedicated eligible state and an excluded final state prevent the agent's own write from re-entering the workflow.
Prevent trigger loops
A common failure occurs when an agent's own write satisfies its trigger again.
Example:
Trigger: any update to the Requests database.
Agent writes classification and owner.
The write creates another update event.
The agent runs again.
Notion's public documentation describes trigger filters, but it does not promise a universal exactly-once or idempotency mechanism for every Custom Agent workflow. Design a guard in the workflow state:
Trigger only when Status equals “Needs triage.”
First write a processing marker if the workflow supports it.
End in a state excluded from the trigger view.
Record a stable source identifier and last processed state.
Use an external queue or deterministic workflow engine when strict exactly-once processing is required.
Step 3: define the agent's permission model
Custom Agent security has two layers.
Resource access
Tools and access determines which Notion pages, databases, connected apps, and external tools the agent can use.
Separate read and write needs. A reporting agent may need broad read access but only one write destination. A routing agent may need to update a small set of properties but should not edit the policy that governs the routing decision.
Agent sharing
The agent itself is shared with people or groups. Notion currently documents Full Access, Can Edit, and Can View and Interact levels.
These permissions determine who can change configuration, inspect activity, invoke the agent, or interact with it.
Review the combined boundary
A user can interact with a Custom Agent whose source access differs from the user's direct access. Notion explicitly describes this as a supported coordination pattern.
That means the review question is not merely “Can this user open the page?” It is:
Can this user cause the agent to retrieve or reveal information from that page?
Test with users who have different direct access:
Agent owner.
Agent editor.
Interaction-only user.
User without direct access to one source.
User who should not be able to invoke the workflow.
User in a connected Slack channel.
Inspect both the response and every written output.
Step 4: write instructions as an executable procedure
Good instructions are ordered, bounded, and testable.
Use this structure:
Role
Name the job, not a personality.
“You are the launch-risk review agent for active product launches.”
Trigger context
State what event or schedule starts the run and which record or time window is in scope.
Sources
List the canonical pages, databases, properties, channels, and tools. Define precedence when sources disagree.
Steps
Write the procedure in order:
Validate required inputs.
Retrieve only relevant evidence.
Apply the approved decision rules.
Produce the output schema.
Link evidence.
Set the final workflow state.
Stop.
Decision rules
Define allowed categories, thresholds, and escalation conditions. Avoid asking the model to invent policy.
Output schema
Name the destination and required fields. State what must not be changed.
Stop conditions
Examples:
Required field missing.
Evidence sources disagree.
Proposed action affects a protected system.
Confidence is below the review threshold.
Estimated output would expose restricted content.
No records match the operating window.
Examples
Include representative success, missing-information, and conflicting-evidence examples. Examples reduce ambiguity more effectively than adding adjectives such as “careful” or “high quality.”
Step 5: make the output reviewable
An agent output should prove what happened.
A strong structured record includes:
Source record ID.
Trigger time.
Agent version or review date.
Decision or output status.
Assigned owner.
Evidence links.
Assumptions.
Missing information.
Action taken.
Human review state.
Error or stop reason.
For narrative reports, use a stable section order:
Summary.
Changes since the previous period.
Risks.
Decisions needed.
Owners and dates.
Evidence.
A stable schema makes runs comparable and lets humans identify drift.
Step 6: choose a model intentionally
Notion allows teams to select a model or use Auto. Model choice affects behavior, latency, and credit usage.
Use a small representative test set rather than assuming the largest model is always best.
Test:
Classification accuracy.
Evidence fidelity.
Instruction following.
Structured-output consistency.
Tool use.
Error behavior.
Credits per successful outcome.
A cheaper model that requires frequent manual repair may be more expensive operationally. A larger model used for a deterministic extraction task may waste credits. Measure the complete mission.
Notion also documents that administrators may need to enable certain models because of data-handling differences. Model governance is therefore part of the workspace rollout, not merely a per-agent preference.
Step 7: build a realistic cost model
Custom Agents require Business or Enterprise and consume Notion credits.
Use this formula:
Monthly Custom Agent cost = average cost per run × eligible trigger events per month
Then calculate the business metric:
Cost per completed outcome = monthly agent cost ÷ accepted outputs
Official Notion examples currently estimate approximate per-run ranges such as:
Workflow | Approximate cost per run |
|---|---|
Q&A | $0.03–$0.11 |
Task routing | $0.05–$0.15 |
Status update | $0.08–$0.18 |
Mail triage | $0.04–$0.10 |
Daily brief | $0.10–$0.30 |
Actual usage depends on model, steps, retrieval, tools, and run frequency.
Forecast a range
For 1,000 eligible routing events per month:
Low estimate: 1,000 × $0.05 = $50.
High estimate: 1,000 × $0.15 = $150.
If only 700 outputs are accepted without repair, the effective cost per accepted outcome is about $0.07–$0.21 before labor.
Control the demand side
Cost optimization begins with trigger quality:
Filter irrelevant events.
Batch work that does not require immediate response.
Reduce redundant sources.
Stop early when required inputs are missing.
Use the least expensive model that passes the mission.
Prevent write-trigger loops.
Retire agents that produce no adopted output.
A credit cap is safe only when new events remain visible, urgent work has a human path, and replay will not duplicate completed outcomes.
Plan for credit exhaustion
Notion documents workspace credit allocation and automatic pauses when a workspace reaches its limit. An in-progress task may finish, but new tasks do not begin after the cap is reached.
Every production workflow needs a pause plan:
Which queue accumulates while the agent is paused?
Who receives the alert?
Which human process takes over?
How are missed events replayed?
How is duplicate processing prevented after resumption?
A workflow is not production-ready if credit exhaustion silently drops business work.
Step 8: test before publishing
Use a test matrix that covers behavior and permissions.
Test | Expected evidence |
|---|---|
Happy path | Correct output fields and evidence links |
Missing required input | Safe stop state; no unsupported decision |
Conflicting sources | Escalation instead of silent source selection |
Irrelevant event | No action or filtered trigger |
Duplicate event | No duplicate final record |
Agent writes to source | No trigger loop |
Restricted source | No unauthorized direct or indirect disclosure |
Unauthorized user | Cannot reconfigure or invoke beyond policy |
Tool failure | Error visible; no partial unsafe write |
Credit limit reached | Queue and human fallback remain clear |
Owner leaves | Ownership transfer keeps or intentionally stops service |
Version rollback | Previous behavior can be restored |
Run the tests in Chat where possible, then publish to a controlled scope and inspect Activity after real triggers.
Step 9: operate through Chat, Activity, and Settings
Notion documents three core tabs for a Custom Agent:
Chat: test one-off runs and refine behavior.
Activity: inspect triggers, actions, errors, and failures.
Settings: manage instructions, triggers, tools and access, and model selection.
Use them as an operating loop:
Observe an accepted or failed run.
Identify whether the cause is trigger, scope, instruction, model, or source quality.
Change one variable.
Test against the same example.
Publish.
Inspect new real runs.
Record the change and expected effect.
Version history provides a recovery path when a configuration change degrades behavior.
Step 10: define ownership and offboarding
A production agent needs:
Business owner for the outcome.
Configuration owner with Full Access.
Data owners for every source and output.
Security reviewer for cross-permission behavior.
Budget owner for Notion credits.
Backup owner.
Notion documents ownership transfer and states that an agent stops running after seven days without an owner. Add Custom Agents to the employee offboarding checklist.
Also review duplicated agents carefully. Notion notes that a duplicate starts private and does not inherit every connection, run history, Worker configuration, or credit limit. A copy is not automatically a production clone.
Three production workflow patterns
1. Request triage
Trigger: New record enters “Needs triage.”
Inputs: Request, customer impact, routing policy.
Output: Category, priority proposal, owner proposal, evidence, review state.
Human gate: High-severity or ambiguous requests require approval.
Cost control: Do not run until required intake fields exist.
2. Weekly project status
Trigger: Friday schedule.
Inputs: Active project database, recent updates, risk log.
Output: Changes, risks, decisions needed, owners, links.
Human gate: Project lead reviews before external distribution.
Cost control: Query active projects and the current time window only.
3. Knowledge maintenance
Trigger: Review date or scheduled cadence.
Inputs: Canonical policy page, owner, linked change sources.
Output: Confirmed current, proposed revision, or owner escalation.
Human gate: Agent never publishes policy changes without owner approval.
Cost control: Skip records already verified in the review window.
Common failure modes
Agent has broad workspace access
Result: irrelevant retrieval, increased disclosure surface, and higher reasoning cost.
Fix: grant a focused source set and expand from evidence.
Trigger is broader than the business event
Result: unnecessary runs and possible loops.
Fix: filter on a dedicated status, view, keyword, or schedule.
Output is free-form
Result: humans cannot compare runs or measure completion.
Fix: define fields, states, evidence, and stop reasons.
Agent writes policy and applies policy
Result: the same identity can change the governing rule and execute it.
Fix: keep policy read-only and route policy changes to an owner.
Cost is measured per run only
Result: cheap but unusable outputs look efficient.
Fix: measure accepted outcomes and manual repair.
Activity is reviewed only after an incident
Result: drift and silent failures accumulate.
Fix: sample runs and errors on a defined cadence.
Credit pause has no fallback
Result: event-driven work stops without an operational queue.
Fix: maintain a visible backlog and replay procedure.
When to connect external tools or MCP
Use connected apps or MCP when the job genuinely requires an external action or source. Treat every connection as an additional permission and failure boundary.
Document:
Authentication owner.
Allowed tools.
Read and write scopes.
Expected inputs and outputs.
Rate and usage limits.
Error and retry behavior.
Secret or sensitive-data handling.
Revocation procedure.
Do not use an agent as a substitute for deterministic infrastructure when the workflow requires strict transactions, high throughput, or exactly-once guarantees.
A launch checklist
Before publishing a Custom Agent:
One job and one owner are named.
Trigger matches the real business event.
Trigger cannot be re-fired by the agent's own output.
Minimum source and tool access is granted.
Agent-sharing permissions are reviewed with resource access.
Output destination and schema are defined.
Stop and escalation conditions are explicit.
Happy, missing, conflicting, duplicate, and unauthorized cases pass.
Activity owner and review cadence are assigned.
Cost range and workspace credit limit are set.
Credit-pause fallback is documented.
Version rollback and disable procedure are known.
Ownership transfer is in the offboarding process.
Frequently asked questions
What are Notion Custom Agents?
They are specialized AI teammates configured inside Notion with instructions, triggers, explicit source and tool access, sharing permissions, model selection, and run history.
Which plans include Custom Agents?
Notion currently requires Business or Enterprise. Agent runs consume Notion credits.
Can Custom Agents run automatically?
Yes. Notion documents recurring schedules, Notion events, and Slack events.
Do Custom Agents have full workspace access?
Not by default. Owners grant pages, databases, and connected tools through Tools and access.
Can a user receive information from a source they cannot open?
Yes, if the user can interact with an agent that has access to the source. Review agent access and agent-sharing permissions together.
How do I stop a trigger loop?
Use a dedicated eligible state, a filtered view, and a final state excluded from the trigger. Use external deterministic infrastructure if the workflow requires strict idempotency.
How do I estimate cost?
Measure actual credits per representative run, multiply by eligible monthly events, then divide by accepted outcomes.
What happens when credits run out?
Notion documents that Custom Agents pause when the relevant credit limit is exhausted. New work needs a queue and fallback until credits are restored.
Can I roll back a Custom Agent change?
Notion provides version history for reviewing and restoring prior configurations.
Sources
Where Dokki fits
Dokki can hold the workflow brief, source material, structured state, approval gates, and agent output together. Use it to model the same Custom Agent mission end to end, then compare permission clarity, review burden, failure recovery, and cost per accepted result.
_Last verified: July 21, 2026._
Continue with What are Notion Agents? Personal vs Custom Agents, Notion AI credits explained, and Notion MCP capabilities and limits.