How to Model BPMN AI Agents

An AI Agent is modelled exactly like a human participant in a BPMN process. The difference is that the participant reasons with an LLM and interacts with the workflow through Tool Calls instead of a graphical user interface.

That single idea explains most of what follows: everything you would normally do to make a task understandable to a person — a clear description, a well-labelled form, meaningful event names — is exactly what makes it understandable to the agent. You're not configuring an AI feature; you're describing a role.

This page shows how to write that description in practice: the system prompt, the BPMN documentation fields the agent reads, and the form definitions it uses to know what data to collect. See AI Agents for the underlying concept and for the Tool Calls an agent can use, and Working with Skills for how to give an agent domain-specific knowledge.

System Prompt

The system prompt is where you tell the agent what its role is, what it should do, and what data it's allowed to touch. It's attached directly to the task in the BPMN model and is only loaded once, at the start of the conversation.

A prompt that extracts data and links it to a related record:

<?xml version="1.0" encoding="UTF-8"?>
<PromptDefinition>
  <options>{"n_predict": 4096, "temperature": 0 }</options>
  <prompt role="system"><![CDATA[
You are a car rental manager. A new fine has been received.

Extract the fine data and write it into the current workitem using the tool call
"update_workitem". Use exactly the following field names and types:

 - "fine.id" (string) - the allotted fine/case ID
 - "fine.plate.number" (string) - the plate number, preserved exactly as it appears
 - "fine.violation.date" (date) - the day of the violation
 - "payment.amount" (double) - the amount to pay
 - "payment.duedate" (date) - the date by which the amount must be paid

Only include fields for which you actually found data. Do not guess.

After writing the fine data, use the tool call "link_workitem" to search for the matching
leasing contract and link it to the current workitem in one step. Pass the extracted plate
number as the value for the index field "id", and the fixed value "Contract" for the index
field "$workflowgroup" inside the criteria parameter. Also pass "contract.ref" as the
refField parameter. Example: {"criteria": {"id": "M-AH-4524", "$workflowgroup": "Contract"},
"refField": "contract.ref"}

If link_workitem reports exactly one linked match (linkedCount: 1), call task_complete with
a short one-sentence summary in the result parameter.

If link_workitem reports zero or more than one linked match, do not call task_complete.
Instead respond with a short plain-text note that a manager needs to review the case.
]]>
</prompt>
<prompt role="user"><itemvalue>fine.summary</itemvalue></prompt>
</PromptDefinition>

Three lessons apply to almost every prompt you write for an agent:

Show, don't just describe. A tool's schema alone is rarely enough — always include a concrete example of the exact argument structure, including parameters that don't vary. Smaller models tend to drop optional-looking parameters otherwise.
Let the tool decide, not the model's guess. Base branching decisions (e.g. “call task_complete or not”) on a value the tool result actually reports — such as linkedCount — rather than something the agent would have to count or infer itself.
Keep field names consistent. The names you tell the agent to search or write must match what's actually indexed on the target process exactly — a mismatched workflow group or a differently formatted plate number won't error, it will just silently return zero matches.

BPMN Descriptions

An AI Agent understands your business process the way it understands anything else — through language. Before every agent run, the platform assembles a plain-text overview of your accessible processes from their descriptions, and the LLM matches the user's request against it. This works across languages and phrasings — a user typing “Ich brauche Urlaub” reliably triggers a process whose initial task is described as “A new vacation request has been submitted by an employee”, because the model recognizes the meaning, not just the words.

This means: your descriptions are the agent's knowledge base. There is no other source of truth.

BPMN models carry documentation at three levels, each serving a different purpose for the agent:

Level	Location in BPMN	Purpose for the Agent
Model Documentation	Top-level documentation of the entire `.bpmn` file	Defines the domain — “what area does this model cover?”
Process Documentation	Documentation on the Pool or the main Process element	Describes the business purpose of a specific process
Initial Task Description	Description field of the first Task in the process	Describes what happens at the point of initiation

Think of it as a funnel: Model Documentation sets the domain, Process Documentation narrows it to a specific process, and the Initial Task Description anchors it to the concrete starting situation.

Model Documentation — a plain-language summary of what the model covers:

This model covers all HR-related processes for employees and managers,
including leave requests, expense reports, onboarding workflows
and internal approvals.

Process Documentation — describes the process in business terms, not technical steps:

The vacation request process handles all types of employee leave,
from standard annual leave to special occasions.
It ensures compliance with company policy and provides
a transparent approval trail.

Initial Task Description — the most specific layer. It should tell the agent what the process is about, who typically initiates it, and what happens as a result.

Too vague:

Initial task for the HR department.

Good:

A new vacation request has been submitted by an employee.
The request needs to be reviewed and approved by the manager.

Also good — more detail helps with ambiguous cases:

An employee submits a request for annual leave or special leave.
The request includes the desired dates and a reason.
It is forwarded to the responsible manager for approval
and triggers a notification to HR once a decision is made.

The language of the description doesn't need to match the language of the user — the model resolves that automatically.

Event Descriptions

Each event on the initial task is also visible to the agent. Event descriptions are not just labels — they are instructions that tell the agent when to use which event.

The agent uses these descriptions to decide between two scenarios:

Draft / save — use this event when required form fields are still missing. The workitem is persisted in an intermediate state and the agent asks the user for the remaining data.
Submit / approval — use this event only when all required form fields are filled. The workitem is forwarded for processing.

Write event descriptions accordingly:

Draft event:

Save as draft. Use this event when required fields are still missing.
The process is saved but not yet submitted for approval.

Submit event:

Submit for approval. Use this event only when ALL required fields are filled.
The request will be forwarded to the manager for review.

A description like "Initial Submit used by AI Agent only" or no description at all gives the agent no signal to work with. Always write the event description as a rule that the agent can follow.

What Happens Without Descriptions

If descriptions are missing or too generic, the agent's behaviour becomes unpredictable:

It may ask the user clarifying questions instead of acting directly
It may pick the wrong process when multiple processes have similar names
It may fail to match at all and return a text response explaining that no suitable process was found
It may pick the wrong event (draft vs. submit) because the event descriptions provide no guidance

None of these are failures of the agent — they are failures of the model documentation. The agent can only be as good as the information it is given.

Forms

If the initial task has an Imixs Form definition attached, the agent automatically reads all field definitions and includes them in the skill headers. This tells the agent which data fields it needs to collect from the user.

The agent extracts:

Field name (name) — used as the item key when writing data to the workitem
Field type (type) — tells the agent how to format the value (e.g. html5date → ISO date format)
Label (label) — the human-readable field name shown to the user
Required (required) — whether the field must be filled before the agent can submit

A minimal form definition looks like this:

<imixs-form>
  <imixs-form-section columns="2" label="Vacation Data">
    <item name="vacation.date" type="html5date" label="From:" required="true" />
    <item name="vacation.due"  type="html5date" label="To:"   required="true" />
  </imixs-form-section>
  <imixs-form-section columns="1" label="">
    <item name="employee.department"  type="text"     label="Department"   required="true" />
    <item name="vacation.description" type="textarea" label="Description"  required="true" />
  </imixs-form-section>
</imixs-form>

Layout information (columns, sections) is ignored by the agent — only the field metadata is used. The agent will extract values it already knows from the conversation and ask only for fields that are marked as required but not yet known.

Summary: Modelling Checklist

Before deploying a BPMN model that the AI Agent should work with, verify the following:

[ ] The Model Documentation describes the domain covered by the model
[ ] The Process Documentation is filled in with a business-level summary for each process
[ ] The Initial Task Description clearly states what the process is, who starts it, and what it achieves
[ ] All Event Descriptions on the initial task clearly state when the agent should use that event
[ ] The draft event description instructs the agent to use it when required fields are missing
[ ] The submit event description instructs the agent to use it only when all required fields are filled
[ ] A Form Definition is attached to the initial task if the process requires structured data input
[ ] All form fields that must be filled before submission are marked as required="true"
[ ] All descriptions are written in full sentences, not labels or identifiers
[ ] Descriptions are consistent across all processes in a model to avoid ambiguity