AI Agent execution model

Understand how the AI Agent connector runs, including prompts, tool descriptions, the agent loop, agent context, and response handling.

System prompt, user prompt, and tool descriptions

Reliable agent behavior depends on three inputs working together:

• System prompt: Defines the agent's role, boundaries, priorities, and success criteria.
• User prompt: Carries the current request and immediate context.
• Tool/task descriptions: Define which actions are available in the ad-hoc sub-process and how each should be used.

At runtime, the connector passes this combined context to the LLM. The model then selects which tools to call (if any), along with parameters.

How task descriptions are used for tools

When using an ad-hoc sub-process, each activity can be exposed as a tool. For best results, document each tool with:

• A clear task name that describes intent.
• A behavior-oriented description that includes when to use it, when not to use it, and the expected outcome.

This makes tool selection more predictable and reduces repeated or incorrect calls.

Execution responsibility split

The decision and execution loop is shared between the LLM and Camunda:

• LLM decides: Which tool to call next, in what order, and with which parameters.
• Camunda orchestrates: Executes the selected BPMN activity, stores variables, applies retries and incident handling, and routes human tasks and events.

This means tools can be called in different orders, repeated, run in parallel, or skipped entirely, while execution remains constrained by the modeled process boundaries.

tip

For a broader overview of how execution works in an AI agent, see AI agents. For architectural guidance, see Design and architecture.

Agent loop

This connector is typically used in an agent loop, with the connector implementation repeatedly being executed based on tool call results until it is able to reach its goal. Each pass through the loop is a loop iteration.

For example, the following diagram shows an agent loop modeled with the AI Agent Task implementation type.

• The process loops back to the AI Agent connector task from the ad-hoc sub-process until the agent decides no further tool calls are needed.
• With the AI Agent Sub-process implementation type, the agent loop is handled internally and so is not explicitly modeled in the BPMN diagram.

1. A request is made to the AI agent connector task, and the LLM determines what action to take.
2. If the AI agent decides that further action is needed, the process enters the ad-hoc sub-process and calls any tools deemed necessary to satisfactorily resolve the request.
3. The process loops back and re-enters the AI agent connector task, where the LLM decides (with contextual memory) if more action is needed before the process can continue. The process repeats this loop iteration until the AI agent decides it is complete, and passes the AI agent response to the next step in the process.

Agent loop use cases

Typical agent loop use cases for this connector include the following:

Use case	Description
Tool calling	In combination with an ad-hoc sub-process, the AI Agent connector will resolve available tools and their input parameters, and pass these tool definitions to the LLM. The LLM generates a response, that might include tool calls (a request to call a tool paired with the input parameters). If tool calls are requested, the tools can be executed by activating the respective activities within the ad-hoc sub-process. With the AI Agent Sub-process implementation, activating the activities will be implicitely handled by the agent implementation. With the AI Agent Task implementation, it is necessary to model the process to pass these tool calls to the ad-hoc sub-process and to return the tool call results to the AI Agent task.
Response interaction	After returning a response (and without calling any tools), model the process to act upon the response. For example, present the response to a user who can then ask follow-up questions back to the AI Agent connector as a human-in-the-loop (HITL) follow-up.

As the agent preserves the context of the conversation, follow-up questions/tasks and handling of tool call results can relate to the previous interaction with the LLM, allowing the LLM to provide more relevant responses.

Response follow-up

Separately from the agent loop's own tool calling, the AI Agent connector's response can also be reviewed before the process continues: the process routes the agent's response to a task, such as a user task or another LLM acting as a judge, and can be modeled to loop back and re-enter the agent with a follow-up request. When that reviewing task is a person, this is an example of human-in-the-loop (HITL). This pattern is distinct from the agent loop itself, which is the LLM's internal tool-calling cycle rather than an external re-invocation of the process.

For worked examples, see the AI Agent Sub-process example and the AI Agent Task example.

Agent context

An important concept to understand is the use of the Agent context process variable to store information required for allowing re-entry to the AI Agent connector task with the same context as before.

Depending on which implementation type is used, the Agent context must be configured differently in the model:

• AI Agent Sub-process: The agent context is kept within the sub-process scope. This means you only need to configure the agent context when the agent should pick up an existing conversation, for example to model a human-in-the-loop (HITL) follow-up as in the quickstart example. In this case, you must align the configured agent context variable with the used result variable/expression so that the context update is correctly passed to the next execution of the AI Agent connector task.

• AI Agent Task: You must align the agent context input variable and the response variable/expression so the context update is correctly passed to the next execution of the AI Agent connector task.

Response format

The AI Agent connector can be configured to instruct the LLM to respond in a structured JSON format, and to parse the JSON structure into a FEEL context accordingly. This allows the LLM to return structured data that can be easily processed in the BPMN process.

Example conversation

The following sequence diagram shows a high-level example conversation with the AI Agent connector, including both an agent loop and a human-in-the-loop (HITL) follow-up.

The conversational awareness provided by the agent context allows use cases such as the user only responding with Yes, please proceed, with the agent understanding what it should do next.

With the AI Agent Task implementation, the process models the routing between the agent and the ad-hoc sub-process. With the AI Agent Sub-process implementation, the agent handles it internally.