Skip to content

api-reference.md

Latest commit

 

History

History
321 lines (257 loc) · 9.95 KB

api-reference.md

File metadata and controls

321 lines (257 loc) · 9.95 KB
Raw

API Reference

This page summarizes the main public APIs exported by @mobileai/react-native.

Components

AIAgent

AIAgent wraps your app and provides the assistant runtime, chat UI, screen inspection, navigation access, guardrails, registered actions, and support features.

import { AIAgent } from '@mobileai/react-native';

<AIAgent analyticsKey="mobileai_pub_xxxxxxxx">{children}</AIAgent>;

Provider And Networking

Prop Type Notes
analyticsKey string Publishable MobileAI project key. Enables hosted proxy, analytics, knowledge, and support features.
provider 'gemini' | 'openai' Text provider. Default: 'gemini'.
apiKey string Local prototyping only. Do not ship provider keys in production apps.
proxyUrl string Backend proxy URL for production provider calls.
proxyHeaders Record<string, string> Headers sent to proxyUrl.
voiceProxyUrl string Optional WebSocket URL for voice mode.
voiceProxyHeaders Record<string, string> Headers sent to voiceProxyUrl.
model string Provider-specific model name.

Navigation And Screen Context

Prop Type Notes
navRef any React Navigation or Expo Router navigation container ref.
router { push; replace; back } Expo Router imperative router.
pathname string Current Expo Router pathname.
screenMap ScreenMap Generated ai-screen-map.json.
useScreenMap boolean Include screen map in prompts. Default: true.
transformScreenContent (content) => string | Promise<string> Mask or rewrite screen content before provider calls.

Behavior

Prop Type Notes
interactionMode 'companion' | 'copilot' | 'autopilot' Default: 'copilot'.
enableUIControl boolean Disable UI-control tools when false.
maxSteps number Maximum agent steps per user request.
stepDelay number Optional delay between steps.
maxTokenBudget number Stop when estimated task tokens exceed this value.
maxCostUSD number Stop when estimated task cost exceeds this value.
debug boolean Enable SDK logs.
interceptNativeAlerts boolean Expose native alert buttons as assistant targets.

Interaction mode behavior:

Mode Runtime behavior
companion Registers guidance/data/support tools and blocks UI-effect tools such as tap, type, scroll, navigate, guide_user, and rich UI injection tools.
copilot Registers UI tools and enforces approval plus semantic action safety before execution.
autopilot Registers UI tools for trusted automation flows. Configure safety explicitly for any risky workflow.

Safety

Prop Type Notes
consent AIConsentConfig Consent is required by default.
actionSafety ActionSafetyConfig Semantic action safety configuration.
toolStabilization ToolStabilizationConfig Snapshot-based stabilization after UI tools.
verifier VerifierConfig Optional outcome verifier for critical actions.
interactiveBlacklist React.RefObject<any>[] Refs the assistant must not interact with.
interactiveWhitelist React.RefObject<any>[] Restrict assistant interaction to listed refs.

Knowledge, Tools, And Actions

Prop Type Notes
knowledgeBase KnowledgeBaseConfig Static entries or retriever for app knowledge.
knowledgeMaxTokens number Default: 2000.
customTools Record<string, ToolDefinition | null> Add, override, or remove tools. null removes a built-in tool.
mcpServerUrl string WebSocket URL for the MCP bridge.
instructions { system?; getScreenInstructions? } App-specific system and per-screen instructions.

UI

Prop Type Notes
showChatBar boolean Default: true.
accentColor string Quick color for the chat UI.
theme ChatBarTheme Chat UI theme tokens.
blocks Array<BlockDefinition | React.ComponentType<any>> Rich content blocks available to the assistant.
richUITheme RichUIThemeOverride Rich UI theme tokens.
richUISurfaceThemes Partial<Record<'chat' | 'zone' | 'support', RichUIThemeOverride>> Per-surface rich UI tokens.
blockActionHandlers Record<string, BlockActionHandler> Handlers for interactive rich blocks.
showDiscoveryTooltip boolean Default: true.
discoveryTooltipMessage string Custom discovery tooltip text.

Support And Analytics

Prop Type Notes
supportStyle 'warm-concise' | 'wow-service' | 'neutral-professional' Default: 'warm-concise'.
userContext { userId?; name?; email?; phone?; plan?; custom? } User profile for support and analytics.
pushToken string Device push token for offline support replies.
pushTokenType 'fcm' | 'expo' | 'apns' Push token type.
analyticsProxyUrl string Enterprise analytics proxy.
analyticsProxyHeaders Record<string, string> Headers for analytics proxy.
proactiveHelp ProactiveHelpConfig Proactive help configuration.
customerSuccess CustomerSuccessConfig Health score and adoption tracking.
onboarding OnboardingConfig Guided onboarding journey configuration.

Lifecycle Callbacks

Prop Type
onResult (result: ExecutionResult) => void
onBeforeTask () => void | Promise<void>
onAfterTask (result: ExecutionResult) => void | Promise<void>
onBeforeStep (stepCount: number) => void | Promise<void>
onAfterStep (history: AgentStep[]) => void | Promise<void>
onTokenUsage (usage: TokenUsage) => void

Hooks

useData

Registers an app data source.

useData(
  name: string,
  description: string,
  schema: Record<string, string | DataFieldDef> | undefined,
  handler: (context: { query: string; screenName: string }) => Promise<unknown> | unknown,
  deps?: React.DependencyList
): void;

useAction

Registers an app-owned action.

useAction(
  name: string,
  description: string,
  parameters: Record<string, string | ActionParameterDef>,
  handler: (args: Record<string, any>) => any,
  deps?: React.DependencyList
): void;

useAI

Reads the current assistant state and sends messages from custom UI.

const {
  send,
  isLoading,
  status,
  lastResult,
  messages,
  clearMessages,
  cancel,
} = useAI();

You can temporarily disable UI control for a subtree:

const { send } = useAI({ enableUIControl: false });

Guardrail Types

ActionSafetyConfig

interface ActionSafetyConfig {
  enabled?: boolean;
  classifier?: ActionSafetyClassifier | 'default' | false;
  guardModel?: 'auto' | string;
  classifierTimeoutMs?: number;
  minConfidenceToAllow?: number;
  unknownActionDecision?: 'ask' | 'block';
  approvalReuse?: 'risk-boundary' | 'workflow' | 'none';
  userOverride?: {
    allowAskDecision?: boolean;
  };
  overrideDecision?: (decision: ActionSafetyDecisionWithContext) => ActionSafetyDecision | void | null;
  onDecision?: (decision: ActionSafetyDecisionWithContext) => void;
}

Defaults in copilot mode:

{
  enabled: true,
  classifier: 'default',
  guardModel: 'auto',
  classifierTimeoutMs: 300,
  minConfidenceToAllow: 0.75,
  unknownActionDecision: 'ask',
  approvalReuse: 'risk-boundary',
  userOverride: { allowAskDecision: true },
}

ActionSafetyDecision

interface ActionSafetyDecision {
  decision: 'allow' | 'ask' | 'block';
  confidence?: number;
  reason: string;
  userMessage?: string;
  capability?: ActionSafetyCapability;
  scope?: ActionSafetyScope;
  risk?: 'low' | 'medium' | 'high' | 'critical';
  requiresFreshApproval?: boolean;
}

ToolStabilizationConfig

interface ToolStabilizationConfig {
  enabled?: boolean;
  maxMs?: number;
  stableFrames?: number;
}

Defaults:

{
  enabled: true,
  maxMs: 1000,
  stableFrames: 2,
}

Rich UI Types

BlockDefinition

interface BlockDefinition {
  name: string;
  component: React.ComponentType<any>;
  allowedPlacements: Array<'chat' | 'zone'>;
  propSchema?: Record<string, BlockPropDefinition>;
  previewTextBuilder?: (props: Record<string, unknown>) => string;
  interventionType?: BlockInterventionType;
  interventionEligible?: boolean;
  styleSlots?: string[];
}

ChatBarTheme

interface ChatBarTheme {
  primaryColor?: string;
  backgroundColor?: string;
  textColor?: string;
  inputBackgroundColor?: string;
  successColor?: string;
  errorColor?: string;
}

Support Helpers

buildSupportPrompt

Builds support-focused system instructions.

import { buildSupportPrompt } from '@mobileai/react-native';

const system = buildSupportPrompt({
  enabled: true,
  persona: { agentName: 'Nora', preset: 'warm-concise' },
  autoEscalateTopics: ['account deletion'],
});

createEscalateTool

Creates a custom escalation tool if you are not using MobileAI Cloud escalation.

import { createEscalateTool } from '@mobileai/react-native';

const escalateTool = createEscalateTool({
  config: {
    provider: 'custom',
    onEscalate: (context) => sendToHelpdesk(context),
  },
  getContext: () => ({
    currentScreen: 'Orders',
    originalQuery: 'My order is late',
    stepsBeforeEscalation: 3,
  }),
  getHistory: () => [],
});

Other Exports

The package also exports:

  • Providers: GeminiProvider, OpenAIProvider, createProvider, ReactNativePlatformAdapter
  • Voice services: VoiceService, AudioInputService, AudioOutputService
  • Knowledge services: KnowledgeBaseService, createMobileAIKnowledgeRetriever
  • Analytics: MobileAI
  • Support UI and transport: CSATSurvey, EscalationSocket
  • Rich UI: RichContentRenderer, RichUIProvider, built-in blocks, and primitives