Clarify AI Agent Sub-process event handling and “Interrupt tool calls” semantics

[mathieu-stennier]

Clarify AI Agent Sub-process event handling and “Interrupt tool calls” semantics

Affected documentation

• AI Agent Sub-process connector – Event handling section
  https://docs.camunda.io/docs/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-subprocess/#configuration-event-handling

---

Background

The current Event handling section for the AI Agent Sub-process describes two options:

• Wait for tool call results (default)
• Interrupt tool calls
  and illustrates them with the “Tool A / Tool B / Event message” example.
  At the same time:
• In Modeler, interrupting event subprocess start events are disallowed on ad‑hoc sub‑processes (used by the AI Agent Sub-process). This leads users to model non‑interrupting event subprocesses and then configure the connector with Event handling behavior = “Interrupt tool calls”. This is not clearly explained in the docs and conflicts with the usual BPMN mental model of interrupting event subprocesses.
• Internal discussion clarified the intended mental model: when you model an ad-hoc sub-process controlled by an AI agent, you effectively hand over control of which elements are activated and when the sub-process is completed to the agent. Reacting to events via an event subprocess is tricky, and the current limitations (e.g., no interrupting event subprocesses inside the ad-hoc sub-process) are there to reduce complexity for both implementation and users.
  Multiple people (including customers and internal colleagues) reported confusion about:
• What exactly “Interrupt tool calls” does.
• How it relates to BPMN interrupting vs. non-interrupting event subprocesses.
• Which elements are supposed to be cancelled (tool jobs, user tasks, entire ad-hoc sub-process, etc.).

---

Problem / Documentation gaps

1. Modeling constraints are not explained

• The docs don’t state that interrupting event subprocesses are not allowed on the ad-hoc sub-process used by the AI Agent Sub-process; only non-interrupting event subprocesses can be modeled there.
• As a result, readers assume BPMN’s usual semantics (interrupting event subprocess cancels the parent scope) and expect that choosing Interrupt tool calls will behave similarly, even though the underlying BPMN construct is non-interrupting.

2. Ambiguous semantics of “Interrupt tool calls”

• The section currently says: “When an event is received while other tool calls are still in progress, the process will cancel the tool execution and directly return a list of messages to the LLM: …” followed by a synthetic “Tool A execution was cancelled” message.
• It does not clearly spell out:
• Which concrete runtime elements are cancelled (e.g., external tasks, connector jobs, “Wait for user” user tasks created by tools).
• Whether the ad-hoc sub-process scope itself is cancelled or stays active.
• That the event subprocess remains non‑interrupting from a BPMN perspective; “Interrupt tool calls” is an agent‑level behavior, not a change to BPMN interrupting vs. non‑interrupting semantics of the event subprocess start event.

3. Missing mental model and examples

• There is no short explanation of the “agent controls the ad-hoc sub-process” model and how event handling fits into this.
• The existing example focuses on tool messages to the LLM but not on:
• Token flow inside the ad-hoc sub-process.
• What happens to running user tasks.
• How users should think about non-interrupting vs. “interrupt tool calls” in combination.

---

Proposed documentation changes

1. Add a prominent note about modeling constraints

In the Event handling section, add an info / note / caution box that explicitly states:

• For AI Agent Sub-processes (implemented as ad-hoc sub-processes), interrupting event subprocess start events are not supported in Modeler. Only non‑interrupting event subprocesses can be modeled on the agent sub-process scope.
• The Event handling behavior field (“Wait for tool call results” / “Interrupt tool calls”) controls how the agent’s job worker reacts to an event, not the BPMN interrupting vs. non‑interrupting semantics of the event subprocess start event.
• As a result, even when using Interrupt tool calls, the event subprocess is still a non-interrupting BPMN construct; interruption is applied at the tool‑call level (by the agent), not by cancelling the parent ad-hoc sub-process in the engine.

2. Clarify semantics of each Event handling behavior

Expand the descriptions in _event-handling.md as follows:

Wait for tool call results

Keep the existing example, and add text such as:

• The agent waits until all tool calls that were requested in the current step (including any tools that create user tasks like “Wait for user”) have completed before handling the event.
• Only after all these tool calls complete does the job worker send a new request to the LLM, including:
• One message per completed tool.
• Then one message containing the event payload (for example, the timer/event subprocess handler output).

Interrupt tool calls

Keep the existing message sequence example, but clarify the behavior explicitly:

• When the configured event fires while one or more tool calls are still running, the agent:
• Cancels all still-running tool calls belonging to the current agent step (including user tasks representing “Wait for user” tools, once the bug is fixed).
• Synthesizes a “<Tool X> execution was cancelled” message for each cancelled tool and includes it in the LLM request, alongside the results of already‑completed tools and the event message.
• The surrounding ad-hoc sub-process scope remains active; the agent decides, based on the new LLM response, which elements to activate next or whether to complete the sub-process.
• Make clear that no BPMN interrupting event subprocess is involved; the interruption happens purely in the agent’s control flow (job worker), not by cancelling the BPMN parent scope.

3. Explain the relationship between BPMN and agent behavior

Add a short conceptual subsection, for example “How event subprocesses work with the AI Agent Sub-process”, that states:

• In standard BPMN, an interrupting event subprocess cancels its parent scope when triggered, while a non-interrupting one runs in parallel.
• For the AI Agent Sub-process (ad-hoc sub-process):
• Only non-interrupting event subprocesses are allowed on the agent scope (by design and enforced by Modeler).
• The Event handling behavior controls how the agent treats running tool calls when such a (non-interrupting) event subprocess is triggered:
  • Wait for tool call results: event handler runs only after tools complete.
  • Interrupt tool calls: running tools are cancelled and their cancellation is surfaced to the LLM, even though the event subprocess itself is still non‑interrupting from a BPMN point of view.
• Reiterate the mental model: by modeling an ad-hoc sub-process with an AI agent, you delegate control of the sub-process execution (which tasks/tools run and when it completes) to the agent; event subprocesses provide additional signals into that control loop, not low-level cancellation of the scope like a classic interrupting event subprocess.

[mathieu-stennier]

@afgambin could you collaborate with @maff on this?

[afgambin]

Slack thread for context: https://camunda.slack.com/archives/C08BHU6JQJG/p1768405611746009