Agent navigates the app

The user asks to open something; the assistant sends an app command and the app navigates, with the chat closing out of the way.

Goal

“Open the trail runner” → the model calls app_command { name: 'open_product', args: { sku: 'SKU-1001' }, closeChat: true } → the app closes the chat and pushes the product page.

Pieces

• SDK: KletsoConfig(allowServerCommands: true), client.ui.contextProvider = () => navigatorKey.currentContext, and registerAction('open_product', …).
• Prompt line: “When the user asks to open or go to a product, call app_command with name open_product and the sku.”
• The built-in app_command tool needs no configuration.

Code

client
  ..registerAction('open_product', (args, ctx) async {
    final product = productBySku(args['sku'] as String? ?? '');
    if (product == null) return;
    client.close();
    await navigatorKey.currentState?.push(MaterialPageRoute(builder: (_) => ProductPage(product)));
  })
  ..ui.contextProvider = () => navigatorKey.currentContext;

Verify

• Preview: “open the trail runner” → inspector shows app.command with name: open_product.
• App: the chat sheet closes and the product page appears. client.ui.commandResults emits ran.
• Turn allowServerCommands off → the command is ignored and commandResults emits disabled; nothing else changes.

Notes

• Commands run the same handlers as taps and notifications, so there is one place to maintain navigation.
• Keep the set of command-able actions small and safe (navigate, open, filter). Anything with consequences should be a confirmation tool instead.