Routing

VableAI can navigate your Flutter app on the user's behalf. You tell the SDK which routes exist and which routing library you use — the AI agent handles the rest when the user says something like "take me to my account" or "open settings".

Overview

Note: Routes that require parameters (e.g. /product/:id, /user/:userId/profile) are not currently supported.

Setup has two options — manual or automatic:

Manual — declare your routes explicitly via initialize and handle navigation with setNavigationCallback
Automatic — use configureRouter with your routing library and let Vable handle navigation automatically

Declaring Routes

Pass routes at initialization time:

await Vable.initialize(
  '<replace_with_public_key>',
  routes: [
    VableRoute(path: '/home',     name: 'Home'),
    VableRoute(path: '/account',  name: 'Account'),
    VableRoute(path: '/settings', name: 'Settings'),
  ],
);

You can also use VableRouteExtractor to derive routes from an existing routes map:

final appRoutes = {
  '/home':     (context) => const HomePage(),
  '/account':  (context) => const AccountPage(),
  '/settings': (context) => const SettingsPage(),
};

await Vable.initialize(
  '<replace_with_public_key>',
  routes: VableRouteExtractor.fromRoutesMap(appRoutes),
);

Connecting Your Router

Call Vable.configureRouter after your router and dependency injection are initialized.

AutoRoute

// main.dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  configureDependencyInjection(); // set up your DI first

  await Vable.initialize(
    '<replace_with_public_key>',
    routes: [
      VableRoute(path: '/home',    name: 'Home'),
      VableRoute(path: '/account', name: 'Account'),
    ],
  );

  Vable.configureRouter(
    library: VableRoutingLibrary.autoRoute,
    router: appRouter, // your AppRouter instance
  );

  runApp(const App());
}

Add VableNavigatorObserver to your router delegate so Vable tracks navigation context:

// app.dart
MaterialApp.router(
  routerDelegate: AutoRouterDelegate(
    appRouter,
    navigatorObservers: () => [
      VableNavigatorObserver(),
    ],
  ),
  routeInformationParser: appRouter.defaultRouteParser(),
)

AutoRoute uses code generation and doesn't support string-based navigation well. If configureRouter doesn't navigate correctly, use setNavigationCallback instead — see Custom Navigation Callback below.

GoRouter

final router = GoRouter(
  routes: [
    GoRoute(path: '/home',     builder: (_, __) => const HomePage()),
    GoRoute(path: '/account',  builder: (_, __) => const AccountPage()),
    GoRoute(path: '/settings', builder: (_, __) => const SettingsPage()),
  ],
);

await Vable.initialize('<replace_with_public_key>');

Vable.configureRouter(
  library: VableRoutingLibrary.goRouter,
  router: router, // Vable calls router.go(url) internally
);

runApp(MaterialApp.router(routerConfig: router));

Native Flutter Navigator

No configureRouter call needed. Define your routes in MaterialApp and add VableNavigatorObserver:

MaterialApp(
  routes: {
    '/home':    (context) => const HomePage(),
    '/account': (context) => const AccountPage(),
  },
  navigatorObservers: [VableNavigatorObserver()],
)

For full control — or when your router doesn't support string-based navigation — use setNavigationCallback:

Vable.setNavigationCallback((String url) {
  final router = getIt<AppRouter>();
  switch (url) {
    case '/account':
      router.push(const AccountRoute());
      break;
    case '/settings':
      router.push(const SettingsRoute());
      break;
  }
});

A custom callback takes priority over configureRouter.

VableNavigatorObserver

VableNavigatorObserver keeps Vable's navigation context in sync as the user moves through your app. Add it to navigatorObservers in your MaterialApp or router delegate:

// With MaterialApp
MaterialApp(
  navigatorObservers: [VableNavigatorObserver()],
)

// With MaterialApp.router + AutoRoute
AutoRouterDelegate(
  appRouter,
  navigatorObservers: () => [VableNavigatorObserver()],
)

Full Example (AutoRoute)

// main.dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  configureDependencyInjection();

  await Vable.initialize(
    '<replace_with_public_key>',
    routes: [
      VableRoute(path: '/home',    name: 'Home'),
      VableRoute(path: '/account', name: 'Account'),
    ],
  );

  Vable.configureRouter(
    library: VableRoutingLibrary.autoRoute,
    router: appRouter,
  );

  runApp(const App());
}

// app.dart
class App extends StatelessWidget {
  const App({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp.router(
      routerDelegate: AutoRouterDelegate(
        appRouter,
        navigatorObservers: () => [VableNavigatorObserver()],
      ),
      routeInformationParser: appRouter.defaultRouteParser(),
    );
  }
}

Intents

Core