kimaai_chatbot_tools_registry

When it fires

In every chatbot request, streamed or not, and every search answer, while the request is prepared: after kimaai_chatbot_gate and the limits, right after kimaai_chatbot_allowed_tools, before anything reaches the AI provider. It starts from an empty list. KimaAI adds its own at priority 10: the contact form tool of lead capture while it asks on buying intent and the conversation has no lead yet, and in Pro the catalogue of kimaai_tools_registry, the custom functions and the meeting booking tool.

Each definition is an array with type function, the tool’s name, a description that tells the model when to call it, and parameters, the JSON schema of its arguments. After the filter KimaAI keeps only the definitions whose name is among the allowed tools ($payload['selectedTools']): a tool needs both filters, or an entry in the setting “Allowed custom functions” (Pro). With no allowed tool, the request offers none. A search answer keeps only the knowledge search.

The request offers the tool; kimaai_chatbot_tool_call runs it when the model calls it. A tool no request offered is never run, whatever the model asks for.

Parameters

NameTypeDescription
toolsarrayThe tool definitions as the provider gets them, each with type function, name, description and parameters.
payloadarrayThe normalised request payload, with prompt, sessionId, postId, chatbot_settings and selectedTools, the names kimaai_chatbot_allowed_tools returned.
chatbot_settingsarrayThe chatbot settings.

Returns

array: The tool definitions.

Example

add_filter(
  'kimaai_chatbot_tools_registry',
  function (array $tools, array $payload): array {
    if (get_post_type((int) ($payload['postId'] ?? 0)) !== 'product') {
      return $tools;
    }

    $tools[] = [
      'type' => 'function',
      'name' => 'my_delivery_time',
      'description' => 'The delivery time to a country in working days. Call it when the visitor asks when an order arrives.',
      'parameters' => [
        'type' => 'object',
        'properties' => [
          'country' => [
            'type' => 'string',
            'description' => 'The two-letter country code, for example DE.',
          ],
        ],
        'required' => ['country'],
        'additionalProperties' => false,
      ],
    ];

    return $tools;
  },
  10,
  2
);

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

The chatbot offers my_delivery_time on product pages only; elsewhere the model does not know it. postId is the page the chat sits on, 0 in a search answer. The page of kimaai_chatbot_tool_call runs the tool.

  • kimaai_chatbot_allowed_tools: the names a request may offer.
  • kimaai_chatbot_tool_call: runs the tool.
  • kimaai_tools_registry: the catalogue of tools the setting lists (Pro).
  • kimaai_chatbot_max_tool_rounds: how many rounds of tool calls an answer may take.

What are your feelings