Most AI agent demos die in the gap between the prototype and the database the company actually runs on. The agent works in a notebook, then it does not work in production because the data lives in seven systems, the schema drifts every week, and nobody owns the layer in between.
Building agents on Notion closes that gap. The agent reads from the same databases the team uses, calls external tools through MCP and the API, and writes the result back into the same record everyone else sees. The data layer and the operating layer are one thing. That is the unlock.
What a Notion agent actually is
A Custom Agent in Notion is a configurable worker with three parts. A trigger, which is either a schedule, a database change, or a manual run. A set of instructions, which describe the goal, the boundaries, and the tools the agent is allowed to use. And a set of connections, which are the Notion workspaces, external tools through MCP, and APIs the agent can call.
The agent runs in a loop. It reads, it plans, it acts, it writes back. The Notion workspace is its long-term memory. The page history is the audit trail.
Pick the right first agent
Founders ask which agent to build first. The honest answer is the one that fails safely. A first agent should have a tolerable error rate, a human reviewer in the loop, and a measurable output.
- 01Inbound lead enrichment. Reads new rows in the Contacts database, enriches with public data, scores against the ICP, assigns an owner.
- 02Meeting prep. Reads a calendar event, finds the related account in Notion, drafts a prep doc with context, recent activity and three suggested questions.
- 03Renewal radar. Runs weekly, finds accounts with a renewal in the next 90 days, ranks them by risk, posts a list with a recommended action per account.
- 04Inbox triage. Reads new emails in a shared inbox, classifies them, drafts a reply, leaves the send button to the human.
Avoid the trap of starting with a customer-facing agent in week one. The first agent should make a teammate's job easier, not a customer's experience riskier.
The two-week build
Every Notion agent we ship follows roughly the same arc.
- 01Week one, day 1 to 2. Map the workflow as it runs today. Who does what, in which tool, with which inputs and outputs. Write it down as a list of steps. This is the spec.
- 02Week one, day 3 to 4. Clean the data layer. The databases the agent will read from need consistent properties, a clear schema, and a few example records. Most agent failures are data failures.
- 03Week one, day 5. Build the agent. Pick a trigger, write the instructions, wire up the connections. Keep the first version narrow. One job, one output.
- 04Week two, day 1 to 3. Run it in shadow mode. The agent runs, writes the result to a draft property or a separate database, the human reviews. Track accuracy on 50 to 100 cases.
- 05Week two, day 4 to 5. Promote to production. Move the output into the live database. Keep the human review for one more sprint. Watch the metrics.
Two weeks to a production agent is realistic when the data layer is clean. If the data is a mess, the agent build is two days and the data work is two months. Be honest about which one you are in.
The three failure modes to design against
Hallucination. The agent confidently writes a wrong field. Mitigate with citation-required outputs, a confidence score property, and a human review step on anything below a threshold.
Drift. The schema changes, the agent silently breaks. Mitigate with a contract layer between the agent and the database, and an eval that runs weekly on a fixed set of records to catch regressions.
Cost. The agent runs on every page change and the bill quintuples in a month. Mitigate with a cheaper model on the first pass, an expensive model only on uncertain cases, and a hard ceiling on runs per day.
Evals, not vibes
Every production agent has an eval set. A list of 50 to 100 input records with a known correct output. Run the eval on every meaningful change to the instructions, the model, or the connected tools. Track accuracy as a number. Without this you are guessing.
The eval set is also the artifact you hand to the next engineer. It is the contract for what the agent is supposed to do.
What changes for the team
When a Notion agent goes live, the team's work shifts from doing the task to reviewing the agent's output. That is a real change. The first month is rough. By month two the team is faster than they were before the agent existed, and they have a list of three more agents they want next.
“The agents we ship that stick are the ones the team asked for after seeing the first one work. Top-down agent rollouts fail. Pull from the team works.”
- Elko Lemiso, Dissel AI
If you want help
We run a two-week Notion agent sprint with founders who want the first three agents in production without a six-month consulting engagement. The structure, the criteria, and what we cover live on the Notion AI operating system page. If your data layer is clean, the first agent is live in week two. If it is not, we will tell you that on the audit call.
