Docs

Build an intent bar

Put the intent bar in your app, from a trained model to a working bar, and use your users' corrections to improve it.

The intent bar is a bar your users type into. It sends what they type to your model, shows the result as editable chips with a preview, and hands the call to your app to run. It runs every call through your app's own code, with the signed-in user's permissions.

The intent bar is a JavaScript package, @fernfly/intent-bar, with a React component and a script tag for apps that don't use React. It is early, and its API may change before version 1.0.

Before you start

You need a deployed project. There are two ways to get one:

  • Intent bar for your app in the new-project wizard reads your API docs and does everything in one run. See Create a model.
  • Any deployed project works too. Its Overview has the same setup under Add the intent bar.

Set it up

The setup has three steps, on the wizard's last step and on the project's Overview.

1. Allow your app to call the model

The intent bar calls your model from the browser, without an API key. Choose Allow keyless calls, then list your app's address under Sites allowed to call this endpoint and choose Save allowed sites. Add http://localhost:3000, or wherever you run your app, while you develop.

API keys and keyless calls explains the controls that apply to keyless calls.

2. Install the package

npm install @fernfly/intent-bar

3. Add the intent bar and connect each tool

Choose Copy code. Studio writes a starting component with your project id and one entry for each of your tools. Render it once, in the signed-in part of your app, then:

  • Fill in each run with the call your app makes for that tool, such as a router change for a filter or an API request for an action.
  • Change any label that doesn't read the way your users would say it.

A shortened example:

'use client'
import { IntentBar } from '@fernfly/intent-bar'

export function AppIntentBar() {
  return (
    <IntentBar
      project="<project-id>"
      appName="Acme"
      tools={{
        list_invoices: {
          kind: 'filter',
          run: (args) => router.push(invoicesUrl(args)),
        },
      }}
    />
  )
}

The intent bar guide covers the script tag, lookups (finding "Priya" among your users, for example) and previews.

As well as the model, the intent bar searches your app's pages and one-click commands as the user types, and shows matches straight away.

If you gave Your app's address when you created the project, Studio reads its public pages and adds the pages and commands it finds to the starting code. They are used for instant search only. The model never sees them, and they are never used for training.

If your app's pages need sign-in, Studio can't read them, and the intent bar uses the links in your app's <nav> instead.

How a request flows

  1. The user types a sentence and presses Enter.
  2. The intent bar sends it to your model and shows the call as chips: the tool, and each argument with its value.
  3. The user checks the chips, and can change any value, add a missing argument or switch to another tool.
  4. The user runs it. The intent bar calls that tool's run in your app, which applies the filter or performs the action.

Nothing runs until the user does step 4, with one exception. When the model answers with a tool whose kind is 'navigate', and every chip has a value, its button counts down from 3 and the call runs by itself. Any key or click stops the countdown, and Enter runs the call at once. Set autoRun on the tool to a number of seconds to change the wait, or to false to wait for Enter.

Corrections

When a user changes a chip and then runs the call, the intent bar sends the changed call to Fernfly as a correction. It tells you what the user meant when the model got it wrong.

What the user didSent as a correction?
Changed a value the model choseYes
Added an argument the model left outYes
Removed an argument, or edited free textYes
Switched to another toolYes
Chose between two matches a lookup foundNo. The model's words were right; your data was ambiguous.
Changed chips, then pressed EscNo. Nothing ran.
Ran the call unchanged, or let it run by itselfNo. The model was right.

A correction is accepted once per request, within 24 hours of it, and only when it fits your tools.

Corrections never become training data on their own. On the Retrain tab, choose Corrected to see the requests your users fixed. Each shows the model's call and the user's, marked Corrected by a user. Use this correction puts the user's call in place of the model's, so you can save it as a training pair. See Retrain.

Revised

Was this page helpful?