Skip to main content

Multi-Screen Workflows

"Add a vehicle" is one screen. "Find the customer named Silva, open their newest contract, and renew it" is a workflow: navigate → scroll a list → select a row → navigate again → act. This guide covers what the agent needs to chain screens together reliably.

Register every screen on the path​

The agent plans routes from the navigation graph in your MCP document plus the runtime screen metadata. Every screen a workflow passes through should be registered — including the "boring" intermediate ones:

registerScreen({
  name: 'Customers',
  title: 'Customers',
  description: 'Searchable list of all customers. Tapping a row opens CustomerDetail.',
  suggestedPrompts: ['Find a customer', 'Add a customer'],
});

registerScreen({
  name: 'CustomerDetail',
  title: 'Customer Detail',
  description: 'Shows one customer with their contracts. Actions: renew, edit, delete.',
});

The single most common cause of a multi-step task failing partway through is a vague or missing description. Say what the screen shows and where it leads — the agent chains screens from these sentences.

Nested navigators​

React Navigation requires nested params to reach a screen inside a nested navigator, and the agent handles this through the path field of a navigation action (see Agent actions): a navigate payload may carry path: ['HomeTab', 'VehiclesTab'] to reach a screen under HomeTab → VehiclesTab. You don't construct this yourself — the agent derives it from the navigation graph the CLI extracts from your navigator definitions. What you do need:

  • Keep navigator structure in analyzable form (standard createStackNavigator / createBottomTabNavigator patterns).
  • Use the CLI's navigationInclude config (see Configuration) if your navigator files live somewhere unconventional.
  • Re-run appilots sync after restructuring navigation — a stale graph sends the agent down routes that no longer exist.

Long and virtualized lists​

Workflows often need "the row for Silva" in a list of hundreds. Lists picked up by auto-tracking (FlatList, SectionList, VirtualizedList, FlashList) are addressable by the agent even when rows are virtualized off-screen: the agent can issue scroll_list actions (conceptually { listId, toIndex?, direction? } — see Agent actions) to bring a target row into view before pressing it.

To make lists workflow-friendly:

  • Give the list a testID (it becomes the listId).
  • Make rows identifiable: row data with name/title/plate-style fields gives the agent something to match "Silva" against.
  • Ensure row presses are registered — a testID + onPress on the row's touchable, or a registered target.

Entry points: suggested prompts​

suggestedPrompts on registerScreen seeds the chat's suggestion chips per screen — a cheap way to steer users toward workflows you know work well:

registerScreen({
  name: 'Contracts',
  suggestedPrompts: ['Renew a contract', 'Find contracts expiring this month'],
});

Dev-defined prompts always outrank mined popular prompts (see useSuggestedPrompts).

Design guidelines​

  • One screen, one job. Screens with a crisp purpose produce crisp descriptions, and crisp descriptions produce reliable plans.
  • Gate the destructive end. Multi-step workflows often end in a mutation ("...and renew it"). Put effect/riskLevel metadata on that final action so the whole chain pauses for confirmation at exactly the right moment.
  • Test the full sentence. Don't just test each screen — ask the agent for the complete workflow in one message and watch the breadcrumb. Where it stalls tells you which screen's metadata needs work.
Last updated on