Quickstart

Add Kletso to a Flutter app, get a key, and have the assistant render your own widget, in about ten minutes.

You need Flutter 3.35 or newer, a Kletso workspace (private beta: request access), and one agent published to development. If you only want to see the SDK work, skip to step 6 and use the built-in fake backend.

1. Add the package

flutter pub add kletso_flutter
flutter pub add url_launcher   # optional: lets url actions open a browser

kletso_flutter is pure Dart: no platform channels, no native setup, works on Android, iOS, web (JS and Wasm) and desktop. During the private beta the packages are provided as a Git dependency; the pub.dev release follows.

2. Get a publishable key

In the dashboard open API keys, make sure the environment pill says Development, and create a Publishable key. Copy it once; it is not shown again. It looks like kl_pub_dev_… and is safe to ship in the app.

You also need the agent id from Agents (it starts with agt_).

3. Initialise

import 'package:flutter/material.dart';
import 'package:kletso_flutter/kletso_flutter.dart';

Future<void> main() async {
  final client = await Kletso.init(
    KletsoConfig(
      publishableKey: 'kl_pub_dev_…',
      agentId: 'agt_…',
      environment: KletsoEnvironment.development,
    ),
  );
  await client.identifyAnonymous();      // or: client.authenticate(token: hostJwt)
  client.setContext({'plan': 'free', 'currency': 'INR'});
  runApp(const MyApp());
}

Kletso.init opens the session and connects (WebSocket, falling back to SSE). identifyAnonymous gives the visitor a stable id for the life of the token store you pass (in memory by default). Pass a persistent store to keep conversations across restarts.

4. Show the launcher and the notification host

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) => MaterialApp(
        builder: (context, child) => KletsoNotificationHost(
          client: Kletso.instance,
          child: child ?? const SizedBox.shrink(),
        ),
        home: Scaffold(
          body: const HomeScreen(),
          floatingActionButton: const KletsoLauncher(),   // bubble → chat sheet
        ),
      );
}

KletsoLauncher opens the chat as a bottom sheet on phones and a docked panel on wide screens. KletsoNotificationHost shows banners, toasts and alerts the runtime sends, above your UI, even while the chat is closed.

Run the app, tap the bubble, and say hello. The greeting comes from your agent’s Persona tab; answers come from the model on your key.

5. Render your own widget

Declare the component in a file that imports only kletso_core (so the sync tool can read it):

// lib/kletso_components.dart
import 'package:kletso_core/kletso_core.dart';

const productCardSpec = KletsoComponentSpec(
  type: 'acme.productCard',
  description: 'A product tile: name, price with currency, rating, stock state.',
  props: {
    'type': 'object',
    'required': ['sku', 'name', 'price', 'currency'],
    'properties': {
      'sku': {'type': 'string'}, 'name': {'type': 'string'},
      'price': {'type': 'number'}, 'currency': {'type': 'string'},
      'rating': {'type': 'number'}, 'inStock': {'type': 'boolean'},
    },
  },
  example: {'sku': 'SKU-1001', 'name': 'Trail Runner 2', 'price': 1899, 'currency': 'INR'},
  actions: ['view', 'add'],
);
const kletsoComponents = [productCardSpec];

Register the builder with the widget you already have:

Kletso.instance.registerComponent(productCardSpec.type, (ctx, node) => ProductCard(
  name: node.string('name'),
  price: node.number('price'),
  inStock: node.boolean('inStock', fallback: true),
  onView: () => ctx.executeAction('view'),          // local action → your handler
  onAdd: () => ctx.executeAction('add'),            // agent action → the model
), spec: productCardSpec);

Kletso.instance.registerAction('open_product', (args, ctx) async {
  Kletso.instance.close();
  Navigator.of(ctx.context).pushNamed('/product/${args['sku']}');
});

Tell the dashboard and the model about it:

dart run kletso_flutter:sync        # writes kletso.components.json

In Components → Sync from code, paste or drop the file and import. Then open your agent, tick acme.productCard under UI, add a tool that returns products (or point at the demo backend, see below), and Publish to development. Ask the assistant for products and the reply is your card.

6. No backend yet? Use the fake

final backend = KletsoFakeBackend(scenario: const KletsoFakeScenario.demo());
await Kletso.init(
  KletsoConfig(publishableKey: 'kl_pub_demo', agentId: KletsoFakeBackend.agentId),
  api: backend, transport: backend,
);

The fake plays the protocol fixtures in-process: flights, hotels, product cards, a sales chart, a confirmation, a handoff, notifications. Try “flight”, “products”, “sales”, “cancel my order”, “human”.

7. Try the demo tools

The runtime hosts a stand-in shop backend at https://api.kletso.ai/demo/acme/* (products, flights, orders, shipments, sales). The Acme sample agent’s tools point at it, so a fresh workspace can show real tool calls before you connect your own API. Tool definitions are in the Tools page.

Where next

• Scenarios: product search, order tracking, cancellation with confirmation, proactive store offer, and more.
• Flutter SDK: every knob in the client and the widgets.
• Dashboard: agents, versions, tools, triggers.