On this page
- Overview
- Dependencies
- How Maestro talks to AI providers: Maestro AI Task Capability plugins
- Maestro AI Task general configuration
- Configuring a Maestro AI Task
- Task options
- Return format
- Prompt, test mode and where the answer goes
- Image and audio sources from process variables
- AI Assistants (tools and agents)
- Moderation in task
- Security: untrusted data, guardrails and tools
- Example workflows
- Maestro AI Task API
- Exposing workflows to AI agents
Maestro AI Task
Maestro 4.x release and above
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, and that can be greatly enhanced by offloading mundane day to day tasks to AI so people can focus on the important ones.
For example, you can use the Maestro AI Task in workflows which:
- Currently use human interaction for tasks that are clearly defined and have enough information for AI to act on.
- Have complex content moderation needs that simple single step mechanisms can't manage.
- Include approvals with defined rules that could be offloaded to AI.
- Need to read a document or image, transcribe audio, generate an image or classify text as one step in a larger process.
The Maestro AI Task is flagged as experimental while the Drupal AI ecosystem continues to evolve quickly. As the ecosystem matures, so will the AI Task, and the experimental flag will eventually be lifted.
The Maestro AI Task module ships with Maestro as a separate, optional module. It is not installed with the core Maestro tasks. See the core Maestro task types documentation.
Dependencies
- Maestro (https://www.drupal.org/project/maestro) of course!
- Key module (https://www.drupal.org/project/key)
- Provides API key management. The AI module depends on Key as well.
- AI module (https://www.drupal.org/project/ai)
- The standard module for AI development on Drupal. Provides configuration and a developer abstraction for the various AI platforms.
- Optional: AI Logging, a sub-module of the AI module that logs AI API calls. Helpful when debugging your prompts.
- Optional: AI Assistant API, a sub-module of the AI module. Required by the Maestro AI Task Assistant Capability module described below.
Maestro, Key and AI must be installed and configured before you can install the Maestro AI Task module. Refer to the AI and Key module documentation for how to create API keys for the AI providers you want to use. As an overview, you would:
- Install the required modules.
- Configure Maestro (you may have already done this).
- Configure your API keys in the Key module at /admin/config/system/keys.
- Configure the AI module's default providers at /admin/config/ai/settings.
- Enable Maestro AI Task, and optionally Maestro AI Task Assistant Capability and Maestro AI Task Vision Example.
How Maestro talks to AI providers: Maestro AI Task Capability plugins
The AI module lets you set a default provider for each operation type, such as chat, chat with image vision, text to image, speech to text and moderation. Maestro pairs those default providers with Maestro AI Task Capability plugins. A capability plugin knows how to configure and run one kind of AI call from a workflow.
The capabilities shipped with Maestro are:
| Capability | AI operation type | What it does |
|---|---|---|
| Chatbot | Chat | Sends your prompt to the chat provider and returns the answer. Supports a configurable return format. |
| Chat with Image Vision | Chat with image vision | Sends your prompt and an image to the provider, for example to read a receipt or check a photo. |
| Text to Image (file) | Text to image | Generates an image, saves it as a file in the public or private file system and returns its URL. |
| Text to Image (Base64) | Text to image | Generates an image and returns it as a Base64 encoded string, normally stored in a Maestro AI Storage entity. |
| Speech to Text | Speech to text | Transcribes an audio file and returns the text. You can set the audio language. |
| Moderation | Moderation | Checks the prompt text with the moderation provider. Only returns output when the input is flagged, and then returns the highest flagging result. |
| AI Assistant (tools/agents supported) | Chat | Provided by the optional Maestro AI Task Assistant Capability module. Hands the prompt to an AI Assistant you have built, including its own tools, agents and system prompt. |
When you edit an AI Task, you only see capabilities whose AI operation type has a default provider configured in the AI module. If a provider you configured does not appear, a capability plugin has to be written for it. You can have more than one capability for the same operation type (for example the two Text to Image capabilities), so developers can create finely tuned plugins for their own needs.
A capability plugin provides:
- Configuration form elements, shown when you select that capability.
- Validation and preparation of its settings when the task is saved.
- Execution of the AI call, turning your configured options into a request to the provider.
- A task validity check, used by the Maestro template validity checker.
- Whether its answer can be shaped with a configurable return format (Yes/No, True/False or custom).
- Whether workflow data in its prompt should be marked as untrusted data (see Security below).
Maestro AI Task general configuration
The general settings are under Configuration > Workflow > Maestro AI Task Settings (/admin/config/workflow/maestro_ai).
- Base Prompt: when you add a new AI Task to a template, its Prompt field is pre-filled with this text.
- Test Mode and AI Testing Response: when Test Mode is checked, the AI Testing Response is used as the answer for EVERY SINGLE AI Task on the site and no AI calls are made.
- You can also turn on Test Mode for individual AI Tasks in the task's edit form.
- This is very handy when you are building a workflow that uses AI and want to test the flow without paying for AI calls.
- It is also a quick way to stop all AI calls if something goes wrong on your site. A warning is shown on every AI Task edit form while global Test Mode is on.
Configuring a Maestro AI Task
You add a Maestro AI Task (MAT) to your template like any other task. The MAT is a non-interactive task: the Maestro engine runs it without human intervention.
AI providers need information to work, usually a prompt and sometimes a file. You give the MAT a prompt, and depending on the capability, an image or audio source, so the provider can fulfil the request.
Task options
- Label: the label shown on the task in the template builder.
- Participate in setting the workflow stage and status message?: see the core task documentation for this setting.
- Hold this task open if the AI response IS NULL?: when checked and the capability returns NULL, the task does not complete. It stays in the Maestro queue and runs again on the next orchestrator run.
- Be warned: this can increase your AI costs if your calls keep "failing".
- A capability may return NULL on purpose to keep the task open, for example to let AI keep checking something until it says the task is done. Whether that is appropriate is up to you.
- Log the response from AI?: when checked, the AI answer is written to the Drupal log (Recent log messages). This may be redundant if you use the AI Logging module.
- Configured AI Providers Available: choose which capability this task uses. The list is the intersection of the AI module's configured default providers and the capability plugins on your site. Choosing a capability shows its own settings:
- Chatbot: the return format (see below).
- Chat with Image Vision: the image source. Choose a manually entered URL, a Maestro AI Storage entity, a process variable or a local file path relative to your site root.
- Speech to Text: the audio language (or any ISO-639-1 code) and the audio source, with the same source options as Vision.
- Text to Image (file): the public or private file system, the file name (without extension), the path (tokens allowed, created if it does not exist) and whether to return a browser accessible image URL.
- AI Assistant: the AI Assistant to use and optional post-processing instructions (see below).
Return format
Capabilities that support it, such as Chatbot, let you ask the AI to answer in a fixed format:
- A single JSON encoded string with a YES or NO answer
- A single JSON encoded string with a TRUE or FALSE answer
- A custom response format you specify
The return format instruction is added after your prompt, so it is the last instruction the model reads. Craft your prompts with the return format in mind: if you process the answer in the task (see below), the answer must be a Yes/No or True/False JSON response.
Prompt, test mode and where the answer goes
- Prompt: what you want the AI to do. Maestro tokens are replaced before the call, for example
[maestro:process-variable-value:topic]to include a process variable, or[maestro:render_ai_task_entity:ID:text]to include a Maestro AI Storage entity. Enable the Token module to browse the available tokens from the form. Some operation types, such as Speech to Text, do not use the prompt; for those, any non-blank prompt will do. - Test Mode and Testing Response: when checked, this task returns the Testing Response instead of calling AI. The default testing response is
{"result":"true"}. This overrides the global setting. - Return the data into a process variable, AI storage entity or process directly in this task:
- Process in task: the task decides its own outcome from the answer. The answer must be JSON with a
resultof true/false or yes/no, for example{"result":"true"}.- true or yes: the task completes successfully.
- false or no: the task completes with the Cancelled status.
- Anything else (not JSON, or no valid
result): the task completes with the Aborted status and a warning with the start of the response is logged.
Follow the AI Task with an IF task set to By Last Task Status to branch on the outcome. You cannot save a custom return format together with Process in task.
- Set a process variable with the return data (max 255 characters): the answer is stored in the process variable you choose and truncated to 255 characters. Process variables are not designed for large amounts of data.
- Set a Maestro AI Storage entity with the return data (large data): the answer is stored in a Maestro AI Storage entity. Pick an existing storage label used in this template, or create a new one. The entity is created the first time the task runs in a process and updated on later runs. The ID
maestro_ai_task_historyis reserved by Maestro.- Up to 16 megabytes, stored in the database in a MEDIUMBLOB column.
- Use it in later prompts with
[maestro:render_ai_task_entity:ID:text], or retrieve it in code with the Maestro AI Task API.
- Process in task: the task decides its own outcome from the answer. The answer must be JSON with a
Image and audio sources from process variables
Process variable values often come from end users (webform submissions, interactive tasks, AI tools), so Maestro does not use them as raw paths. When a Vision or Speech to Text task reads its file from a process variable, the value must be one of:
- A managed Drupal file ID that the process initiator is allowed to download, or
- An https:// URL whose host resolves only to public IP addresses. Redirects are not followed and downloads are capped at 25 MB.
The media type is detected from the file contents, not from its name or headers. If the value does not pass these checks, the reason is logged and the call is not made.
AI Assistants (tools and agents)
Enable Maestro AI Task Assistant Capability to let an AI Task hand its prompt to an AI Assistant built at /admin/config/ai/ai-assistant. The Assistant brings its own system prompt, tools and agents, so a single AI Task can, for example, search content or call other tools before answering.
- AI Assistant: the Assistant this task delegates to.
- Post-processing instructions (optional): an Assistant's raw answer may not be in the shape your workflow needs. If you enter instructions here, the Assistant's answer is passed through one more, separate AI call with these instructions, for example "extract a JSON object with keys score and justification" or "summarize in one sentence". Leave it blank to use the Assistant's answer as is.
- When the task is set to Process in task and you leave the post-processing instructions blank, Maestro automatically uses a default instruction that turns the answer into
{"result":"true"}or{"result":"false"}. If you write your own instructions, they must produce that shape themselves. - If no Assistant is configured, the Assistant no longer exists or the call fails, the task completes with the Aborted status and the error is logged.
Moderation in task
When a Moderation task is set to Process in task, it completes successfully when the input is not flagged and with the Cancelled status when it is flagged.
Security: untrusted data, guardrails and tools
Workflow data such as form submissions, uploaded files and earlier AI answers may be written by people you do not trust, and could contain text that tries to change what the AI does (prompt injection). The AI Task includes several protections:
- Untrusted data markers. For the Chatbot and Chat with Image Vision capabilities, every token value in your prompt is wrapped in
<maestro_data>tags, and the model is given a system prompt telling it to treat that content, and any attached image or file, strictly as data and never as instructions. Write your instructions in the prompt itself and bring workflow data in with tokens so it is marked this way. - AI module guardrails. If an AI module guardrail stops a Chatbot or Vision call, Maestro does not treat the guardrail's message as the answer. Nothing is stored, the task completes with the Aborted status and the guardrail details are logged. The task is not held open, so the same stopped call is not repeated on every orchestrator run.
- Aborted versus Cancelled. Cancelled always means a real "no" or "false" answer. Aborted means there was no usable answer (a guardrail stopped it, the response was malformed or the call failed). Use an IF task to send these down different paths, for example to a person for review.
- AI answers feeding tools. If a Tool Task passes an AI Task's answer into a tool that changes data or starts something, the template validity check lists it as information so you can decide whether a review step is needed in between.
Example workflows
Enable Maestro AI Task Vision Example to install two expense receipt checking workflows, a simple one and a complex one, with their webforms. They need a Chat with Image Vision provider configured in the AI module.
Maestro AI Task API
The API for the Maestro AI Task is in the src/MaestroAiTaskAPI folder of the module:
namespace Drupal\maestro_ai_task\MaestroAiTaskAPI;It includes methods to:
- Fetch a Maestro AI Storage entity or its value by its unique ID and process ID (
getAiStorageEntityByUniqueId(),getAiStorageValueByUniqueId()). - Save a value into AI Storage from your own code (
saveAiStorageValue()). - List the AI Storage IDs used in a template (
getAiStorageEntityDefinitionsInTemplate()). - Convert a Base64 image in AI Storage into a file (
convertBase64AiStorageImageToFile(),saveBase64ImageToFile()). - Safely load image or audio media referenced by a process variable (
loadProcessVariableMedia()). - Create a capability plugin instance (
createMaestroAiTaskCapabilityPlugin()).
To render an AI Storage entity in a token with your own render_as type, implement hook_maestro_ai_task_render_ai_entity(). The built in types are text and base_64_image_url. See maestro_ai_task.hooks.api.php.
Exposing workflows to AI agents
To go the other way, letting AI agents and assistants start and check on Maestro workflows, see Maestro AI Tools on the Maestro Tool Task page.
* Agentic AI:
The Maestro AI Task relies on the AI service you configure. That could be one of the major AI vendors or a provider running inside your own environment. The Maestro AI Task use case is to:
- have minimal human intervention
- make decisions
- take actions
All the while, your workflow templates steer the work toward the goal of the business process you are automating. You can break complex processes down into multiple AI Tasks, Tool Tasks and human tasks, all coordinated by the Maestro engine.
Help improve this page
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion