Tool configuration form

Show users a custom form when they add a tool to an agent.

First add an HTTP tool in the application builder.

Configuring a tool when adding it to an agent

What to enable

A configurable tool is available only in Builder mode. Before saving it, set the main URL of the embedded page; this address opens the form used to add and edit an instance. The application's main page does not have to be shown in the project menu. MCP tools use the regular switch and do not use this configurator.

• Configure when adding opens the embedded page before the first addition;
• Allow adding more than once is available only for a configurable tool and creates a separate instance each time;
• configurability cannot be disabled while the tool is added to at least one agent;
• multiple additions cannot be disabled while any agent still has more than one instance.

For the configurator, Senler opens the embedded page's primary URL. When developer mode is enabled, an application team member receives the developer URL instead. The API adds a one-time launch_code and the cabinet adds the version 2 bootstrap parameters: senler_mode=tool_configurator, senler_theme, and senler_language. The complete context arrives through Bridge. The iframe does not receive the Client Secret or a Senler access token.

Senler Bridge

Use the @senlerio/bridge package to communicate with the cabinet. It validates message structures, accepts data only from the specified origin, and avoids a hand-written postMessage protocol.

Bridge is installed separately and does not require React, Senler UI, or CSS:

npm install https://github.com/SenlerBot/senler-bridge/archive/refs/tags/v1.0.1.tar.gz

import { createSenlerBridgeClient } from "@senlerio/bridge";

const allowedParentOrigins = new Set([
  "https://senler.io",
  "https://aibot.local",
]);
const parentOrigin = new URL(document.referrer).origin;
if (!allowedParentOrigins.has(parentOrigin)) {
  throw new Error("Unknown Senler parent origin");
}

const bridge = createSenlerBridgeClient({ parentOrigin });
const context = await bridge.connect();

if (context.launch.type !== "tool_configurator") {
  throw new Error("Expected tool configurator launch");
}

Add only real cabinet origins for your environments to the allowlist. connect() announces readiness and returns the current context. By default, Bridge also sets lang, the dark class, and color-scheme on the document root; the application still needs styles for both themes. Subscribe to bridge.onContextChange(...) to react to later language, theme, or context changes.

context.launch contains app_id, project_id, installation_id, agent_id, the tool, create or edit mode, and the saved instance during editing. These values help build the form but are not an API token. The application must implement authorization with an external service itself.

Register one save handler. When the user selects Add or Save, the cabinet calls it and waits for no more than 20 seconds:

const unsubscribeSubmit = bridge.onToolConfiguratorSubmit(async () => ({
  title: "Primary store",
  configuration: {
    account_id: "store-1",
  },
  configured_parameters: [
    {
      name: "customer_id",
      type: "string",
      description: "Customer ID in the primary store",
      required: true,
      allowed_values: [],
    },
  ],
  private_data_action: "replace",
  private_data: {
    access_token: "secret-token",
  },
  private_data_required: true,
}));

If the handler throws an Error, the cabinet shows its message and keeps the dialog open. Call the unsubscribe functions and bridge.destroy() when the page unmounts.

The configurator iframe allows scripts, forms, modals, downloads, and external popups. It may also request browser access to the clipboard, fullscreen mode, and microphone; actual permission depends on the browser and the user's choice. The cabinet does not grant camera access.

What is stored

• title is a clear instance title up to 160 characters;
• configuration contains regular JSON settings up to 64 KB. It is returned in instance during editing and sent to the handler on every call;
• configured_parameters are the parameters exposed to the model for this instance. Names and types must match the source tool parameters; allowed_values restricts accepted values, while an empty array adds no restriction;
• private_data contains protected JSON data up to 64 KB. It is encrypted at rest, is never returned in instance or the API, and is sent only to the tool handler when called;
• private_data_action accepts preserve, replace, or clear. private_data is required with replace; use preserve during editing to keep an already stored secret;
• private_data_required: true prevents the agent from calling an instance without protected data. The cabinet marks that instance as Private data must be connected again.

In the installed project, the required actions are enabled separately in each agent's settings. Disabling tools in the application makes them unavailable to agents but does not disable the plugin's embedded user interface.