agent-playbooks/notion-ai-agent-delegation.md

Delegating tasks to Notion AI Custom Agents via MCP

Tested 2026-09-23. Method for having Claude hand off tasks to Notion's published Custom Agents (not generic "Notion AI" — specific published agents in a workspace) through the Notion MCP connector.

Prerequisites

• Notion MCP connected with session tools available: notion-search-agents, notion-spawn-session, notion-wait-session, notion-send-message-to-session, notion-list-session-events, notion-search-sessions / notion-query-sessions, notion-stop-session.
• At least one published Custom Agent in the target Notion workspace. Unpublished/misconfigured agents exist in the list but fail at spawn time.
• If the agent needs to create/edit pages, it needs edit access granted to that specific agent on the target page/teamspace inside Notion's UI. This permission cannot be granted via MCP — it's Notion-side.

Workflow

1. Discover available agents

   notion-search-agents(scope: "workspace", limit: 20)
   

   Returns {url, name, description, icon} per agent. url is in the form agent://<spaceId>/<agentId> — required for spawning.

2. Spawn a session

   notion-spawn-session(agent_url: "agent://...", initial_message: "<task>")
   

   Returns {session_url, status: "running"} immediately (does not block). session_url format: session://<spaceId>/<sessionId>.

   Failure mode observed: an unpublished agent throws a clean 400 "Agent is not published or configured." — fails fast, no wasted session.

3. Wait for completion

   notion-wait-session(session_url: "...", seconds: 45)
   

   Polls up to seconds (max 60/call — call again if still running). Returns {status: "completed", message: "<agent's final output>"}.

4. Follow up in the same session (multi-turn)

   notion-send-message-to-session(session_url: "...", message: "<follow-up>")
   

   Session retains context — e.g. asking to shorten/revise a draft works correctly and keeps prior structure/formatting.

5. Inspect what the agent actually did

   notion-list-session-events(session_url: "...", count: 50)
   

   Returns a numbered event log: user.message, agent.tool_result (each internal tool call the agent made, with output), agent.message (final reply). Useful for verifying an agent's self-reported limitation is real rather than a hallucinated excuse — e.g. we saw an orchestrator agent actually check its own permission/module config before reporting it couldn't create a page.

Observed results (3 test agents)

Agent	Outcome
Single-purpose content agent (e.g. "LinkedIn Post Writer")	Completed cleanly in ~15-20s, good structured output, follow-up edits honored.
Unpublished/misconfigured agent	Spawn rejected immediately with clear error, no session created.
Orchestrator-type agent with only web-search permission	Ran, reasoned, self-reported blocked status with a specific ask (grant edit access to a named parent page) instead of failing silently or hallucinating success.

Takeaways

• Round-trip (spawn → wait → completed) is reliable and fast for self-contained generation/drafting tasks.
• Sessions are stateful — safe to iterate multi-turn rather than re-spawning.
• Agents accurately self-report permission scope; verify via notion-list-session-events if you want to confirm rather than trust.
• For anything requiring page writes, grant edit access to that specific Custom Agent on the target page/teamspace in Notion's UI first — this step lives outside MCP and cannot be done from here.
• Always run notion-search-agents before spawning; not every listed agent is actually usable.