Maestro AI Task

Coming soon to the Maestro 4.x release

Overview

The Maestro AI Task provides a building block for Agentic AI* as it relates to business process and work automation. The goal of business process automation is to increase productivity which can be greatly enhanced by offloading mundane day-to-day tasks to AI while humans can focus on important tasks.

For example, you can use the Maestro AI Task in workflows which

• Currently use human interaction for tasks which are clearly defined and have enough information for AI to action upon them.
• Have complex workflows surrounding content moderation that simple single-step mechanisms just can’t manage.
• Approval workflows which have defined rules that could be offloaded to AI.

The Maestro AI Task is flagged as “experimental” as the Drupal AI ecosystem continues to rapidly evolve.  As the AI ecosystem continues to mature, so too will the Maestro AI Task and eventually will have the “experimental” flag lifted.

The Maestro AI Task module is included as a separate installable module shipped with Maestro core.  The AI Task does not get installed by default with the existing core Maestro tasks. Please refer to the the core Maestro tasks definitions and documentation.

Dependencies

There is a small ecosystem of modules which the Maestro AI Task relies upon.

• Maestro (https://www.drupal.org/project/maestro ) of course!
• Key module (https://www.drupal.org/project/key)
  • AI depends on Key as well.
  • Provides API key management.
• AI module (https://www.drupal.org/project/ai)
  • The de facto module for use with AI development on the Drupal platform.
  • Provides configuration and developer abstraction for the various AI platforms.
• AI Logging (optional)
  • Sub-module of the AI module which provides logging of AI API calls.
  • This module may be helpful when debugging your AI prompts

You must have all three of those modules installed and configured prior to being able to install the Maestro AI Task module.

Please refer to the specific installation instructions for the AI and Key modules and how you create an API key for the AI providers you wish to work with. 

As an overview, you would:

• Install all the required modules.
• Configure Maestro (you may have already done this)
• Configure your API keys via the Key module’s administrative interface found at https://yoursite/admin/config/system/keys
• Configure the AI module’s provider settings found at https://yoursite/admin/config/ai/settings

How Maestro Talks to the Configured AI Providers - Maestro AI Task Capability Plugin

The AI module provides a number of configurable AI Providers for capabilities such as chat, translate text, text to image, chat with image vision and so on and are shown on the AI module settings page.  Maestro uses the configured default AI providers in conjunction with what’s known as a Maestro AI Task Capability Plugin to know how to talk and send Maestro information to your AI service.

The Maestro AI Task Capability Plugin is a pre-coded mechanism that provides configuration and execution “smarts” to help you plug your Maestro AI Task into your workflow templates.  Maestro AI Tack Capabilities that are currently available support

• Chat - chatbot capabilities
• Text to Image - saving an image to the filesystem
• Text to Image - saving a Base64 image to the database inside of a Maestro AI Storage entity
• Chat with Image Vision - sending an image and prompt to the AI service for processing

When configuring your Maestro AI Task, you will be presented with a list of configured AI module providers which have a corresponding Maestro AI Task Capability.  If it does not appear in the list, a Maestro AI Task Capability will have to be written to support it.

Over time, the number of pre-written Maestro AI Task Capabilities will grow. Developers are able to write Maestro AI Task Capabilities to suit their own requirements, making the Maestro AI Task incredibly powerful and extensible.

You can have more than one Maestro AI Task Capability for every configurable AI Module Provider.  This allows developers to create finely tuned plugins for the MAT that address configuration and execution requirements.  

Specifically, Task Capabilities provide the following functionality:

• Configuration form elements
  • These elements appear in the “Configured AI Providers Available" when you’ve selected a radio button option.
• Validation for configuration form save
  • Preparation of the Task configuration options prior to saving
• Execute the AI call
  • This is where each Maestro AI Task Capability fine-tunes the configured options into a call to the AI service you’ve configured.
• Task Validity Check
  • For use during the Maestro Template validity checker.
  • If there’s anything that the capability should/shouldn't have in its configuration, you have the option to flag it.
  • Let the MAT know if it makes sense for the capability to allow for a customizable return format or not.

Maestro AI Task General Configuration

The Maestro AI Task has a general configuration section found under Configuration - Workflow - Maestro AI Admin settings.

• Base Prompt - When you create a Maestro AI Task in a Template, the Prompt configuration field will be auto-filled with the Base Prompt configured here.
• Test Mode and AI Testing Response - When Test Mode is checked, the AI Testing Response will be used as the return data for EVERY SINGLE Maestro AI Task in the system.  
  • You can turn on Test Mode on specific Maestro AI Tasks from within the Maestro AI Task edit panel.
  • This is a very handy option to use when setting up a workflow that has AI so that you can test workflow operation.
  • This is a way to quickly disable AI LLM calls in the event there are issues in your system.

Configuring a Maestro AI Task

You add a Maestro AI Task (MAT) into your Maestro Template as you would any other task.  The MAT is a non-interactive task meaning that its execution is performed by the Maestro Engine and does not require human intervention.  

At its core, AI service providers require information that you provide it to function.  This generally comes in the form of a prompt and sometimes uploaded files. The MAT is no different.  You are able to configure the MAT with prompt and file data (operation dependent) so that the AI service provider can fulfill the request.

We’ll look at the MAT configuration in two portions.  

The first portion options are

• Label - Self explanatory. The label that appears on the task in the Template Builder
• Participate in Setting the Workflow Stage and Status Message? - Refer to the core task documentation about this item.
• Hold this task open if the AI response is NULL? - If the Maestro AI Task Capability returns a NULL from the AI call, when checked, this option will prohibit the Maestro AI Task from completing and will keep the task resident in the Maestro Queue.  That means the task will re-execute on the next Maestro Engine cycle.
  • Be warned that this could cause an increase in AI Service costs if your AI calls “fail” continuously.
  • Depending on the use case, your Maestro AI Task Capability plugin may return NULL to purposefully cause the task to not complete.  This type of implementation is 100% up to you to determine if it is appropriate.
  • An example of this would be to let AI make a decision about something and to never complete the task until AI says to do so.
• Log the response from AI? - This may be redundant if you are using the AI Logging module.  
  • When checked, the Maestro AI Task will send a log message to the Drupal Recent Log Messages (watchdog).
• Configured AI Providers Available - This section is provided by the Maestro AI Task Capabilities plugins available on the system as an intersection between which AI Module Providers are configured and which Maestro AI Task Capabilities are able to interface with those configured AI Module Providers.
• 
  • In this example, we have the AI Module configured to have a default provider for
    • Chat
    • Text to Image
    • Chat with Image Vision
  • We show 4 options because we have two Maestro AI Task Capabilities that can interface with the Text to Image provider. This is where developers can write their own Maestro AI Task Capabilities plugins to be able to perform whatever prompt and data manipulation you require.
  • When you choose an AI Provider, the selected capability can provide you with the configuration options available.  For example, here we’ve chosen the Text to Image saving the image as a physical file option:
  • Different selected Providers will produce different configuration options.
  • An important feature of the Maestro AI Task Capabilities is that they are able to declare whether or not their response can be forced to a True/False, Yes/No or custom response format. For example, the Chatbot option provides a customizable return format as shown here:
  • 
  • The options are
    • Return as a single JSON encoded string specifying Yes or No response
    • Return as a single JSON encoded string specifying True or False response
    • A custom response format specified
  • That means as a Maestro AI Task administrator, you’ll need to be aware of how you are crafting your prompts. Later on, you’re able to configure how you’re processing the task including to process the task based on what’s returned.  That means if you’re not returning a TRUE/FALSE or YES/NO response, your task may complete, but set a Maestro Task Status you’re not expecting.

The second portion options are

• Prompt - The prompt you wish to send to the configured AI mechanism.
• Test Mode - When checked the task’s output is forced to a configurable test response.
  • A test response option will appear when checked.
  • You can configure a global test response option as well in the Maestro AI Task configuration.
  • This is what it looks like when the Test Mode option is enabled:
  • 
• Return the data into a process variable, AI Storage entity or process directly in this task - Options available are
  • Process in task
    • If you’ve chosen this option, your prompt MUST return a YES/NO or TRUE/FALSE return.
  • Set a process variable with the return data (max 255 characters)
    • Process variables are simple textual storage mechanisms that are not designed to store large amounts of data.
  • Set a Maestro AI Storage entity with the return data (large data)
    • Up to 16 Megabytes
    • Stored in the database in a  MEDIUMBLOB column
    • Maestro AI Task API available to retrieve the data from the Maestro AI Storage mechanism.

Maestro AI Task API

You will find an API for the Maestro AI Task that provides methods to help you access the Maestro AI Storage entity that is used to store large amounts of data.

You will find the AI API in the src/MaestroAiTaskAPI folder of the Maestro AI Task.

namespace Drupal\maestro_ai_task\MaestroAiTaskAPI;

* - Agentic AI:

The Maestro AI Task relies upon the AI Service you've configured. The AI Service could be offerings from the major vendors in the AI LLM space or could be an AI provider running internal to your environment.  The Maestro AI task use case is to

• have minimal human intervention
• make decisions
• take actions

All the while your workflow templates are used to steer towards the ultimate goal of a business process you're trying to automate.  You can break down complex processes or procedures into multiple Maestro AI Tasks all marshalled through the Maestro Engine.