Designing AI-Agent Onboarding That Actually Converts

SaaS activation funnels were built for human-only products. “Signed up, invited a teammate, created 3 things, upgraded.” AI products have an extra dimension: did the user actually let an agent do something? Without instrumenting that step, you are flying blind on what drives conversion. We built a 7-event funnel that includes agent activation. Here is the shape, the instrumentation, and the onboarding choices that move each step. The funnel is the spec. Once it is instrumented honestly, “what do we build next” answers itself.

AI-product activation is not the same as SaaS activation. A user signs up, creates a project, maybe invites a teammate — and then what? Did they connect an agent? Did the agent do anything? Did they hit the paywall before or after they saw value? Without instrumenting these steps explicitly, the funnel is invisible and “what do we build next” becomes a guessing game.

This is the funnel we landed on, the engineering pattern behind it, and the product decisions that map to each step.

Why agent activation is different from SaaS activation

Classic SaaS activation: user signs up, creates a thing, invites a teammate, comes back a second day. The “aha” is the product itself.

AI-product activation has an extra failure mode: the user signs up, creates a project, and never connects an agent. They use the product as a regular task tracker, never experience the differentiator, and churn thinking “this is just another kanban.” The agent connection step is the activation pivot, and most products do not instrument it.

If your “AI product” activation metric is “user created an account,” you are measuring the wrong thing.

The 7-event funnel

Our funnel, in order:

board_created — user created their first project
teammate_invited — user invited a human teammate
agent_connected — user connected an MCP agent (Cursor/Claude/OpenCode) OR invoked the built-in assistant
agent_action — agent performed a real operation (created/updated/moved a task)
quota_pressure — user hit the quota ceiling (signal of habit, see our paywalls vs quotas post)
checkout_started — user opened the pricing page or checkout flow
subscription_active — paid subscription is live

Steps 3 and 4 are the agent activation pivot. Steps 5 to 7 are the monetization pivot. The funnel splits cleanly: if users fall off between 1 and 3, the problem is onboarding. If they fall off between 4 and 7, the problem is pricing or perceived value.

Onboarding choices that move each step

Step	Product choice that moves it
`board_created`	Auto-provision a demo project on signup so the user starts on step 2, not step 1
`teammate_invited`	Show the team step in onboarding, but do not gate — solo users should still reach agent activation
`agent_connected`	3-step guide with prefilled MCP config; one-click “Connect Cursor” beats “here are the docs”
`agent_action`	Built-in assistant as fallback — users without an IDE agent can still reach this step via `/ai` in Telegram or the web panel
`quota_pressure`	Soft quota with visible usage surface (see paywalls vs quotas)
`checkout_started`	Paywall CTA only fires on quota exhaustion, not on first AI request
`subscription_active`	Stripe-managed checkout; idempotent; recovery emails

The single highest-leverage change was step 3: a guided agent-connect flow with a prefilled config snippet. “Here are the docs, good luck” converted terribly. “Click this, paste that, you are connected” converted materially better.

Instrumentation pattern

Three engineering decisions mattered:

One table, not one per event. A single ProductEvent table with (userId, eventName, occurredAt, metadata). Adding a new event is a row insert, not a schema migration.

Fire-and-forget emitter. Activation tracking must never block a request or fail the user action being tracked. Every event goes through an EventEmitter with a try/catch wrapper:

productEvents.emit("agent_action", { userId, boardId, action: "create_task" });
// emitter handles persistence async; failures log but never throw

emitOnce for first-time semantics. “First agent action” should fire once per user, not 200 times. A small helper:

async function emitOnce(userId: number, eventName: string, payload: any) {
  const exists = await db.productEvent.findFirst({
    where: { userId, eventName },
  });
  if (exists) return;
  await db.productEvent.create({ data: { userId, eventName, ...payload } });
  productEvents.emit(eventName, payload);
}

Race conditions are fine — a duplicate row in the rare case does not break the funnel report. Do not over-engineer the dedup.

What the funnel tells you

The day after we shipped the funnel report, two things became obvious:

Step 3 to 4 was our leakiest transition. Users connected an agent but never reached first agent action. The fix was surfacing example prompts in the assistant (“try: list my tasks”) rather than a blank input.
Step 5 to 6 was healthier than we assumed. Users who hit quota pressure converted at a reasonable rate. The paywall was not the problem we thought it was.

Both insights were invisible before instrumentation. The funnel is the spec.

FAQ

Q: How do I measure AI agent activation? A: Instrument a multi-event funnel that includes agent-specific milestones — agent connected, first agent action — alongside standard SaaS steps. Standard activation metrics miss the agent dimension entirely.

Q: What is an activation funnel for AI products? A: A sequence from signup to conversion that includes agent steps. Ours: board_created then teammate_invited then agent_connected then agent_action then quota_pressure then checkout_started then subscription_active.

Q: How do I track first-time events without double-counting? A: Use an emitOnce helper that checks for prior occurrence before firing. Subsequent occurrences are no-ops. Do not over-engineer dedup — a rare duplicate row does not break the funnel report.

Q: Should activation tracking be synchronous or asynchronous? A: Asynchronous, fire-and-forget. Tracking must never block or fail the user action being tracked. Wrap persistence in try/catch and log failures separately.

Q: How many events should my funnel have? A: Enough to localize the leak, no more. 5 to 8 events is the sweet spot. Beyond that, the report gets noisy and the marginal insight drops.

Conclusion

AI-product activation has an extra dimension SaaS activation does not: the agent. Without instrumenting agent connection and first agent action, you cannot tell whether users are churning because of onboarding, pricing, or never experiencing the differentiator at all. Build the funnel, ship the instrumentation, and the next-priority question answers itself.

→ How we replaced our paywall with a quota · Connect Cursor to Kangram via MCP · Building a unified AI assistant