Start here

SDK Configuration

Deeply integrate the Agent into your React app.

ModelNexProviderChat InterfaceAutomatic Element Detection (Optional)

ModelNexProvider

ModelNexProvider is the runtime contract between your app and ModelNex. It establishes identity, targeting, and access to internal tooling.

PropTypeDescription
websiteId Required string Unique project identifier for the current app or environment.
userProfile UserProfile Current user identity and audience fields used for targeting and progress state.
tsx
import { ModelNexProvider } from '@modelnex/sdk'

export function AppShell({ children, currentUser }) {
  return (
    <ModelNexProvider
      websiteId="prod_site_123"
      userProfile={{
        userId: currentUser.id,
        isNewUser: currentUser.createdAt > Date.now() - 86400000 * 7,
        type: currentUser.role,
      }}
    >
      {children}
    </ModelNexProvider>
  )
}

Browser-Activated Dev Mode

Inject window.__MODELNEX_DEV_MODE_KEY__ in the browser and let the SDK validate it against the backend before exposing the authoring tools.

tsx
<script>
  window.__MODELNEX_DEV_MODE_KEY__ = 'dmk_live_xxxxxxxxx'
</script>

<ModelNexProvider
  websiteId="your-website-id"
  userProfile={{
    userId: currentUser.id,
    type: currentUser.role,
    isNewUser: currentUser.isNewUser,
  }}
>
  <App />
</ModelNexProvider>

Chat Interface

Use ModelNexChatBubble when you want the assistant to feel native to your product rather than an external widget.

PropTypeDescription
theme object Theme overrides for colors, sizing, panel dimensions, and z-index.
welcomeMessage string Empty-state copy shown before the first interaction.
agentName string Display name of the assistant in the UI.
tsx
import { ModelNexChatBubble } from '@modelnex/sdk'

export function ChatIntegration() {
  return (
    <ModelNexChatBubble
      appName="Acme Corp Dashboard"
      agentName="Acme Assistant"
      welcomeMessage="Hi there. Ask me to navigate, explain a screen, or help with setup."
      placeholder="Type a command or ask a question..."
      defaultCommand="Show me my recent activity"
      theme={{
        accentColor: '#f59e0b',
        accentForeground: '#ffffff',
        panelWidth: '400px',
        panelMaxHeight: '700px',
        bubbleSize: '64px',
        borderRadius: '24px',
        zIndex: 9999,
      }}
    />
  )
}

Automatic Element Detection (Optional)

ModelNex can discover interactive elements automatically, but data-testid gives the agent a stable anchor for deterministic replay.

  1. Add data-testid to key buttons, links, and inputs.
  2. Map those test IDs to human-readable meanings in the Portal Patterns tab.
  3. Re-run recordings and previews after major DOM changes.
tsx
export function DashboardHeader() {
  return (
    <header>
      <button data-testid="nav-documents">Documents</button>
      <button data-testid="nav-templates">Templates</button>
      <button data-testid="user-settings">Account Settings</button>
    </header>
  )
}
View all guides Previous: Quickstart Next: Portal Configuration