Skip to main content

AI Agent

2025.1.01+

Introduction

The AI Agent Task allows to execute an AI Agent of the type utility, document, knowledge and external.

Properties

General

AttributeTypeDescriptionCategory
Model Id Text

Model Id identifies the element within the process model.

Name Expression usage possibleText

The name of the element. This is the name displayed in the diagram.

Documentation Multiline Text

A free-form text that can be used to explain details about the particular element.

Store result variable transiently Boolean

Flag that marks that the result of the expression will not be persisted at the end of the database transaction. Use this if you do not want to store a result after the next wait state, e.g. if you only need access to the result inside a condition.

Agent Model RequiredAgentModel

Link to an AI Agent model (required)

In same deployment Boolean

Set it to true if the referenced definition should be referenced from within the same app deployment. Set it to false to always use the newest definition.

Multi Instance

Multi instance

AttributeTypeDescriptionCategory
Multi instance type RequiredSelection:
  • None
  • Parallel
  • Sequential

The type of multi-instance: default is 'None' meaning a single instance is created at runtime. Select either 'Parallel' or 'Sequential' if you want multiple instances to be created.

Collection Expression usage possibleText

References a collection variable (for example a JSON array variable) by its name or using an expression that resolves to a collection.

Element variable Text

The name of the variable where the currently processed element from the multi-instance collection configured above will be stored (for example, 'invoicePosition').

The element can then be accessed through an expression, e.g., ${invoicePosition}.

Element index variable Text

The name of the variable where the index of the currently processed item from the multi-instance collection will be stored, for example, 'itemIndex'. The index is a number starting with 0 which is increased with every element that is being created. The index can then be accessed through an expression, e.g., ${itemIndex} further on in the process.

Cardinality Text

A fixed number or an expression that resolved to an integer that controls the number of instances that will be created.

This is typically used when there is no collection available or needed.

Completion condition Expression usage possibleText

An expression that should resolve to a boolean value. When evaluating to true, the remaining activity instances will be removed and the process instance will continue.

Variable aggregation

AttributeTypeDescriptionCategory
Variable Aggregations List

Define an aggregation. Each element in this list will result in one aggregation variable.

Advanced

AttributeTypeDescriptionCategory
Optimize for only automatic steps Boolean

(Advanced setting, only check it if you understand the implications) If checked, this instructs the Flowable engine that the multi-instance only contains automatic tasks and no wait states. In this situation, an asynchronous job is created when the multi-instance activity is entered that keeps checking if all instances are completed and completes the multi-instance. The benefit of this approach is that it is light on resources versus alternatives and doesn't lead to optimistic locking exceptions.

Advanced

Execution

AttributeTypeDescriptionCategory
Skip expression Expression usage possibleText

If the Skip expression evaluates to true, the flow is taken regardless of any condition.

It is required to opt-in to this feature by setting a variable _FLOWABLE_SKIP_EXPRESSION_ENABLED with the Boolean value true on the process instance.

Include in history Boolean

When the history level is set to "instance" or "task" level with this property it can be configured if this activity instance should be included in the historic activity data.

Is for compensation Boolean

Determines whether the activity can serve as a compensation for another activity.

Asynchronous Boolean

When enabled, the activity will be started as an asynchronous job. The process state is persisted before this element is executed. Then, the process execution will be resumed asynchroneously. This can be used when the execution an activity takes a long time to return the UI to the user quicker in case the user does not need to see the next step immediately. However, if an error occurs before the following wait state, there will be no direct user feedback. Please refer to the documentation for more details.

Exclusive Boolean

Determines whether the activity or process is run as an exclusive job. An exclusive job makes sure that no other asynchronous exclusive activities within the same process are performed at the same time. This helps to prevent failing jobs in concurrent scenarios.

Leave asynchronously Boolean

When enabled, the activity will be left as an asynchronous job. This means that the activity is ended asynchronously, including end execution listeners. Please refer to the documentation for more details.

Leave exclusive Boolean

Determines whether the activity should leave as an exclusive job. An exclusive job makes sure that no other asynchronous exclusive activities within the same process are performed at the same time. This helps to prevent failing jobs in concurrent scenarios.

Job Category Expression usage possibleText

When set, the underlying generated job will have a Job Category, which will be executed only by Application Servers, where the Process Engine has enabledJobCategories set to this category.

Advanced options

AttributeTypeDescriptionCategory
Exception Mappings List

Define one or more exception mappings to map a technical Java exception to a BPMN error code.

Failed job retry time cycle ComplexTrigger

Service task logic defined with a failed job retry time cycle

Listeners

AttributeTypeDescriptionCategory
Execution listeners List

Allows invoking custom after certain lifecycle events.

Start: Executes after the activity has been started.

End: Executes after the activity was completed.

Transition: When defined on a sequence flow, executes once the flow is transition is taken.

Visual

AttributeTypeDescriptionCategory
Background color RequiredColor

The background color of the element in the diagram.

Font size Selection:
  • 8
  • 9
  • 10
  • 11
  • 12
  • 14
  • 18
  • 20
  • 24
  • 36
  • 48
  • 72

Font size.

Font weight Selection:
  • Normal
  • Bold

Select the style between bold and normal.

Font style Selection:
  • Normal
  • Italic

Select the style between italic and normal.

Font color Color

Select a font color.

Border color RequiredColor

The border color of the element in the diagram.

List Attribute Details

Variable Aggregations

AttributeTypeDescription
Target (Variable / Expression) RequiredExpression usage possibleText

The name of the target variable or an expression that gives the variable name

Type RequiredSelection:
  • Default
  • Custom

The type of aggregation. Use 'default' to use the standard behavior of creating an aggregation JSON variable. Use 'custom' to define a delegate expression that will handle the aggregation. Please see the documentation for more information.

Delegate Expression Expression usage possibleText

Define a delegateExpression that will resolve to an instance of VariableAggregator (for BPMN) or PlanItemVariableAggregator (for CMMN). This instance will then be responsible for aggregating the variables.

Class String

A class that implements VariableAggregator (for BPMN) or PlanItemVariableAggregator (for CMMN). This instance will then be responsible for aggregating the variables.

Target variable creation RequiredSelection:
  • Default
  • Create overview variable
  • Store as transient variable

Configures the way the aggregation variable is created. The 'Default' option creates the aggregation variable when all instances of the multi-instance have been completed. Use 'Create overview variable' to create a variable at the start of the multi-instance and keep it up to date during multi-instance exeution. Once all the instances are completed it will create a JSON variable in the same way as for Default target variable creation. Use the 'Store as transient variable' option to have the default behavior, but store the resulting aggregation variable transiently.

Variable Definitions BasicFormList

property.loopVariableAggregation.definitions.description

Variable Definitions

AttributeTypeDescription
Source (Variable / Expression) RequiredExpression usage possibleText

The name of the source variable or an expression that provides the value

Target (Variable / Expression) Expression usage possibleText

The name of the aggregation variable or an expression that resolves to a variable name.

Exception Mappings

AttributeTypeDescription
Error code RequiredText

The code of an error definition.

Exception class name Text
Root cause Text
Include child exceptions Boolean

Failed job retry time cycle

AttributeTypeDescription
Time cycle RequiredText

Execution listeners

AttributeTypeDescription
Event RequiredSelection:
  • Start
  • End
  • Take

The lifecycle event. The 'Take' event is only available for sequence flow.

Class Text

Fully qualified classname of a class to be invoked when executing the task. The class must implement either JavaDelegate or ActivityBehavior.

Expression Text

JUEL Expression to be executed when the task is started. Expressions allow you to interact with the backend by calling services, making calculations etc. You can find more information about expressions in the documentation.

Delegate expression Text

Delegate Expression to be executed when the task is started. A delegate expression must resolve to a Java object, for instance a Spring bean. The object's class must implement either JavaDelegate or ActivityBehavior.

Fields List

Fields

AttributeTypeDescription
Name Text

The name of the element. This is the name displayed in the diagram.

String value Text
Expression Text

JUEL Expression to be executed when the task is started. Expressions allow you to interact with the backend by calling services, making calculations etc. You can find more information about expressions in the documentation.

String Text