SDK Overview

@appilots/sdk is a React Native package that embeds an AI chat UI in your app and gives an AI agent the ability to navigate screens, read what's on them, and operate them — pressing buttons, filling forms, flipping switches — on the user's behalf.

This page covers installation, the package's export surface, and the optional Metro plugin. For the actual wiring, continue to AppilotsProvider and AppilotsChat.

Requirements

@appilots/sdk declares these as peer dependencies — install them if your app doesn't already have them:

Package	Minimum version
react	>=18.0.0
react-native	>=0.72.0
react-native-safe-area-context	>=4.0.0
react-native-svg	>=13.0.0

Installation

npm install @appilots/sdk

yarn add @appilots/sdk

pnpm add @appilots/sdk

Metro plugin (recommended)

The SDK ships a Metro plugin that auto-loads your .appilotsrc file at bundle time. With it configured, AppilotsProvider needs zero props — no projectId or apiKey hardcoded in your app code.

metro.config.js

const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const { withAppilots } = require('@appilots/sdk/metro');

const config = {};

module.exports = withAppilots(mergeConfig(getDefaultConfig(__dirname), config));

See CLI configuration for the .appilotsrc file format. If you skip the Metro plugin, pass config explicitly to AppilotsProvider instead — both paths are covered in AppilotsProvider.

Package exports

The main entry point (@appilots/sdk) re-exports everything the SDK has to offer. Two narrower subpaths exist for consumers who want a smaller import surface — they don't expose anything the root doesn't already have:

Subpath	Contents
@appilots/sdk	Everything below — the main entry point.
@appilots/sdk/navigation	Just the navigation exports (AppilotsNavigationContainer, registerScreen, navigation types).
@appilots/sdk/hooks	Just the hooks (useAppilots, useAppilotsField, etc).
@appilots/sdk/metro	The Metro plugin (withAppilots), CommonJS only, used from metro.config.js.

What's exported

Group	Exports	Purpose
Provider	AppilotsProvider, useAppilotsContext, AppilotsConfig	Root context — see AppilotsProvider.
Chat	AppilotsChat and its prop types	The chat UI — see AppilotsChat.
Theming	AppilotsThemeProvider, useAppilotsTheme, defaultLightTheme, defaultDarkTheme, mergeThemeTokens, appilotsTheme, appilotsThemeFromTailwind	Token-based theming — see Theming.
i18n	AppilotsI18nProvider, useAppilotsI18n, detectDeviceLocale, resolveLocale	Locale detection and string bundles — see Customization: i18n.
UI pieces	ConfirmDialog, ActionBreadcrumb, ChatIcon, HeadsetIcon	Standalone components you can reuse in a custom chat surface.
Hooks	useAppilots, useAppilotsNavigation, useAppilotsChat, useAppilotsActions, useAppilotsField, useAppilotsTarget, useAppilotsToggle, useAppilotsSlider, useSuggestedPrompts	Read/write access to chat state, navigation state, and the component registry — see Hooks and Registering elements.
Navigation	AppilotsNavigationContainer, registerScreen, ScreenMetadata, NavigationConfig	Screen-level metadata for the agent — see Navigation.
Registry	componentRegistry, elementRegistry, listRegistry, createComponentRegistry, createElementRegistry, createListRegistry, AppilotsRegistryProvider, useResolvedRegistry	The low-level registry that the hooks, HOCs, and auto-tracking all write into. Most apps never touch this directly — the singleton registry is used automatically unless you explicitly scope a subtree with AppilotsRegistryProvider.
Config loading	initAppilots, getGlobalConfig	Reads .appilotsrc at runtime (used by the Metro plugin path).
Auto-tracking	enableAppilotsAutoTracking, isAutoTrackingEnabled	Zero-config component registration — see Registering elements.
Runtime snapshot	captureSnapshot and its type exports	Internal runtime snapshot used to build the agent's context of the current screen.
HOC factories	createAppilotsInput, createAppilotsButton, createAppilotsSwitch	Wrap a shared component once so every usage auto-registers — see Registering elements.
Executor	executeAction, ExecutorContext, ActionResult	The low-level action executor that the hooks and auto-tracking build on.
HTTP client	AppilotsClient	The client the provider builds from your config — see API Reference for the wire contract.
Core types	AgentAction, AgentActionType, AgentMessage, AgentPermissions, ChatMessage, FormFillPayload, NavigationPayload, UIInteractionPayload, AppilotsEvent, AppilotsEventType, AppilotsEventHandler, AppilotsTraceEntry, EscalationState, MessageRole	Shared TypeScript types used across the public API.
Version	SDK_VERSION	The installed SDK version string.

Next steps

• AppilotsProvider — wrap your app and configure the SDK.
• AppilotsChat — drop in the chat UI.
• Navigation — describe your screens to the agent.
• CLI overview — generate and sync the MCP document your project needs before the agent can do anything useful.