Advertising sustains the DA. Ads are hidden for members. Join today

On this page

Maestro Tool Task

Last updated on
4 November 2026

Maestro 4.3 and above

Overview

The Maestro Tool Task calls a Tool API tool directly from your workflow. You choose the tool when you build the template, map each of its inputs to fixed text, Maestro tokens or a process variable, and decide where each of its outputs is stored. Maestro then calls the tool the same way, every time the task runs.

No AI is involved. Nothing decides whether or how to call the tool at run time, which makes the Tool Task predictable, repeatable and easy to test. Any tool provided by any module that integrates with Tool API can be used: creating or updating content, sending messages, calling external services and so on.

The Tool Task is a non-interactive (engine) task. It is shown in a sea green colour in the template builder.

Dependencies

  • Maestro 4.3 or above
  • Tool API (tool), version 1.0.0-beta12 or later
  • Optional: Maestro AI Task, if you want to store large tool outputs in a Maestro AI Storage entity
composer require drupal/tool
drush en maestro_tool_task

Who the tool runs as

Tool API checks permissions and access before running a tool. The Tool Task runs the tool as the account the orchestrator is running as. Set Run the orchestrator as in the Maestro engine settings (/admin/config/workflow/maestro) to a dedicated account that has only the permissions your workflows' tools need. If it is left empty, the tool runs as whoever triggered the orchestrator: the user refreshing the Task Console, anonymous for the /orchestrator URL, or the Drush user (drush maestro:orchestrate --user=...). See the Installation page.

Configuring a Tool Task

Add a Tool Task to your template from the task palette and choose Edit Task.

Tool

Choose the tool this task will run. The form then shows that tool's inputs and outputs.

Tool inputs

For each input (required inputs are marked with *), choose where its value comes from:

  • Free text (Maestro tokens allowed): fixed text, tokens such as [maestro:process-variable-value:node_id], or a mix of both. Tokens are replaced as plain text, so a value like Dries' view reaches the tool exactly as typed and not HTML escaped.
  • An existing process variable: the value of the process variable you choose.

Inputs the tool locks are not shown. Optional inputs that end up empty are not sent to the tool.

What to do with the tool outputs

For each output you can keep the whole output, pick out individual values, or both. Outputs you leave alone are discarded.

  1. Keep the whole output?
    • Into a process variable. Text and numbers are stored as is, true/false as "true"/"false", and anything else as JSON. Values longer than 10,000 characters are truncated and a warning is logged.
    • Into a Maestro AI Storage entity (when Maestro AI Task is enabled), for large outputs. Enter an ID using lowercase letters, numbers and underscores. The entity is created the first time the task runs in a process and updated on later runs. Use it in an AI prompt with [maestro:render_ai_task_entity:ID:text].
  2. Also pick out individual values into process variables (JSON output only). Each row copies one value from the output into a process variable. Paths use dots, and numbers pick items from a list: images.0.thumbnail is the "thumbnail" of the first item in "images". A path that is not found sets the variable to an empty value and logs a warning. This option is not offered for outputs that can never hold JSON, such as booleans, numbers and dates.

When a tool fails

The Tool Task always completes, so a failing tool never blocks the orchestrator. When the tool cannot run, the task completes with the Cancelled status and the reason is logged under the maestro_tool_task channel, including the user it ran as. This happens when:

  • no tool is selected, or the selected tool no longer exists;
  • Tool API is older than 1.0.0-beta12;
  • Tool API rejects the call, for example because of missing permissions, access or invalid input;
  • the tool throws an error while running.

Follow the Tool Task with an IF task set to By Last Task Status to handle failures, for example by routing to a person.

Template validity check

The template validity check reports:

  • Tool Tasks with no tool selected, or whose tool no longer exists.
  • Values picked out of an output that can never contain them, which would leave the process variables empty.
  • For information: Tool Tasks that pass an AI Task's answer (through a process variable or AI Storage entity written by an AI Task) into a tool that changes data or starts something. Workflow data can steer an AI answer through prompt injection, and the Tool Task would then run the tool with that answer without anyone reviewing it. Whether that is acceptable is your decision; consider adding a Review Task in between.

Tool Task or AI Task?

  • Use the Tool Task when you know exactly which tool to call and with what inputs. It is deterministic and costs nothing to run.
  • Use the AI Task with the AI Assistant capability when you want AI to decide which tools to call, or to interpret unstructured information.
  • They work well together: an AI Task can classify or extract data into process variables, and a Tool Task can then act on it in a controlled way.

Maestro AI Tools: workflows as tools for AI agents

The Maestro AI Tools module (maestro_ai_tools, Maestro 4.3 and above, requires Tool API) works the other way around. It exposes your public Maestro workflow templates as Tool API tools, so AI agents, AI Assistants and anything else that uses Tool API can discover workflows, start them and check on them.

drush en maestro_ai_tools

It provides these tools:

Tool What it does
Start Maestro Workflow: template
start_maestro_workflow:TEMPLATE_MACHINE_NAME		 One tool per public template. Each process variable in the template becomes a named input, so the AI sees a clear, self describing tool for each workflow. Returns the new process ID.
Start Maestro Workflow (by machine name)
start_maestro_workflow_by_name		 A single tool that starts any public workflow by machine name, with an optional map of process variable values. Useful for workflows created after an agent's tool set was configured. Returns the new process ID.
List Maestro Workflows
list_maestro_workflows		 Lists the public templates the current user may start, with their machine names, descriptions and process variable names.
Get Maestro Workflow Status
get_maestro_workflow_status		 Reports on a process by its process ID: whether it is active or complete, its current stage, which tasks are waiting and who they are assigned to, and recently completed tasks.

Access rules

  • Templates marked private are never exposed and cannot be started through these tools.
  • Starting a workflow requires Maestro's per-template start template permission for that template. The list tool only shows templates the user may start.
  • Workflow status has two levels. Users with view maestro process entities get full details for any process. Users with view maestro task console get basic details (state and dates only) for a process they started or have an open task in, when the template has "show details" turned on. Process variable values are never included, and a process that does not exist is refused in the same way as one the user may not see.

The workflow must be validated before it can be started. Give your templates clear labels and descriptions, because that is what the AI uses to decide which workflow to start.

Help improve this page

Page status: No known problems

You can: