Agent tool output key

Tools within an AI Agent sub-process return their results to the agent through the toolCallResult variable. The rule reports one warning per tool in either of the following situations:

1. Misdirected result: The tool sets result variables, but none of them is named toolCallResult, for example, because of a typo such as toolCalResult. The rule reports the warning on the element that set the wrong variable, which can be downstream of the tool's entry element.
2. No result: No element in the tool's flow sets a result variable. The rule reports the warning on the tool's entry element, because no single element is at fault. Even a fire-and-forget tool should report its completion, for example, with = "Email sent.".

How a tool can set toolCallResult

The result can be set anywhere in the tool's flow through several channels:

• Output mapping: Target toolCallResult or one of its fields, such as toolCallResult.statusCode.
• Connectors: Use the Result variable or Result expression field, for example, = { toolCallResult: response.body }. This is the only available channel because connectors cannot read process variables.
• Script tasks and business rule tasks: Set the Result variable to toolCallResult.

Avoid overwrites when several elements contribute

Assigning a value to toolCallResult twice overwrites the first value:

To add a field without overwriting the existing value, use context put() in an output mapping:

= context put(toolCallResult, "confirmation", sendResult)

This works only for elements that run in the workflow engine. Connector result expressions cannot read the current value of toolCallResult, so a connector tool must build its complete result in a single expression.

What the rule cannot see

Results written by arbitrary FEEL expressions elsewhere, such as a variable set by a called process, cannot be detected statically. Ignore the warning or make the result wiring explicit with an output mapping.

The result variable name

This rule always checks for toolCallResult, the default used by the AI Agent connector. An AI Agent Task's multi-instance ad-hoc sub-process can rename this variable by changing the multi-instance Output element value. If you rename it, ignore the warning for that tool.

Result never reaches the agent

The tool maps its output to result instead of toolCallResult, or no element in its flow sets a result at all.

toolCallResult set on an element in the tool flow

An output mapping targets toolCallResult or one of its fields, such as toolCallResult.statusCode; a connector result expression contains a toolCallResult key; or a script task's result variable is toolCallResult.

Declare a sub-process as agentic

This rule applies only within an ad-hoc sub-process recognized as a tool container. Camunda's provided AI Agent element templates are compatible with this rule, regardless of the template version. An ad-hoc sub-process is recognized as a tool container in either of the following ways:

• Its zeebe:modelerTemplate attribute is set to io.camunda.connectors.agenticai.aiagent.jobworker.v1, which identifies the AI Agent job worker template. Any version of this template is supported.
• It has a zeebe:property named io.camunda.agenticai.toolContainer with the value true, regardless of whether its tools are invoked by an AI Agent task in the same process or in a separate process. Starting with Camunda 8.10.0-alpha4, the out-of-the-box AI Agent element templates add this property automatically. This property is the supported long-term approach.

If you are not using an out-of-the-box template, or if your template version predates this change, add the property manually. Select the ad-hoc sub-process, open the Extension properties section in the properties panel, and add a property named io.camunda.agenticai.toolContainer with the value true. The property appears as a standard extension property rather than as a dedicated control:

In the XML, the property appears as follows:

<bpmn:adHocSubProcess id="Tools">
  <bpmn:extensionElements>
    <zeebe:properties>
      <zeebe:property name="io.camunda.agenticai.toolContainer" value="true" />
    </zeebe:properties>
  </bpmn:extensionElements>
</bpmn:adHocSubProcess>

References

• AI Agent tool definitions
• Rule source