Agentic Ad Hoc Sub-Process
In an ad hoc sub-process, the process model does not say which activities to run or in what order: something outside the process decides that. In an agentic ad hoc sub-process, an AI agent decides. The activities inside the sub-process are its tools. The agent reads the task, starts the activities it needs, reads their results and decides what to do next, until the work is done.
The agent is the AI Agent Connector, the same connector as on the AI Agent service task, except that it sits on the ad hoc sub-process instead of on a task.
Beta
In CIB seven 3.0.0, the agentic ad hoc sub-process is a beta feature. Do not use it in production. For what it cannot do yet, see Limitations and Deployment Checks.
When to Use It
- Agentic ad hoc sub-process: the agent’s actions should be BPMN activities that you see in Cockpit; some of them wait for a person, a message or a timer; or you want to reuse existing tasks and call activities as tools.
- AI Agent service task: the model answers in one go, its tools are quick Java or MCP calls, and nothing waits.
- Plain ad hoc sub-process: a person or a rule decides which activities run.
Every decision of the agent is a paid model call, and the order of the activities is not fixed in the model.
How it differs from the AI Agent service task:
| AI Agent service task | Agentic ad hoc sub-process | |
|---|---|---|
| Tools | Java @Tool classes and MCP servers |
activities inside the sub-process: service and user tasks, call activities, sub-processes; MCP servers as well |
| Can a tool wait for a person, a message or a timer | no | yes |
| If a model call fails | the task fails as a whole, with all its model calls | only that model call is retried; after the last retry, the sub-process shows an incident |
| When it ends | when the model has answered | when the agent says it is done (completeScope) or answers, and nothing inside is running |
Concepts
| Term | Meaning |
|---|---|
| Tool | an activity inside the sub-process without an incoming sequence flow; an activity behind a sequence flow runs as part of the tool before it |
completeScope |
a tool the agent always has, besides the activities you draw: the agent calls it when the work is done. You do not model it |
| Turn | one round of the agent: it starts when the process enters the sub-process, and again when a tool ends while the agent waits; it ends when the agent answers with text |
| Model call | one request to the model. After every answer that starts tools, the agent is asked again, in the same turn, so a turn makes several model calls |
| Step | one model call together with the activities its answer starts; the engine runs each step as a job of its own (type agentic-ad-hoc-turn) |
| State | what the agent gets at the start of every model call: the activities that have finished, with their results, what is still running or blocked, the turn counter and the context variables; so it goes on where it left off |
| Outcome | how the last turn ended, in the variable agentOutput_outcome, see Ending and Limits |
For example: in turn 1 the agent starts Check logs, then Order spare part and Call customer, with a model call
for each answer, and then answers with text. Call customer waits for a person, so the turn ends with the outcome
waiting. When the person completes the task, turn 2 begins: the agent calls completeScope and gives its final
answer.
Quick Start
What you need:
- The AI Agent Connector enabled. The agentic sub-process is switched on and off together with it, see Installation & Enablement. If the connector is off, the sub-process is deployed as a plain ad hoc sub-process and waits: nobody starts its activities.
- A model with an OpenAI-compatible API, trained for agentic workflows, see Recommended Models.
In the template, Base URL and Model work as on the AI Agent service task, see
Configuring the Agent.
Set the key on the server with the environment variable
OPENAI_API_KEYand leave the API key field empty: a key in a process variable or in the model is stored in the database and in the history. - A job executor that runs the jobs. In Run it is on.
Model it in the CIB seven Modeler:
- Add an expanded sub-process and choose Change element → Ad-hoc sub-process.
- In the properties panel, choose the template CIB seven AI Agent (ad hoc sub process).
- Fill in Message: this is the agent’s task, for example
Resolve incident ${incidentId}: ${description}. - Draw the activities the agent may start. Give each a readable id, for example
checkLogs: the id is the tool’s name. In its Documentation, say what the activity does and when to use it.
Run it:
- Deploy the model (the rocket button at the bottom of the Modeler).
- In Tasklist, choose Start process and the process. The example’s start form asks for the incident id and what the customer reports.
- In Cockpit, open the process instance: Call customer has a token and
agentOutput_outcomeiswaiting. - In Tasklist, open Call customer in the filter All tasks, assign it to yourself, fill in what was agreed with
the customer and complete it. The agent sees the result, calls
completeScopeand the process ends:agentOutputholds the agent’s summary andagentOutput_outcomeiscompleted.
The example on this page is a support desk. The agent has three tools: look at the logs, order a spare part and call the customer.
The whole model is the file incident-agent.bpmn: save it and open it in the Modeler. Below are its parts, one by one. The service tasks compute their result with an expression, so that the model deploys as it is; in a real process, a connector, an external task or a Java delegate takes their place.
1. The start event asks for the two values that the agent’s task reads.
<bpmn:startEvent id="start" name="Incident reported">
<bpmn:extensionElements>
<camunda:formData>
<camunda:formField id="incidentId" type="string"
label="Incident id" />
<camunda:formField id="description" type="string"
label="What the customer reports" />
</camunda:formData>
</bpmn:extensionElements>
<bpmn:outgoing>toAgent</bpmn:outgoing>
</bpmn:startEvent>
<bpmn:sequenceFlow id="toAgent"
sourceRef="start" targetRef="handleIncident" />
2. The sub-process and its agent. The template writes these values; in the Modeler they are its fields.
<bpmn:adHocSubProcess id="handleIncident"
name="Handle incident"
camunda:modelerTemplate="org.cibseven.connect.ai.agent.AdHocSubProcess"
camunda:modelerTemplateVersion="1">
<bpmn:extensionElements>
<camunda:connector>
<camunda:connectorId>cibseven-ai-agent</camunda:connectorId>
<camunda:inputOutput>
<!-- the agent's name in the chat log and Agent Chat -->
<camunda:inputParameter name="agentName">Incident agent</camunda:inputParameter>
<!-- the task; ${...} reads the start form's values -->
<camunda:inputParameter name="message">Resolve incident ${incidentId}: ${description}</camunda:inputParameter>
<!-- your rules, after the built-in ones (append) -->
<camunda:inputParameter name="instruction">Check the logs first. Order a spare part only if the logs show a hardware fault. Tell the customer what was done.</camunda:inputParameter>
<camunda:inputParameter name="instructionMode">append</camunda:inputParameter>
<!-- the answer, and how the last turn ended -->
<camunda:outputParameter name="agentOutput">${output}</camunda:outputParameter>
<camunda:outputParameter name="agentOutput_outcome">${outcome}</camunda:outputParameter>
</camunda:inputOutput>
</camunda:connector>
</bpmn:extensionElements>
<bpmn:incoming>toAgent</bpmn:incoming>
<bpmn:outgoing>toEnd</bpmn:outgoing>
<!-- the tools of part 3 go here -->
</bpmn:adHocSubProcess>
<bpmn:sequenceFlow id="toEnd"
sourceRef="handleIncident" targetRef="end" />
<bpmn:endEvent id="end" name="Incident handled">
<bpmn:incoming>toEnd</bpmn:incoming>
</bpmn:endEvent>
3. The tools: the activities inside the sub-process. The id of each is the tool’s name, and its documentation tells the agent what the tool does.
<!-- finishes at once; its result goes back to the agent -->
<bpmn:serviceTask id="checkLogs" name="Check logs"
camunda:expression="${'Node 3: disk read errors since 02:10'}"
camunda:resultVariable="logFindings">
<bpmn:documentation>Reads the service logs for this incident and returns what they show.</bpmn:documentation>
</bpmn:serviceTask>
<!-- takes a value from the agent, see Tools below -->
<bpmn:serviceTask id="orderSparePart" name="Order spare part"
camunda:expression="${'Ordered: '.concat(part)}"
camunda:resultVariable="sparePartOrder">
<bpmn:documentation>Orders a replacement part and returns the order.</bpmn:documentation>
<bpmn:extensionElements>
<camunda:inputOutput>
<camunda:inputParameter name="part">${toolParameter(toolCall.part, 'The part to order, for example disk for node 3', 'string')}</camunda:inputParameter>
</camunda:inputOutput>
</bpmn:extensionElements>
</bpmn:serviceTask>
<!-- waits for a person; the form field is the result -->
<bpmn:userTask id="callCustomer" name="Call customer">
<bpmn:documentation>A person calls the customer, explains what was done and records what was agreed.</bpmn:documentation>
<bpmn:extensionElements>
<camunda:formData>
<camunda:formField id="agreement" type="string"
label="What was agreed with the customer" />
</camunda:formData>
</bpmn:extensionElements>
</bpmn:userTask>
The example has no gateway after the sub-process, to stay short. In your process, check how the agent ended, see Ending and Limits.
Tools
The name and the description of an activity are what the agent knows about the tool. Write them for the model:
what the tool does and when to call it. The description is taken from the activity’s Documentation field. The
tool name is the activity id, so the id may contain only the letters A–Z and a–z, digits, _ and -, at
most 64 characters.
A value from the agent reaches the tool through the toolParameter function in an input parameter of the
activity. In the Modeler: Inputs → +, Local variable name part, Assignment type String or
expression, and as Value:
${toolParameter(toolCall.part,
'The part to order, for example disk for node 3',
'string')}
toolCall.part is the value the agent gives for the parameter part; that name is what the model sees. The second
argument is the parameter’s description for the model, the third is the type: string, integer, number or
boolean. The parameter is required; with a ? after the type, for example 'integer?', the agent may leave it out.
The input parameter, here also part, is the local variable your task reads.
What a tool returns to the agent is decided by the process model: the result variable of a service task, the
output parameters (output mapping) or the form fields of a user task. To choose the variables yourself, set the
camunda:property adHocResultVariables on the activity, for example logFindings, severity. With the result, the agent gets
the tool’s status: finished, waiting (for example for a person), or how else it ended, for example interrupted by a
boundary event or cancelled from outside.
The agent may start a tool more than once, for example for a second order. Tools that finish at once run one
after another; tools that wait run side by side. An activity with the camunda:property adHocBlockedWhileOthersRun = true
can only be started while nothing else in the sub-process runs, for example a release that waits for all checks.
Other tools. MCP servers in the connector’s input parameter mcpServers (the template has no field for it) are
available to the agent as well, see Tools; an MCP tool does not
keep the sub-process waiting. An AI Agent service task inside the sub-process can be a tool, too: it keeps its own
conversation, also as several or multi-instance tasks. A nested ad hoc sub-process can be a tool; the agent gets its
results when it ends.
The agent can ask a person only through a tool that waits: a user task, or a sub-process that sends the question and waits for the answer. A text answer ends the turn, so nobody receives a question in it.
The instruction does not enforce limits. Check the amount the agent may pay out, or an action it must not take, in the system behind the tool, not only in the text of the instruction.
Treat text from outside as data. The agent reads every tool result and every value in Message as part of its conversation. Text from outside, for example a customer’s e-mail, can contain instructions that steer the agent (prompt injection). Write the task in Message, and pass such text in Context variables: the agent then receives it as data, not as part of the task. Give the agent only tools whose effects are acceptable whatever it decides.
Keep the facts the agent must not lose as process data. The agent’s memory holds only the last messages
(Chat memory max messages, 20 by default), so in a long conversation it forgets what a person said early on: it
asks again, or goes on with a value it made up. Let a tool note such facts: a task that writes them into process
variables and takes them as optional parameters, for example
${toolParameter(toolCall.policeReport, 'The police report number', 'string?')}. Name these variables in
Context variables and, because they are not set when the sub-process starts, also in Optional context
variables. The agent then gets their current values with every model call, whatever its memory still holds, and
is told which of them are not set yet. In the instruction, tell the agent to note each fact as soon as the person
gives or corrects it, and to ask only for what is not noted yet.
Let a tool that changes data in another system run on its own. Set Asynchronous continuations > Before on
it (camunda:asyncBefore). Then, if the other system fails, only this tool is retried. Without it, an error undoes
the agent’s whole step and the model is asked again: it may make the change a second time, or a different change.
The other system should also treat a repeated request as already done.
Inside a tool, some BPMN behaves differently: catch a BPMN error on the tool itself, put a fork and its join into an embedded sub-process, return strings or numbers rather than dates or JSON, and do not use event sub-processes. See Limitations and Deployment Checks.
Configuration
Only Message is required. The other fields have default values.
| Field | Group | Default | What it does |
|---|---|---|---|
| Message | Input | — | The agent’s task. It is evaluated again before every model call, so it shows the current process data. |
| Instruction | Input | empty | Rules on top of the task, for example a company policy. |
| Instruction mode | Input | Append to default, set by the template | Append to default or Prepend to default: your instruction after or before the built-in one. Replace default: only yours, without the built-in rules that the agent asks a person only through a tool that waits, does not start an activity again for work that is already done, and ends the work with completeScope; say them in your instruction. Without the instructionMode parameter, as in XML written by hand, your instruction replaces the built-in one. |
| Context variables | Input | empty | Process variables that the agent sees as data, apart from the task: names separated by commas, up to 4000 characters each and about 20000 in all. Each one is required: if it is not set, is null or does not fit whole, the step fails, and after the job’s retries the sub-process gets an incident that names it. |
| Optional context variables | Input | empty | Those of the context variables that may be missing. One that is not set is reported to the agent as missing; a long one is cut, and one past the total limit is left out and named. If empty, every context variable is required. |
| Follow-up on re-entry | Input | empty | Only with Continue across entries: sent instead of Message in the first turn after the sub-process is entered again, see Feedback Loops. |
| Max model calls per turn | Limits | 25 | How many model calls a turn may make; the agent can also start this many activities with one answer. At the limit the turn ends: if nothing inside is running, the sub-process ends with the outcome callLimit; otherwise the agent gets a new turn when the activity ends. |
| Max turns | Limits | 10 | How many turns the agent has per entry into the sub-process. |
| Max turns total | Limits | empty | Only with Continue across entries: the turns of all entries together. |
| On limit | Limits | Continue | See Ending and Limits. |
| Conversation | Memory | Start new on each entry | See Feedback Loops. |
| Chat memory max messages | Memory | 20 | How many messages the agent keeps, about the last six model calls. Earlier tool results and answers are dropped, so in a long run the agent no longer sees them; keep what it must not lose as process data, see Tools. A larger window sends more with every call. With Continue across entries, leave it empty or set it to at least 2 × Max model calls per turn + 3 (53 with the defaults). |
| Output variable for agent response | — | agentOutput |
The agent’s answer. It is written after every turn; the last answer stays. |
| Output variable for the turn’s outcome | — | agentOutput_outcome |
How the last turn ended; use it in a gateway after the sub-process. |
| Output variable for AI-output marker | — | agentOutput_aiMeta |
Marks the answer as written by AI, for a form or a gateway that must tell it from what a person wrote. |
The other fields of the template, such as Base URL, Model and the RAG fields, are the same as on the AI Agent service task, see Configuring the Agent. Leave the API key field empty.
In XML, the template writes the limits, On limit and Conversation as properties of the sub-process:
cibseven.agentic.maxModelCalls, cibseven.agentic.maxTurns, cibseven.agentic.maxTurnsTotal,
cibseven.agentic.onLimit and cibseven.agentic.conversation. The other fields are input and output parameters of
the cibseven-ai-agent connector on the sub-process.
Recommended Models
The model you choose decides whether the agentic sub-process works. The agent decides from the model’s answers which activity to start next, when to wait and when the work is done. That needs a model trained for agentic workflows: for calling tools, waiting for their results and keeping track of what is still running. A model that answers a single question well can still fail here: it may start a task for a person twice, so the sub-process never ends, or call a tool with a made-up value.
The instruction matters as much as the model. Say in it, in plain words, what the agent must do, when it asks a person and when the work is done. A clear instruction is what makes the agentic sub-process behave as your process expects.
Choose a model trained for agentic workflows with tool calling. The models below worked with the agentic sub-process without such mistakes when this page was written. Models change quickly: check your provider’s current recommendations for agentic work and tool calling before you choose.
| Provider | Smallest suitable model, as an example |
|---|---|
| OpenAI | gpt-6-luna or a larger GPT model |
| Anthropic | Claude Haiku 5.5 or a larger Claude model |
Left empty, Model uses the server’s default model, gpt-6-luna; an installation can change it, see
Installation & Enablement.
Ending and Limits
agentOutput_outcome |
Meaning |
|---|---|
waiting |
the agent answered while a tool is still running; the sub-process waits (only while the sub-process runs) |
completed |
the agent called completeScope: it says the work is done. The sub-process ends when the turn is over. completeScope is refused while an activity the agent started is still running |
ended |
the agent answered with text, and nothing inside is running; it did not call completeScope, so it did not say the work is done |
turnLimit, totalTurnLimit, callLimit |
a limit was reached |
After the sub-process, treat completed as done. With On limit = Continue, the sub-process also ends when a
limit is reached and nothing inside is running, and the process goes on as if the work were done. So put an
exclusive gateway after the sub-process that sends ended, turnLimit, totalTurnLimit and callLimit to a
person, for example to a user task that shows agentOutput.
With On limit = Throw a BPMN error, the sub-process throws a BPMN error whose code is the limit’s name instead.
Deployment then requires a boundary error event on the sub-process for each limit it can reach: turnLimit and
callLimit always, totalTurnLimit with Continue across entries and Max turns total. The simplest way is one
boundary error event without an error reference, which catches every limit. In the Modeler: set On limit to
Throw a BPMN error, attach a boundary error event to the sub-process, leave its error empty and set its Code
variable to limitCode, which then tells which limit was reached. This boundary event catches only the limits: a
BPMN error from a tool needs a boundary error event on the tool itself.
<bpmn:adHocSubProcess id="handleIncident" name="Handle incident">
<bpmn:extensionElements>
<camunda:properties>
<camunda:property name="cibseven.agentic.onLimit"
value="error" />
</camunda:properties>
<!-- the connector, as in part 2 of the example above -->
</bpmn:extensionElements>
<!-- the tools -->
</bpmn:adHocSubProcess>
<!-- catches every limit; limitCode tells which one -->
<bpmn:boundaryEvent id="limitReached"
attachedToRef="handleIncident">
<bpmn:errorEventDefinition
camunda:errorCodeVariable="limitCode" />
</bpmn:boundaryEvent>
A tool that never finishes holds the agent. Put a boundary timer event on the sub-process.
Feedback Loops
With Conversation = Continue across entries, the agent remembers earlier entries into the sub-process. For example: after the sub-process, a Review user task and a gateway send the result back to the sub-process when the reviewer rejects it, and the agent continues from what it did before.
- Follow-up on re-entry is sent instead of Message in the first turn after the sub-process is entered again,
for example
The reviewer said: ${feedback}. - Max turns total limits the turns across all entries.
- Chat memory max messages must be at least 2 × Max model calls per turn + 3; a smaller number is rejected at deployment. Left empty, it is set high enough, to at least 53.
- It is not available on a parallel multi-instance sub-process.
- While the conversation is kept, the process instance cannot be migrated: until the scope around the sub-process ends, or, for a sub-process directly in the process, until the instance ends.
Operate
Retries. If a model call fails, the job is retried, and after the last retry an incident appears on the sub-process. With the default retry cycle this takes a little over a minute, so when the model provider is unavailable, every running agent ends up in an incident; retry the incidents once the provider answers again. Retrying the incident costs one model call and repeats the tools that this model call started and that finish at once, such as service tasks.
The model can also repeat an activity. It may start an activity again that is still running or has just finished, for example a second task for a person. The built-in instruction tells the agent not to start an activity again for work that is already done; with Instruction mode Replace default, say it in your own instruction. A model made for agentic work follows this more reliably, see Recommended Models.
The agent’s variables. In Cockpit’s Variables tab, the variables on the sub-process whose names begin with
adHocAgent are the agent’s state and the results of its tools, one variable per result, and toolCall holds the
values of the current call. The variables whose names begin with cibseven-connect-ai-agent are its conversation, on
the sub-process, and its chat log, on the process instance, one variable per model call. They belong to the agent:
do not change them.
Audit. What was sent to the agent and what it answered is stored in the process’s chat log (see Audit Trail). In the Enterprise Edition, the Agent Chat tab in Cockpit shows it: the agent appears as one entry under the id of the sub-process, with every model call of every turn, what the agent was told, the tools it called with their results, and its answers. Each request starts with the state block that the engine adds: what finished since the agent’s last call, what still runs, and the turn.
The chat log is the same as for the AI Agent service task, with the same settings: Persist chat-log audit
variable (persistChatLog), cibseven.connect.ai-agent.chatLogVariable.enabled and
cibseven.connect.ai-agent.redactContent. What is different for the agent:
- One variable per model call. Each step of a turn is a call of its own, with its own
runId. The agent’s chat log is the variablescibseven-connect-ai-agent_<sub-process id>~<number>on the process instance, numbered across all turns. A tool’s result is recorded in the next request to the model, as a tool result and in the state block. - Whose action it is. The job executor runs the steps, without a user. Each call records the user who
started the process instance (
userIdSource: "startUser"), oruserId: nullwithuserIdSource: "missing"when nobody did. Who completed a task the agent started is not in the chat log; the engine’s user operation log keeps it at history levelfull. - Process data. The values of the Context variables are recorded as a length and a SHA-256 hash, a
fingerprint from which the text cannot be read back, also without
redactContent; the values themselves are in the variables and their history. - End at a limit. The chat log ends with the last answer of the model. A limit that stops the agent leaves
no entry: the outcome (
agentOutput_outcome, for exampleturnLimit) andagentOutput_aiMeta, which then holds onlyaiGenerated: falseandgeneratedAt, show it. - Failed model calls. A failed call is undone together with its chat-log entry; the job is retried, and after
the last attempt the sub-process gets an incident. Failed calls show in the incident, in the job log at history
level
full, and asLLM ERRORlines in the application log. - Multi-instance. The parallel instances of one agentic sub-process write into one chat log under one id;
their calls differ only by
executionId.
How long the chat log is kept. While the process instance runs, the chat log is process variables. After it
ends, it exists only in the history, at history level audit or full, until history cleanup removes it after
the process’s history time to live (History cleanup → Time to live in the Modeler): in the example on this
page P30D, 30 days. At level activity or
none nothing of it is left after the end.
Limitations and Deployment Checks
- Only models with an OpenAI-compatible API. That includes OpenAI, Azure OpenAI, OpenRouter, Ollama and Anthropic’s Claude models through Anthropic’s OpenAI-compatible endpoint, see Configuring the Agent. Other providers work through a gateway with such an API. The key is an API key of the provider’s developer platform; a chat subscription such as ChatGPT, Claude.ai or Claude Code is not one.
- Text only. Documents and images do not reach the model. Dates, JSON values and files among a tool’s results reach the agent only as a placeholder with their type; return a string or a number instead.
- The agent’s steps run without a user. Permissions to start tools are not checked, and the user operation log records no entry for what the agent starts. Give the agent only tools that may run on behalf of the process.
- Retrying a step repeats calls. Make calls to other systems safe to repeat, and let a tool that changes data there run on its own, see Tools.
- A BPMN error from a tool that nothing catches is reported to the agent as a successful completion. A boundary error event on the sub-process does not help: the step fails and ends in an incident. Catch the error with a boundary error event on the tool itself; one without an error reference catches every error, and the agent learns its code.
- A parallel gateway in a tool’s flow can stop the sub-process. Put the fork and the join inside a nested sub-process.
- Event sub-processes and non-interrupting boundary events inside an agentic sub-process are not supported.
- An instance with a waiting agent cannot be migrated. Migrate after the sub-process has ended.
- Cancelling the only task the agent waits for ends the whole process instance. If you cancel it in Cockpit or
by a process instance modification, the engine ends the sub-process and the process instance, and nobody is told.
This will be fixed in a later release.
Give such a task a boundary timer event; to end it early, execute the timer’s job (REST:
POST /job/{id}/execute). The agent is told that the task was interrupted and goes on. To take the work away from the agent, cancel the sub-process and start the activity after it in the same modification. - A final answer longer than 4000 characters (2000 on Oracle) is stored as a serialized Java object.
Expressions such as
${agentOutput}still read it as text, but Cockpit shows it as an unreadableObjectvalue. Ask the agent for a short answer in the instruction.
Deployment rejects the sub-process, and the error message names the element and the reason, if:
- it has the template but not the connector (this happens after copying): apply the template again,
- Message is empty,
- it has a completion condition or the connector has
toolClasses, - no activity inside can be started directly,
- the agent’s input parameters are on the sub-process instead of on the connector.
What’s Next
- The plain ad hoc sub-process: guide and BPMN reference.
- Providers, models and keys: Configuring the Agent.
- Data and security: Security & Data Handling.