Agent tools

Configuring agent tools

For a Plugin application, open the Agent tools section. The main switch controls whether agents can add and run these tools. It does not control automation steps or the application's embedded page.

Choosing a connection method

Choose one mode for the whole application:

• Builder — the application contains one or more HTTP tools with separate URLs and parameters;
• MCP server — the application connects an existing MCP endpoint and loads its tool list from the server.

After changing the mode, select Save. Installed projects receive only the currently saved mode.

MCP server

In MCP mode, enter the server URL and, when required, the authorization header name and value. A saved secret is not shown again; replace it with a new value or mark the saved value for removal, then save the settings.

HTTP tool builder

Select Add. In the tool form, first complete the user-facing presentation:

On the Russian tab, enter the name and short description. In the optional Response description field, explain what data the tool returns after it runs.

On the English tab, enter the English name and English description. If the Russian response description is filled in, add its English version in the Response description field.

Both names and both short descriptions are required; users see the version matching their Cabinet language. The response description may be omitted, but when it is used, enter both language versions. Users see it in the tool details and can understand the expected result of the call.

Then specify the technical settings:

• a system name, for example find_customer;
• the handler URL with http or https;
• by default, the agent uses the Russian short description. Enable Technical description for the agent and enter an agent-facing description only when the model needs call conditions that should not be shown to users;

• in the parameter list, set the name, type (string, number, or boolean), clear description, and required flag for each argument.

In Adding to an agent, enable Configure when adding when the user must select an account, access scope, or other settings before connecting the action. If needed, enable Allow adding more than once so one agent can have several independently configured instances.

Select Add parameter for each new argument. Every parameter has a remove action.

After confirmation, the parameter disappears only from the current form; the actual tool changes after the complete form is saved.

When the form is complete, select Save.

A saved tool in the list can be reopened and changed. Delete requires confirmation and permanently removes the tool from the application.

The handler receives JSON in this form:

{
  "event_id": "019d0000-0000-7000-8000-000000000001",
  "event_type": "tool_call",
  "timestamp": "2026-07-30T12:00:00.000Z",
  "app_id": "app-id",
  "installation_id": "installation-id",
  "project_id": "project-id",
  "agent_id": "agent-id",
  "dialog_id": "dialog-id",
  "lead_id": "lead-id",
  "tool_name": "find_customer",
  "tool_instance_id": "tool-instance-id",
  "arguments": {
    "customer_id": "123"
  },
  "configuration": {
    "account_id": "store-1"
  },
  "private_data": {
    "access_token": "write-only-token"
  }
}

agent_id and dialog_id are always included, while lead_id is included only when the dialog is linked to a lead. tool_instance_id distinguishes independently configured instances of the same tool. configuration contains regular instance settings and private_data contains decrypted protected values needed for the call; do not write them to public logs or responses. Both objects are empty for a regular non-configurable tool.

The call is signed with the shared secret for all application webhooks. Validate the freshness of X-Webhook-Timestamp, match X-Webhook-Event-Id to the body event_id, and verify X-Webhook-Signature using the same rules as public application webhooks. Do not execute the action until its signature has been verified.

Use event_id as an idempotency key because an automatic or manual retry may send the same action again.

Execution modes and retries

In Execution mode, choose:

• Instant execution — the agent waits for one HTTP response and receives its body as the tool result; there are no automatic retries;
• Wait for result — the request is queued, the agent pauses this step, and continues after a successful result;
• Background operation — the request is queued, but the agent does not wait for or use the response to continue the current step.

One attempt waits 10, 30, 60, or at most 120 seconds. Select the value in HTTP attempt timeout. For the two asynchronous modes, select a retry window:

• 5 minutes — 5 attempts: immediately, then after 15 seconds, 1, 3, and 5 minutes;
• 3 hours — 8 attempts: immediately, then after 1, 5, 15, and 30 minutes, and 1, 2, and 3 hours;
• 1 day — 12 attempts: immediately, then after 1, 5, 15, and 30 minutes, and 1, 2, 4, 8, 12, 18, and 24 hours.

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 @senler/ui/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.

import { createSenlerBridgeClient } from "@senler/ui/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.