kimaai_tools_registry

When it fires

Each time KimaAI reads its catalogue of tools, which is several times in a request: for the options of the setting “Allowed custom functions” (Chatbot Settings, section “Allowed functions”), for the definitions sent to the AI provider, and for each tool call. So a callback adds its definitions and does nothing else: no queries, no requests.

The catalogue holds KimaAI’s own tools (wp_get_post, wp_search_posts and hidden ones such as the knowledge search) and those of the integrations. Each entry is keyed by the tool’s name, which the model uses in its call: letters, digits and _, at most 64 characters, not starting with a digit; other names are dropped. The keys of an entry:

  • label and description: the setting shows them, and the description tells the model when to call the tool. Write it for the model.
  • parameters: the JSON schema of the arguments; without it the tool takes none.
  • callback: a callable, or a function’s name, that gets the arguments as an array and returns the result. KimaAI Pro runs it; it encodes an array as JSON for the model.
  • hidden: true keeps the tool out of the setting, for a tool the add-on offers itself through kimaai_chatbot_allowed_tools.
  • sensitive: true for a tool whose result holds a person’s data. The result then reaches the model as it is, without the masking of card numbers and IBANs, and the stored conversation and the stream keep only the number of records.

With KimaAI Pro, the chatbot offers a catalogue tool when it is allowed: ticked in the setting, or added by kimaai_chatbot_allowed_tools. When the model calls it, kimaai_tool_call_allowed decides first, then the callbacks of kimaai_chatbot_tool_call at a priority below 10, and then the tool’s callback. In the free version the setting is a Pro feature and the chatbot does not offer the catalogue; a tool there is defined with kimaai_chatbot_tools_registry and run with kimaai_chatbot_tool_call.

Parameters

NameTypeDescription
toolsarrayThe tools by name, each with label, description, hidden, sensitive, parameters and callback.

Returns

array: The tools by name.

Example

add_filter(
  'kimaai_tools_registry',
  function (array $tools): array {
    $tools['my_opening_hours'] = [
      'label' => 'Opening hours',
      'description' => 'The shop\'s opening hours on one day of the week. Call it when the visitor asks when the shop is open.',
      'parameters' => [
        'type' => 'object',
        'properties' => [
          'day' => [
            'type' => 'string',
            'enum' => ['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'],
          ],
        ],
        'required' => ['day'],
        'additionalProperties' => false,
      ],
      'callback' => function (array $args): array {
        $hours = [
          'monday' => '9:00 to 18:00',
          'tuesday' => '9:00 to 18:00',
          'wednesday' => '9:00 to 18:00',
          'thursday' => '9:00 to 20:00',
          'friday' => '9:00 to 18:00',
          'saturday' => '10:00 to 14:00',
          'sunday' => 'closed',
        ];
        $day = (string) ($args['day'] ?? '');

        return isset($hours[$day]) ? ['day' => $day, 'hours' => $hours[$day]] : ['error' => 'Unknown day'];
      },
    ];

    return $tools;
  }
);

The tool shows in the setting as “Opening hours”. Once it is ticked there, the chatbot of a Pro site answers “When are you open on Thursday?” from the tool’s result.

  • kimaai_chatbot_allowed_tools: allows a tool without the setting.
  • kimaai_chatbot_tools_registry: offers a tool for one request, in the free version too.
  • kimaai_chatbot_tool_call: runs a tool in a callback of its own.
  • kimaai_tool_call_allowed: blocks a call before the tool runs.

What are your feelings