Documentation
Built by Maven

AI Agents

Dynamixs.AI provides a powerful AI Agent platform that integrates seamlessly into your BPMN processing life cycle. An AI Agent is a BPMN participant that can perform work autonomously - in the same way as a human user. It reads documents, makes decisions, and acts on your business process, all driven by the same BPMN model you already use to describe human tasks.

This chapter explains how AI Agents work: when to use, where to place, and how to use Tool Calls to let the agent actually act on data. See How to Model BPMN AI Agents for how to describe your model so the agent understands it, and Working with Skills for how to give an agent domain-specific knowledge.

The Concept

An AI Agent is a BPMN participant that can perform work autonomously in the same way as a human user. The agent can

  • read documents
  • ask questions
  • search business objects
  • update workitems
  • complete tasks
  • create new processes

Just like a human employee, an AI Agent can participate in any BPMN workflow. You model it the same way you would model a human role - with tasks, events, forms and descriptions. The difference is who performs the work.

Modelling an agent means answering two questions:

  1. Do you need an agent at all, or is a single AI Adapter step the better fit?
  2. Where should the agent live - inside an existing task, or in a process of its own?

AI Adapter vs. AI Agent

Dynamixs.AI provides two different ways to integrate an LLM into a business process.

  • An AI Adapter (OpenAIAPIAdapter, ImixsAIAssistantAdapter, ConditionalAIAdapter) is a single request/response step bound to a task-event transition. The workflow asks the LLM one question - classify this document, draft this text, extract this value - and moves on. The control flow stays entirely in the BPMN model.

  • An AI Agent runs a loop. It calls tools, observes their results, and decides on its next step based on what it found - until the task is done or it needs a human. The control flow inside the task is determined at runtime, by the agent.

Which one to choose

The question is not how complex the task is, or how much intelligence it requires. It is this:

Do you know at modelling time how many steps the task will take?

If you do, it is a good idicator that a AI Agent may not be necessary. For example the classification, summarization and extraction of a business document are three determined task-event transitions. You gain persistence after every step, restartability after a failure, a clear record of which prompt produced which value, and the ability to change one step without touching the others. An agent would have no freedom to run here in an agent loop.

If you don't, an AI-Agent is the right choice. The number of steps depends on what the agent finds: a search returns no match and a different query has to be tried, an extracted value turns out to be inconsistent and has to be reconciled, a document references another document that must be looked up first. None of this can be modelled in advance, because the branching lives in the data, not in the process.

A useful test: describe the task as a sequence of steps on paper. If you can write the list down without knowing the content of the actual document, use AI Adapters. If the list reads “…and then, depending on what came back, either A or repeat with B”, use an Agent.

The two are not tiers

An AI Agent is not the more advanced form of an AI Adapter. A deterministic chain of adapter steps is not a workaround to be replaced once the platform matures - for tasks with a known structure it is the better design, and it will stay the better design.

Both are used side by side in real models. An incoming request might be classified, normalized and routed by three AI Adapter steps, and only then handed to an AI Agent for the one case that genuinely requires investigation.

Choosing the Right Architecture

Once you have decided that a task needs an agent, a second question follows: where should it live - inside your existing task, or in a process of its own? Both are valid - they answer different questions.

Embedded Agent

Use an embedded agent when the work needs several steps, but all of them operate on the current workitem:

  • extracting data from a document and reconciling it against existing records
  • searching for a related business object where the query may need to be refined before it matches
  • extracting values that reference another document which has to be looked up first
  • deciding a case where the decision depends on what earlier lookups returned

The agent runs, does its work on the current workitem, and the process continues - the same task, no detour. This is the right default whenever the agent's job is naturally part of the step a human would otherwise have done, and the number of steps depends on what it finds.

If the work is a single lookup, a single classification or a single extraction with no follow-up, you do not need an agent here - use an AI Adapter.

Dedicated Agent Workflow

Sometimes the work is bigger than one step. Think of it less as “calling the AI” and more as handing the case to a colleague who goes off, does the work, and comes back when finished.

Use a dedicated agent workflow pattern when the agent needs to

  • run for longer than a single processing step
  • ask clarifying questions along the way
  • create its own documents or intermediate results
  • work independently of the process that triggered it

A typical example: your Compliance workflow reaches a point where a case needs deeper research. Instead of blocking the compliance case itself, it starts a dedicated agent process - the agent works the case on its own, potentially over several exchanges, and once it concludes, the result flows back into the originating Compliance workflow. From the compliance officer's perspective, this looks exactly like handing a task to a colleague and getting an answer back later.

Human Collaboration

Neither of the two architectures is fully autonomous, and neither is meant to be. An agent - embedded or dedicated - doesn't always have everything it needs. When information is missing, the agent should not guess: it pauses and asks.

The workitem moves to a task where a person can answer, and once they do, the agent picks the conversation back up with full context of everything that happened before.

Model this the same way you would model a human handing a case back for clarification - with a form task and a clear description of what's being asked. From the agent's side, this is simply the difference between “I can act” and “I need to ask first.”

Which of these two the agent chooses is not a matter of tone or phrasing - it is a Tool Call. An agent that has finished its work signals this explicitly; an agent that is missing something simply doesn't, and the process routes the case to a human instead. This is what makes “the agent was unsure” a visible branch in your BPMN model rather than a sentence buried in a chat response. See Tool Calls for how this is wired up.

Tool Calls

An AI Agent cannot modify a business process directly. Every action it takes is executed through a Tool Call: the agent proposes an action, the platform executes it against the real business system, and the result is fed back so the agent can decide what to do next. This is what keeps the agent safe and predictable - it can only do what a tool explicitly allows it to do.

See Tool Calls for the full list of built-in tools (task_complete, find_workitem, link_workitem, update_workitem, find_skill / get_skill) and guidance on designing your own.

Examples

Embedded Agent - Fine Extraction & Contract Linking

A fine notice arrives for a leased vehicle. An embedded agent on the receiving task extracts the fine data with update_workitem, then searches for the matching leasing contract with link_workitem. If exactly one contract is found, it calls task_complete and the case moves on automatically. If none or several are found, it leaves a note for a manager instead. No separate process is needed - the whole thing happens inside the one task that received the document. The full prompt for this example is shown in How to Model BPMN AI Agents.

Dedicated Agent Workflow - Compliance Research

A Compliance workflow flags a case that needs deeper investigation - cross-checking multiple external records, gathering supporting documents, possibly asking a case worker a clarifying question along the way. Rather than blocking the compliance case itself, the task starts a dedicated agent process for this investigation. The agent works the case independently, potentially across several turns with a human, exactly as a colleague would. Once it reaches a conclusion, it calls task_complete, and the result is linked back to the originating Compliance case - which continues from where it left off, now with the investigation's outcome in hand.