Let an agent run actions inside your app

Most tools run on a server. A frontend tool runs in your application, in the session of the person who is actually using it — so the agent can open a screen, apply a filter, start something, or read state that only exists in the browser or on the device.

It comes in two halves: you define the tool in the dashboard, and implement the handler in your own code.

Define it

In the agent's Tools section, add a Frontend tool. Give it a name and a description — the description is what the agent uses to decide when to call it — then define the parameters it should pass to your handler, each with a type and a description of its own.

Under Execution mode, you choose between Auto, where the agent runs the tool itself, and Ask before final execution, where the user is asked to confirm first.

Use confirmation for anything with consequences — sending, deleting, paying, changing settings. Auto is right for navigating, filtering, and reading.

The runtime name

Your handler registers against a slug derived from the name, not the name itself. Letters and digits are kept, everything else becomes a hyphen, and the whole thing is lowercased — so “Create Workflow” becomes create-workflow.

You don't have to work this out. The editor shows the exact runtime name and a ready-made snippet you can copy, with versions for JavaScript, iOS, Android, React Native, Flutter and Capacitor.

Implement the handler

In your app, register a handler under that runtime name:

Gleap.registerAgentTool('create-workflow', async ({ name, trigger }) => {
  // Do the work in your app.
  return 'Workflow created.';
});

The agent calls your handler with the parameters you defined and waits for what you return. Return a string, or an object — an object is turned into JSON. Whatever comes back is what the agent knows about the outcome, so return something it can use: “Workflow created, id 4821” tells it more than “ok”.

If your handler throws, the error is caught and reported back to the agent rather than breaking the conversation, which lets it tell the user something went wrong instead of going silent.

What this is good for

The distinguishing feature is the session. An API call reaches your backend as Gleap; a frontend tool acts inside the user's own session, with their permissions and their view of the data. That makes it the right choice for anything the user should see happen, and for anything where their existing login is what authorises the action.

It also means the tool only works while your app is open. An agent running on a schedule, or one answering an email, has no session to act in — for those, use a server-side tool instead.