Navigation

The agent needs two things to navigate your app well: to know where the user currently is, and to know what each screen is for. AppilotsNavigationContainer handles the first; registerScreen handles the second.

AppilotsNavigationContainer

AppilotsNavigationContainer wraps your React Navigation <NavigationContainer> from the outside. It automatically injects ref and onStateChange to track the active route and forward it to Appilots, so the agent's navigate actions can target real routes and every chat message carries "where the user is" as part of its context.

import { NavigationContainer } from '@react-navigation/native';
import { AppilotsProvider, AppilotsNavigationContainer, AppilotsChat } from '@appilots/sdk';

function App() {
  return (
    <AppilotsProvider>
      <AppilotsNavigationContainer>
        <NavigationContainer>
          <Stack.Navigator>
            {/* your screens */}
          </Stack.Navigator>
        </NavigationContainer>
      </AppilotsNavigationContainer>
      <AppilotsChat />
    </AppilotsProvider>
  );
}

If your NavigationContainer already has its own ref or onStateChange (for analytics, deep linking, etc), AppilotsNavigationContainer forwards to them — you don't lose your existing handlers by adding this wrapper.

registerScreen

registerScreen(metadata) describes a screen to the agent: what it's for, what fields and actions live on it, and which prompts to suggest when the chat opens there. Call it once per screen — at the top of the screen component, or from a shared registry file.

import { registerScreen } from '@appilots/sdk';

registerScreen({
  name: 'VehicleCreate',
  title: 'New Vehicle',
  description: 'Form to register a new vehicle for the account.',
  fields: [{ id: 'plate', label: 'License Plate', type: 'text', required: true }],
  actions: [{ id: 'submitVehicle', label: 'Save Vehicle', type: 'submit', effect: 'write', riskLevel: 'low' }],
  suggestedPrompts: ['Add a vehicle'],
});

ScreenMetadata

Field	Type	Description
name	string	Required. Must match the React Navigation route name.
title	string	Human-readable screen title.
description	string	What this screen does — helps the agent decide when to navigate here.
actions	(string | ScreenActionMetadata)[]	Actions available on this screen. See below.
fields	ScreenFieldMetadata[]	Form fields available on this screen. See below.
formFields	string[]	Legacy simple list of field names. Prefer fields.
tags	string[]	Free-form tags for categorization.
suggestedPrompts	string[]	Chips shown when the chat opens on this screen. These have the highest priority — they beat server-mined popular prompts.

ScreenActionMetadata

Field	Type	Description
id	string	Action identifier the agent references.
label	string	Human-readable label — should match the UI.
type	'submit' | 'button' | 'link' | string	Action type.
targetScreen	string	Destination screen, for navigation/link actions, when known.
requiresConfirmation	boolean	Forces a confirmation card before this action executes.
effect	'read' | 'write' | 'destructive' | string	What kind of effect this action has.
riskLevel	'low' | 'medium' | 'high' | string	Risk level used alongside effect to decide how cautious the agent should be.
destructive	boolean	Marks the action as destructive.

See Agent actions for how the agent uses effect, riskLevel, and requiresConfirmation to decide when to ask for approval.

ScreenFieldMetadata

Field	Type	Description
id	string	Field identifier the agent references.
label	string	Human-readable label — should match the UI.
type	'text' | 'number' | 'select' | 'toggle' | 'date' | string	Field type.
required	boolean	Whether the field is required.
options	{ label: string; value: string }[]	Options for select fields.

registerScreen vs. registering elements

registerScreen describes the screen — its purpose, its fields, and its actions, as metadata the agent reads. It does not make anything operable by itself. To let the agent actually fill a field or press a button, you also need to register the underlying component — via auto-tracking, a hook, or an HOC. See Registering elements for those three approaches.

Next steps

• Registering elements — make fields and buttons operable.
• Agent actions — how effect, riskLevel, and confirmation work together.
• Permissions — gate what the agent can do at the SDK level.