Modelling BPMN AI Agents

How the Agent Understands Your Model

Before the first LLM call, the BPMNSkillController assembles a structured plain-text overview of all accessible workflow processes and injects it into the agent's system prompt. The LLM then uses this overview to match the user's natural-language input against the available processes — across languages, phrasings and levels of abstraction.

For example, a user typing “Ich brauche Urlaub” will reliably trigger a process whose initial task is described as “A new vacation request has been submitted by an employee” — because a modern LLM understands the semantic equivalence even across language boundaries.

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

The Three Description Levels

BPMN models in Imixs-Office-Workflow carry documentation at three distinct levels, each serving a different purpose for the agent.

The agent reads all three levels and combines them into a layered understanding of your model. Think of it as a funnel: the Model Documentation sets the domain context, the Process Documentation narrows it to a specific business process, and the Initial Task Description anchors it to the concrete starting situation.

Model Documentation

The Model Documentation describes the overall scope and domain of the .bpmn file. The agent uses this to disambiguate between processes from different models when a user's request could match more than one.

Write it as 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

The Process Documentation sits at the Pool or Process element level and describes the specific process in business terms — not technical steps. The agent uses this to understand the purpose and scope of a process before looking at its individual tasks.

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 Initial Task Description is the most specific layer. It describes what is happening at the moment the process is initiated — who triggers it, what information is involved, and what happens next.

It should give the agent three pieces of information:

• What the process is about
• Who typically initiates it
• What happens as a result

A description like "Initial task" or "Start" gives the agent nothing to work with. A description like the one below gives it everything it needs:

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 does not need to match the language of the user. The LLM resolves this 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.

Form Field Definitions

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.

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.

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