Onboarding Steps

Rule

If a feature requires user-facing setup (API keys, OAuth, connecting a third-party service), register an onboarding step so it appears in the agent sidebar's setup checklist.

Onboarding must point users to a secure credential path; it must never encode the credential value in source, docs, fixtures, prompts, or generated content. For a provider represented in the workspace connection catalog, check the connection readiness and app grant first, then resolve credentials through the scoped workspace-connection helper. Only when no reusable connection exists should API keys and service tokens use registerRequiredSecret() from the secrets skill. For OAuth, check the scoped OAuth token store. Use deployment env vars only for deploy-level configuration, not per-user credentials.

Model onboarding around the logical connection outcome, not its individual fields. Because registerRequiredSecret({ required: true }) auto-injects a checklist item per registration, do not mark every credential/config field as required by reflex. Use one composite onboarding step or connection readiness check when several values are needed for one provider.

A custom setup page is appropriate only when it adds provider-specific prerequisites, sequencing, or health checks. Keep it as a thin guide over the shared settings, vault, OAuth, and action surfaces; never make it a second place that stores or manages credentials.

Registering a Step

import { registerOnboardingStep } from "@agent-native/core/onboarding";
import { hasOAuthTokens } from "@agent-native/core/oauth-tokens";

registerOnboardingStep({
  id: "gmail",
  order: 100,
  title: "Connect Gmail",
  description: "Grant read/send access.",
  methods: [
    {
      id: "oauth",
      kind: "link",
      primary: true,
      label: "Sign in with Google",
      payload: { url: "/_agent-native/google/auth-url" },
    },
  ],
  isComplete: async (ctx) =>
    ctx?.userEmail ? hasOAuthTokens("google", ctx.userEmail) : false,
});

See packages/core/docs/content/onboarding.md for method kinds and built-in steps.

Related Skills

• adding-a-feature — The four-area checklist; onboarding is often part of a new integration
• authentication — Most onboarding steps involve OAuth or credentials