Agent fromAi() contract

The fromAi() FEEL function declares a tool's LLM-supplied inputs within an AI Agent sub-process. A malformed call resolves to nothing at runtime without producing an error, so malformed calls are reported as errors. A call without a description is valid and is not reported.

Contract breaks

The rule reports the following problems:

• Key is not a FEEL path: The first argument must be a path expression, such as toolCall.url, rather than a string literal, number, null, bracket notation, or conditional expression.
• Key does not start with toolCall.: The connector populates only fields in the toolCall context.
• Key is nested: The connector uses only the last path segment as the parameter name. Use a single name, such as toolCall.filter.
• Key is declared twice in one tool: Duplicate keys collide because a tool's fromAi() calls are combined into a single input schema.
• Wrong function-name casing: The function name is case-sensitive. Use fromAi.
• Description is not a string literal: The description must be a quoted string, for example, fromAi(toolCall.url, "The URL to fetch.").
• fromAi() is in the wrong place: The function is valid only in an input mapping on the tool's entry element—the activity with no incoming sequence flow. Anywhere else, it resolves to null:

Correct fromAi() usage

Use a single-segment toolCall path with a description:

= fromAi(toolCall.url, "The URL to fetch. Must be an absolute URL including scheme.")

A fromAi() call within an ad-hoc sub-process that is not recognized as a tool container is also reported. If the tool is not intended to be agent-driven, remove the fromAi() call instead.

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>

Clicking this report in the Problems panel selects the tool task rather than the ad-hoc sub-process. To add the property, select the sub-process directly in the diagram. The Problems panel does not navigate to it for you.

References

• AI Agent tool definitions
• fromAi() FEEL function
• Rule source