A tool for the chatbot

A tool is a function the AI model may call while it writes an answer: it sends the tool’s name and arguments, KimaAI runs the tool on your site, and the model answers from the result. Three filters make one: kimaai_chatbot_tools_registry describes the tool to the model, kimaai_chatbot_allowed_tools allows it, and kimaai_chatbot_tool_call runs it. This guide builds a tool that finds the shop’s stores in a city. It works in the free version and in Pro.

Example

add_filter(
  'kimaai_chatbot_tools_registry',
  function (array $tools): array {
    $tools[] = [
      'type' => 'function',
      'name' => 'my_find_store',
      'description' => 'The shop\'s stores in a city, with address and opening hours. Call it when the visitor asks for a store near them.',
      'parameters' => [
        'type' => 'object',
        'properties' => [
          'city' => [
            'type' => 'string',
            'description' => 'The city, for example Freiburg.',
          ],
        ],
        'required' => ['city'],
        'additionalProperties' => false,
      ],
    ];

    return $tools;
  }
);

add_filter(
  'kimaai_chatbot_allowed_tools',
  function (array $names): array {
    $names[] = 'my_find_store';
    return $names;
  }
);

add_filter(
  'kimaai_chatbot_tool_call',
  function ($result, string $name, array $args) {
    if ($result !== null || $name !== 'my_find_store') {
      return $result;
    }

    $stores = [
      'freiburg' => [
        ['address' => 'Market Square 1', 'hours' => 'Mon to Sat 9:00 to 19:00'],
        ['address' => 'Station Road 20', 'hours' => 'Mon to Fri 10:00 to 18:00'],
      ],
      'valencia' => [
        ['address' => 'Harbour Street 5', 'hours' => 'Mon to Sat 10:00 to 20:00'],
      ],
    ];
    $city = strtolower(trim((string) ($args['city'] ?? '')));

    return ['city' => $city, 'stores' => $stores[$city] ?? []];
  },
  5,
  3
);

Put the code in your plugin. When a visitor asks “Do you have a store in Freiburg?”, the model calls my_find_store with {"city":"Freiburg"} and answers with the two addresses. The stores are a list in the code here; your tool reads them where they live on your site, a post type or an option. An empty list is a valid result: the model then says there is no store in that city.

How a tool call runs

  1. A chatbot request is prepared. kimaai_chatbot_allowed_tools gives the names the request may offer, then kimaai_chatbot_tools_registry the definitions. KimaAI keeps the definitions whose name is allowed and sends them to the AI provider with the visitor’s message.
  2. The model answers, or calls one or more tools. KimaAI refuses a tool the request did not offer, so the model cannot run a tool by naming it.
  3. kimaai_tool_call_allowed decides whether the call may run.
  4. kimaai_chatbot_tool_call runs it: the callback that knows the tool returns the result.
  5. KimaAI sends the results back to the model, which answers or calls the next tool. Each of these rounds is another request to the AI provider.

Each request asks the filters again, so the tool can depend on the page or the visitor. $payload['postId'], the second argument of kimaai_chatbot_tools_registry, is the page the chat sits on; the filter’s page offers a tool on product pages only. The search answer keeps only the knowledge search, so a tool of your own runs in the chatbot only.

Two registries

KimaAI has two filters with “tools registry” in their name:

  • kimaai_chatbot_tools_registry is the list of one request, the definitions the model gets. The example uses it, so the tool works in every version.
  • kimaai_tools_registry is the catalogue of tools: the setting “Allowed custom functions” (Chatbot Settings, Pro) lists it, so a site owner can switch a tool on and off by hand. An entry can carry a callback that runs the tool, and sensitive for a tool whose result holds a person’s data. With Pro, every allowed catalogue tool goes into the request’s list. In the free version the setting is a Pro feature and the catalogue does not reach the chatbot.

Use the catalogue for a tool the site owner should decide on, with Pro; its page has an example. Use the request’s list for a tool your plugin always offers, or offers by page or visitor.

Running the call

The callback of kimaai_chatbot_tool_call gets null and returns the result for its own tool; for any other tool it returns what it got. Add it at a priority below 10: at 10, Pro’s tool router answers every tool it is asked about, and the result is no longer null when your callback runs.

  • Return an array; KimaAI encodes it as JSON for the model. Keep it short: the result counts towards the request’s tokens.
  • For a case the tool cannot handle, return a result that says so, such as ['error' => 'Unknown city']. The model reads it and tells the visitor in its own words.
  • An exception your callback throws reaches the model as {"error": <message>}, and a streamed chat shows that the tool failed, so catch what you can.
  • KimaAI masks card numbers and IBANs in the result while the chatbot’s masking is on, and emails and phone numbers when the settings ask for it.
  • The result is stored with the conversation and, in a streamed chat, sent to the browser with the tool’s progress. Return only what the visitor may see.

The arguments come from the model. Treat them as the visitor’s input: check them, and never let them choose whose data the tool reads. A tool for a logged-in customer reads the customer from WordPress’s current user, not from an argument.

Blocking a call

kimaai_tool_call_allowed runs before every tool call, KimaAI’s own tools included. Return a string to block a call; the model gets it as the tool’s result:

add_filter(
  'kimaai_tool_call_allowed',
  function ($allow, string $name) {
    if ($allow !== true || $name !== 'my_find_store' || !get_option('my_stores_closed')) {
      return $allow;
    }

    return 'All stores are closed for stocktaking today. Suggest the online shop instead.';
  },
  10,
  2
);

To keep a tool out of a request altogether, remove its name in kimaai_chatbot_allowed_tools instead: the model then does not know it.

Rounds

An answer may take 6 rounds of tool calls by default. When your tools are called one after another, an order lookup and then its delivery, raise the number with kimaai_chatbot_max_tool_rounds. Each round is a request to the AI provider and costs tokens. When the model still calls a tool after the last round, your tool does not run: the model gets a note that the budget is spent and answers with what it has, streamed or not.

add_filter(
  'kimaai_chatbot_max_tool_rounds',
  function (int $max_rounds): int {
    return 8;
  }
);

What are your feelings