Tag: AI workflow

  • Error Handling and Fallbacks in Notion AI Workflows

    Error Handling and Fallbacks in Notion AI Workflows

    The 60-second version

    The default failure mode of a Notion agent is “stop.” That’s almost never what you want in production. Robust workflows define what happens for each kind of failure: agent times out, Worker fails, external API is down, the schema mismatched, the credit pool emptied. Each needs a planned response — retry, fall back to manual, escalate to human, log and continue. Without explicit handling, “the agent stopped working” becomes a mystery debug session.

    Five failure modes and their handling

    1. Agent timeout (rare but exists). A 20-minute Custom Agent run that doesn’t complete. Handling: log the timeout, surface to the human owner, don’t auto-retry (likely to repeat the same problem).
    2. Worker timeout (more common). Worker hits 30-second limit. Handling: structured error return from the Worker; agent decides whether to retry, partial-result, or fail. Don’t silently re-invoke.
    3. External API failure. API down, rate limited, or returning errors. Handling: retry with exponential backoff (max 3 attempts), then fall back to “external system unavailable” path with human notification.
    4. Schema mismatch. Agent expected JSON shape A, Worker returned shape B. Handling: validate at the boundary, log the mismatch, fall back to a default response, alert human to fix the schema drift.
    5. Credit exhaustion. Workspace credit pool hits zero (post-May 4). Handling: this is hard — the agent stops mid-execution. Mitigation is preventative: monitor credit consumption, alert at 75% of monthly budget, top up before zero.

    Three practical patterns

    The retry-with-backoff pattern.
    First attempt fails → wait 1 second, retry. Second fails → wait 4 seconds, retry. Third fails → escalate to human. Don’t retry indefinitely.
    The fallback-output pattern.
    When the primary path fails, return a known-safe default with metadata indicating it’s a fallback. Downstream consumers can check the metadata and decide whether to use the fallback or alert.
    The human-escalation pattern.
    Define clear handoff criteria. When the agent can’t complete, who gets pinged, with what context, in what channel? “Pings someone eventually” is not a plan.

    Logging requirements

    Production agent workflows need three log streams:
    – Action log: what the agent did and when
    – Error log: what failed, with enough context to diagnose
    – Decision log: when the agent chose between options, what it chose and why
    Without all three, debugging takes 10x longer than it should.

    Where this goes wrong

    1. Trusting the default failure behavior. “The agent stopped” is rarely the right response. Define explicit handling.
    2. Silent retries. Retries that don’t log produce mysterious “sometimes it works” behavior. Always log retry attempts.
    3. No credit monitoring. Hitting credit zero stops every agent in the workspace. Monitor consumption proactively.

    What to read next

    Workers in TypeScript, Multi-Agent Orchestration, Security Posture, ROI Math.

  • Multi-Agent Orchestration in Notion: When One Agent Hands Off to Another

    Multi-Agent Orchestration in Notion: When One Agent Hands Off to Another

    The 60-second version

    Single mega-agents are tempting and bad. Specialized agents in a sequence with clear handoffs are harder to design but much more reliable. The principle: each agent does one thing well and hands a structured result to the next. Three handoffs is about the practical limit before debugging becomes painful. Beyond three, refactor.

    Three orchestration patterns that work

    1. The pipeline pattern.
    Agent A produces structured output → Agent B consumes and produces → Agent C consumes and produces final result. Each agent’s output schema matches the next agent’s input schema. Clear linear flow.
    2. The router pattern.
    A routing agent decides which specialist agent should handle the request, then dispatches. Specialists are scoped tightly to their domain. The router doesn’t do work itself; it just routes.
    3. The reviewer pattern.
    A producer agent generates output. A reviewer agent checks against criteria and either approves or returns specific feedback. Iterates until approved or max-attempts hit.

    Three patterns that fail

    1. Recursive agent chains. Agent A calls Agent B which calls Agent A again. Debugging is awful. Don’t.
    2. Shared mutable state. Two agents writing to the same database row simultaneously. Race conditions and overwrites. Don’t.
    3. Implicit handoffs. Agent A produces unstructured text; Agent B parses it. The first format change breaks everything. Use structured handoffs.

    Designing the handoff contract

    The handoff between agents is the highest-risk surface. Three rules:
    – Define the schema explicitly. The output of Agent A is JSON-schema-validated input to Agent B.
    – Version the schema. Schema changes are breaking changes. Version like APIs.
    – Test the handoff in isolation. Mock Agent A’s output; test Agent B’s handling. Mock Agent B’s expected input; test Agent A’s production.

    Where orchestration goes wrong in production

    1. Cost compounds with depth. Each agent call consumes credits. A three-handoff workflow costs roughly 3x a single-agent workflow. Budget accordingly.
    2. Latency compounds too. A 5-second agent x 3 handoffs is 15 seconds end-to-end.
    3. Failure modes multiply. Agent A succeeds, Agent B fails, what happens? Define the failure handling explicitly.

    What to read next

    Workers for Agents in TypeScript, Building Your First Skill, Error Handling in Notion AI Workflows, Custom Agents vs Basic.

  • Workers for Agents in TypeScript: Patterns That Hold Up in Production

    Workers for Agents in TypeScript: Patterns That Hold Up in Production

    The 60-second version

    Workers reward a specific style of TypeScript: small, single-purpose, structured-input-and-output, well-typed. The constraints (30 seconds, 128MB, no state) push you toward this style automatically. Workers that hold up in production share patterns: typed input/output schemas, defensive HTTP calls with timeouts, structured error returns, no hidden side effects.

    Five production patterns

    1. Type your input and output.
    Type strictly. The agent works against the schema. Schema drift breaks the agent silently.
    2. Defensive HTTP with timeouts.
    External API calls inside a 30-second budget need their own timeouts. A 25-second API call leaves 5 seconds for everything else. Set explicit fetch timeouts shorter than the Worker timeout.
    3. Structured error returns instead of throws.
    Throw inside a Worker and the agent gets opaque failure. Return structured error objects and the agent can reason about the failure and respond gracefully.
    4. Idempotency where state matters.
    Workers have no persistent state, but they can hit external systems that do. If the external call is non-idempotent (e.g., creates a record), include an idempotency key derived from input. Calling the Worker twice should produce one record, not two.
    5. Approved domains as a deployment artifact.
    Track domain approvals in code. When a Worker stops working in production, “did the approved domains change” is the first thing to check.

    Three production failures to design around

    1. The 30-second wall. Aim for under 5 seconds typical, under 15 worst case. Long calls fail under retry loads.
    2. Silent domain blocks. A Worker calling a non-approved domain fails with an error that isn’t always obvious. Log every outbound destination.
    3. Memory leaks via large responses. Don’t pull a 50MB JSON response into a 128MB Worker. Stream, paginate, or pre-filter at the source.

    Testing strategy

    Unit-test the Worker logic separately from the agent. Use mock HTTP. Then integration-test with the actual agent calling the Worker. The two test layers catch different bugs.

    What to read next

    Workers + External APIs, Notion AI Meets MCP, Workers for Agents foundation piece, Security Posture.

  • Notion Agents vs n8n Alone: When the Workflow Belongs Inside Notion

    Notion Agents vs n8n Alone: When the Workflow Belongs Inside Notion

    The 60-second version

    This isn’t either-or. n8n is the deterministic workflow engine — when X happens, do Y across these 5 apps. Notion Agents are the reasoning layer — given the context, decide whether X actually warrants action and what the right action is. Combined via the n8n MCP bridge, they form a complete automation stack: agent reasons, n8n executes. Operators who treat them as competitors miss the leverage.

    When Notion Agents win

    • The workflow needs to read and synthesize Notion workspace content
    • Natural-language understanding of context matters
    • The “decide whether to act” question is the hard part
    • Schedule-driven autonomous work is the goal
    • The workflow output is itself in Notion

    When n8n wins

    • Pure cross-app data movement (no reasoning needed)
    • Hundreds of integration options matter
    • Visual workflow building with branching logic
    • High-volume deterministic automations
    • Workflows that don’t touch Notion at all

    The combined pattern

    The pattern that’s emerging:
    – Notion Agent decides what to do based on context
    – n8n workflow executes the cross-app coordination
    – Connected via the n8n MCP bridge inside Notion
    Example: Agent reads new lead in Notion → reasons whether it matches ICP → if yes, calls n8n workflow that updates Salesforce, sends Slack notification, schedules follow-up email.

    What n8n does that Notion Agents don’t

    • Massive integration catalog (Salesforce, Stripe, hundreds of others)
    • Visual flow building
    • High-throughput deterministic execution
    • Self-hosting option for compliance-sensitive use cases

    What Notion Agents do that n8n doesn’t

    • Natural-language understanding of unstructured workspace content
    • Native Notion database manipulation
    • Skills (saved natural-language workflows)
    • Workers for custom code execution
    • Schedule-driven autonomous reasoning

    Where this goes wrong

    1. Trying to do everything in one tool. Reasoning in n8n (limited) or deterministic execution in Notion Agents (expensive) is the wrong direction.
    2. Skipping the MCP bridge. Without it, you re-implement n8n integrations as Workers. Don’t.
    3. Letting agent reasoning replace simple n8n triggers. If the trigger is “row added to database,” that’s deterministic. Just use n8n.

    What to read next

    n8n MCP Bridge, Workers + External APIs, Notion AI vs Zapier, MCP foundation piece.

  • Google Drive + Notion AI: Bringing External Documents Into Agent Context

    Google Drive + Notion AI: Bringing External Documents Into Agent Context

    The 60-second version

    Most teams have content split between Notion and Google Drive. Drive holds the “I’m collaborating in real-time with five people” docs; Notion holds the structured workspace and database content. The Drive integration lets agents read across both. The result: synthesis that pulls from “the project doc in Drive” plus “the project page in Notion” plus “the related research in Notion’s research database” without manual copy-paste.

    Three patterns that work

    1. Cross-source synthesis. “Summarize the state of project X” pulls from the Notion project page, the Google Doc collaborators are working in, and the Sheets file with the metrics. Agent produces one synthesis from three sources.
    2. Drive-content-as-source for Notion drafts. Drafting a Notion document, agent pulls from a Drive Doc as reference. Useful when the source-of-truth lives in Drive but the deliverable lives in Notion.
    3. Migration assistance. Teams moving from Drive to Notion can use the integration to surface “what’s still in Drive that should be in Notion.” Helps the migration without forcing it.

    What stays manual

    • The actual collaboration in Drive (real-time editing isn’t an agent task)
    • Decisions about which content lives where (organizational, not synthesis)
    • Sensitive Drive content the agent shouldn’t see (don’t connect it)

    Permission inheritance

    The Drive integration uses the connected user’s permissions. The agent sees what you see. Two practical implications:
    – For org-wide Drive content, connect through an account with broad access
    – For personal Drive, connect your personal account; the agent sees only your stuff

    Where this goes wrong

    1. Connecting too broadly. A Drive integration that gives the agent access to your entire org’s Drive includes things you didn’t think about (HR docs, finance, executive). Scope tightly.
    2. Letting Drive content lag behind Notion content. When a Notion page is canonical, the agent should reference it, not the Drive doc. Mark canonical sources clearly.
    3. Treating Drive as substrate without organization. A messy Drive feeds an agent that produces messy synthesis. The Editorial Surface Area thesis applies to Drive too.

    What to read next

    Editorial Surface Area, Slack Integration, Calendar + Notion AI, MCP foundation piece.

  • Mail Integration: Drafting and Triaging Email From Inside Notion AI

    Mail Integration: Drafting and Triaging Email From Inside Notion AI

    The 60-second version

    Inbox triage is the highest-frequency, lowest-strategic-value work most knowledge workers do daily. Notion AI’s mail integration takes the operational layer off your plate. Agent reads inbox, categorizes incoming messages, drafts replies for routine items, and surfaces what actually needs your judgment. You review the drafts and send the ones that work. The inbox-zero ritual goes from 90 minutes to 15.

    Three mail integration patterns

    1. The triage and draft agent. Runs morning and afternoon. Categorizes inbox: requires response, FYI, junk, action item. For “requires response” items where context exists in Notion, drafts the reply. You review drafts and approve sends.
    2. The follow-up watcher. Watches sent messages. Flags conversations where you sent something and haven’t heard back in 5+ days. Drafts a follow-up. You review and decide whether to send.
    3. The inbox-to-database agent. When inbox content matches database criteria (new lead → CRM, support request → tickets, content pitch → editorial queue), agent extracts structured data and creates the database entry. Reduces manual entry.

    What stays human

    • Sending. Always.
    • Sensitive replies (HR, legal, conflict, confidential)
    • Initial emails to new contacts
    • Anything where voice matters more than content

    The send button stays human

    This is the rule. Agent integrations with mail should be read-and-draft, never autonomous send. The relationship cost of one wrong sent email exceeds the time savings of automating sends across hundreds of right ones. Don’t.

    Where this goes wrong

    1. Trusting drafts on relationship emails. Drafts to existing contacts you have history with risk missing nuance. Read these especially carefully before sending.
    2. Auto-categorizing too aggressively. “FYI” categorization can hide actual urgency. Sample-check the FYI bucket weekly.
    3. Letting follow-ups become spam. A follow-up after 5 days is reasonable. Three follow-ups in 10 days is harassment. Configure follow-up agents conservatively.

    Privacy posture

    Mail integration gives the agent significant access. Two practices:
    – Connect a personal mail account, not a shared inbox
    – Audit what the agent has read monthly via the Notion access logs

    What to read next

    Slack Integration, Calendar + Notion AI, AI-Native Company Patterns.

  • Calendar + Notion AI: Letting Your Agent Schedule and Prep Meetings

    Calendar + Notion AI: Letting Your Agent Schedule and Prep Meetings

    The 60-second version

    Calendar is the most repetitive coordination work in knowledge work. Notion AI’s calendar integration takes most of it off your plate. The agent reads your upcoming meetings, pulls related context from your Notion workspace, and drops a one-page brief in your inbox 30 minutes before. For scheduling, the agent suggests times based on your patterns and drafts the calendar invite. You confirm and send. Five minutes of coordination work compresses to thirty seconds of approval.

    Three calendar integration patterns

    1. The pre-meeting brief agent. Triggered 30-60 minutes before each external meeting. Pulls the relevant project page, prior meeting notes with these attendees, open action items, and any current context. Brief lands in your inbox or daily notes.
    2. The scheduling assist agent. When you need to schedule something, ask the agent. It reads your calendar, suggests times that match your patterns (e.g., afternoon for deep work, mornings for standup), and drafts the invite text. You review and send.
    3. The post-meeting capture agent. After meetings, agent prompts for quick voice or text capture. Processes the capture into structured updates: action items added to task database, decisions logged to project page, follow-ups scheduled.

    What stays human

    • Deciding which meetings to take
    • The conversations themselves
    • Final approval before scheduling sends
    • Any sensitive scheduling (interviews, terminations, board calls)

    Setup considerations

    The integration runs at the user level — your calendar connects to your agent. For shared calendars, the connection inherits the calendar’s permissions. Two practical notes:
    – The agent only sees what your calendar permissions show. Private events stay private to the agent.
    – For executive assistants managing multiple calendars, each calendar is a separate connection with separate agent context.

    Where this goes wrong

    1. Letting the agent send invites autonomously. Calendar invites have political weight. Always keep a human approval step.
    2. Trusting brief content for sensitive meetings. Performance reviews, terminations, sensitive client conversations — review the brief manually before relying on it.
    3. Overloading prep briefs. A 4-page brief is worse than a 1-paragraph brief because you don’t read it. Configure the agent to produce concise briefs by default.

    What to read next

    Slack Integration, Mail Integration, AI-Native Company Patterns, The Solo Operator’s Stack.

  • Notion AI for Knowledge Workers: The Personal Productivity Loadout

    Notion AI for Knowledge Workers: The Personal Productivity Loadout

    The 60-second version

    Most coverage of Notion AI focuses on team and company use. The individual knowledge worker case is just as compelling and significantly cheaper. Plus plan (\$10/user/month) gets you the inline AI, AI Q&A across your workspace, and meeting notes. That’s enough for most personal productivity workflows. The Custom Agent layer (Business plan) only matters when you have recurring autonomous work — which most individuals don’t, but some do. Match the plan to the actual use, not the marketing aspiration.

    The personal loadout

    1. Daily planning interaction. Each morning, ask Notion AI to summarize your calendar, recent notes, and active projects. Get a one-paragraph “here’s your day” briefing. No agent needed; standard inline AI handles this.
    2. Meeting prep. Before each meeting, ask Notion AI to pull relevant context for the topic and attendees. Standard AI Q&A works fine for personal use. The brief is conversational, not formatted, but that’s adequate for personal prep.
    3. Writing substantive documents. Open a doc, draft, then use the inline AI to tighten paragraphs, suggest counterpoints, summarize sections. The AI is a writing partner, not a ghostwriter — you direct, it executes.
    4. Second-brain navigation. Ask Notion AI to find that thing you wrote three months ago about X. Or to synthesize what you’ve thought about Y across multiple notes. This is where Notion AI outperforms ChatGPT — it knows your stuff.
    5. Quick capture. Use voice memos (mobile) or quick text (desktop) to drop thoughts into a daily notes database. Periodically ask AI to review and structure them into related projects or notes.

    When you do need Custom Agents

    Three personal use cases that earn the upgrade:
    – You produce content on a recurring schedule (newsletter, blog, podcast notes)
    – You manage a personal client roster (consulting, coaching) and want pipeline hygiene
    – You run multiple side projects and need cross-project synthesis automated
    If none of these apply, Plus plan is enough. Don’t upgrade for capability you won’t use.

    The privacy framing

    For individuals, the privacy story matters. Notion AI runs on your workspace content. It doesn’t expose that content to other users. For personal journaling, sensitive notes, or confidential client work, this is meaningfully better than a general-purpose AI.

    Where individuals go wrong

    1. Buying Business plan for capability they won’t use. If you don’t have recurring scheduled work, Custom Agents are wasted spend.
    2. Treating AI as a replacement for thinking. The value of personal notes is largely the thinking that happens during writing. AI shortcuts the writing, which can shortcut the thinking. Use AI for synthesis and recall, not for the original thinking.
    3. Importing too many sources too fast. A new Notion AI user often connects every source available. The agent then synthesizes from a noisy signal. Start with one or two well-organized databases and grow from there.

    What to read next

    Editorial Surface Area, Second-Brain Architecture, Custom Agents vs Basic.

  • Connecting Slack to Your Notion Agent: The Read-Summarize-Act Loop

    Connecting Slack to Your Notion Agent: The Read-Summarize-Act Loop

    The 60-second version

    Slack is where decisions happen. Notion is where decisions are documented. The gap between them is where things fall through. The Slack integration closes the gap by letting agents read what’s happening in Slack, summarize it into Notion, and draft outbound responses based on Slack threads. The pattern that works: read-summarize-act. Agent reads the Slack thread, summarizes the decision into the relevant Notion project page, and drafts the follow-up message back to Slack. The decision is documented and the follow-up is sent without manual handoff.

    Three Slack integration patterns

    1. The decision-capture loop. Agent watches designated #project channels. When a decision is made (signaled by patterns like “let’s do X” or explicit decision flags), agent appends the decision and context to the project page in Notion. Decisions stop being lost to Slack history.
    2. The status digest agent. Daily or weekly, agent reads activity in selected channels and produces a digest in a Notion page. Useful for managers tracking multiple teams without scrolling through hundreds of messages.
    3. The action item extractor. Agent watches conversations for action items (“can you do X by Friday”). Adds them to the relevant person’s task database. Drafts a confirmation message in Slack thread asking the person to confirm.

    What stays human

    • The conversations themselves
    • Decisions about what to do
    • Nuanced communication where tone matters
    • DMs and sensitive channels (don’t connect those)

    Permission and privacy

    Slack agent integration respects user-level permissions. The agent sees what the connected user sees. Two implications:
    – Don’t connect a junior account to a workspace agent — the agent inherits the junior’s limited view
    – Don’t connect an admin account that can see DMs unless you actually want the agent reading DMs (you don’t)
    The right pattern is a dedicated integration account with scoped channel access.

    Where this goes wrong

    1. Agents posting to Slack autonomously. This generates noise and damages trust fast. Configure agents to draft, not post. Humans review and send.
    2. Reading too many channels. The agent’s signal-to-noise ratio drops with channel count. Pick 3-5 relevant channels per agent. Add more later if useful.
    3. Trusting the action-item extractor without confirmation. Slack conversation is loose. “Can you” doesn’t always mean “I commit.” Always add a confirmation step.

    What to read next

    Calendar + Notion AI, Mail Integration, MCP, AI-Native Company Patterns.

  • Notion AI for Customer Success: QBRs, Health Scores, and Account Plans

    Notion AI for Customer Success: QBRs, Health Scores, and Account Plans

    The 60-second version

    CS work is constrained by CSM bandwidth. The bandwidth gets eaten by documentation: QBRs, account plans, health score updates, internal reporting. Custom Agents take that documentation work over so CSMs can spend their time on customer calls. The result is CS teams that cover more accounts at the same headcount or go deeper on the same accounts. Either way, the math improves.

    Four CS-specific agent patterns

    1. The QBR draft agent. Triggered before QBR season. For each account: pulls usage data (via integration), product adoption metrics, support ticket trends, key milestones, prior QBR action items. Drafts the QBR deck content in the team’s template. CSM customizes for the specific customer instead of building from scratch.
    2. The health score maintenance agent. Daily or weekly. Reads usage data, support patterns, engagement signals, NPS responses. Updates each account’s health score in the customer database. Surfaces accounts that dropped a tier in the last week.
    3. The account plan agent. Monthly per account. Reviews account activity, identifies expansion opportunities, surfaces stalled adoption areas, drafts the updated account plan with specific next-quarter goals.
    4. The renewal risk agent. Continuous. Scans accounts approaching renewal. Cross-references health score, recent engagement, support ticket sentiment, and upcoming contract dates. Flags 60-90 days before renewal so CSM has runway to address issues.

    What stays CSM

    • Customer conversations
    • Expansion negotiations
    • Crisis response when accounts are unhappy
    • The judgment about which accounts deserve which level of investment
    • Reading the customer relationship temperature
      The agent surfaces signals; the CSM interprets them.

    The leverage math

    A typical CSM covers 25-40 accounts. Documentation work consumes 30-40% of their week. Custom Agents take that to 10-15%. The CSM either covers more accounts (50-60) or goes deeper on the same accounts (more strategic, more frequent touch).
    The strategic question: which path matches your business? Higher coverage favors expansion-led businesses. Deeper accounts favor retention-led businesses. Don’t let agents accidentally pick the path for you by default.

    Where CS teams go wrong

    1. Letting agents update health scores autonomously into a “you’re red” customer-facing alert. Health scores have political weight inside the customer’s organization. Auto-flagging customers as red without human review can damage the relationship.
    2. Skipping the QBR review. The agent draft is starting material. The customization for that specific customer is what makes the QBR land. Don’t ship the agent draft as-is.
    3. Trusting renewal risk flags without context. A customer can look “at risk” by the data while being fine in the relationship. CSM context wins. Don’t escalate based on the agent flag alone.

    What to read next

    Notion AI for Sales Teams, Account Research, AI-Native Company Patterns.