Skip to content

AI Assistant API Action

API Assistant Actions

What is an API Assistant Action?

AI Assistant Actions implement Drupal's inbuilt Plugin API to provide ways for a configured AI Assistant to interact with the Drupal site it has been installed on. Given that a mis-coded plugin could compromise the security of the site it is installed on, or cause legal issues for the site owners or even the original developers of the plugin, it is recommended that API Assistant Action plugins are only implemented by developers with experience with both Drupal and LLMs.

The ApiAssistantActionInterface

The plugin itself is a Drupal configurable plugin with a form. Advanced users can create a new plugin in their module's /src/Plugin/AiAssistantAction folder that implements the ApiAssistantActionInterface for complete control of the process. However, the majority of the plugins will share a number of requirements - the ability to access to configured AI Assistant, for example - so the AiAssistantActionBase has been created to help reduce duplication. In most cases, we would expect developers to extend this base class to provide new action plugins.

The AiAssistantActionBase class

Developers can create a new plugin in their module's /src/Plugin/AiAssistantAction folder that extends the AiAssistantActionBase base class. This class implements the ApiAssistantActionInterface and provides a Container Factory to allow additional required services to be injected as required by developers.

If the plugin requires specific configuration to be set by site builders, the buildConfigurationForm(), validateConfigurationForm() and submitConfigurationForm() methods will probably need to overridden in your plugin.

The plugin itself can implement multiple actions, to prevent duplication between actions the require similar coding. The listActions() method should be implemented to provide details of each action that the plugin can perform, including a unique id and user-readable label.

The unique id will be passed to the triggerAction() method when the AI Assistant API triggers the action, allowing the method to perform whatever action is desired. The action should set the output context when it runs, using the setOutputContext() method. This will allow the API to pass results to the LLM and to the user as required.

The plugin must also implement the provideFewShotLearningExample() method. This is used to provide a Few-Shot Learning (FSL) example to the AI on how to trigger this action. It should give back one or more examples in an array and the AI will learn from this. Implementing this may require advanced knowledge of LLMs and their workings.

Examples

For working examples, please see the code of the AI search sub-module or the AI Agents module.

For an example of how to provide a user-facing interface for an AI Assistant, please see the AI Chatbot module's code: this provides a user-facing block plugin that uses a configured AI Assistant to allow users to interact with an AI Assistant and see responses from the LLM.