Getting Started

This quickstart adds a working AI Agent service task to a process in a few minutes. It assumes you have a running CIB seven instance and an API key for an OpenAI-compatible LLM provider.

1. Make sure the connector is enabled

The AI Agent overlay is shipped with the run, run4, Tomcat, and WildFly distributions. Depending on the distribution and mode it may be on by default or require a flag/env var (for example, it is off by default in the run distribution’s --production mode). If the CIB seven - AI Agent template doesn’t appear in the Modeler, or the task fails with connector not found, see Installation & Enablement first.

You also need an LLM API key available to the process — typically referenced through a process variable (e.g. ${apiKey}) or, at the deployment level, the OPENAI_API_KEY environment variable.

2. Add an AI Agent service task

In the CIB seven Modeler:

  1. Add a Service Task to your process.
  2. In the Template panel, choose CIB seven - AI Agent. The task’s fields are now grouped into Input, Agent, Tools, Memory, and RAG.

(Applying the template sets camunda:modelerTemplate="org.cibseven.connect.ai.agent" and the hidden connectorId = cibseven-ai-agent.)

3. Fill in the minimum configuration

Only two fields are required: Agent name and Message. Everything else is optional and has a sensible default.

Field Group Example Notes
Agent name Input Summarizer Logical name of the agent.
Message Input Summarize: ${feedbackText} The user message; may reference process variables.
Instruction Input Summarize the core concern in 10 words or less. Optional system prompt. Empty → bundled default prompt.
API key Agent ${apiKey} Optional if OPENAI_API_KEY is set in the environment.
Model Agent (leave empty) Optional. Falls back to the deployment default model.

If you leave Model, Base URL, and API key empty, the connector uses the deployment’s default model, the OpenAI endpoint (https://api.openai.com/v1), and the OPENAI_API_KEY environment variable respectively. See Configuring the Agent for all fields and provider recipes.

4. Map the output

In the output section, set Output variable for agent response to a process variable name — for example summaryResult. This binds the agent’s text answer (${output}) to that variable so the next BPMN step can read it. Two more optional outputs are available:

  • AI-output marker (${outputAiMeta}) — a map flagging the value as AI-generated (see Audit Trail).
  • Memory ID (${memoryId}) — only relevant when chat memory is enabled (see Chat Memory).

5. Deploy and run

Deploy the process and start an instance (supplying feedbackText and apiKey as needed). When the token reaches the service task, the connector calls the LLM and writes the answer into summaryResult. Inspect it in Cockpit, in a following user task, or in a gateway condition.

A complete minimal model

A self-contained “hello agent” — start → AI Agent → end — using only the required fields:

<bpmn:serviceTask id="Task_Summarize" name="Summarize feedback"
    camunda:modelerTemplate="org.cibseven.connect.ai.agent"
    camunda:modelerTemplateVersion="1"
    implementation="##WebService">
  <bpmn:extensionElements>
    <camunda:connector>
      <camunda:inputOutput>
        <camunda:inputParameter name="agentName">Summarizer</camunda:inputParameter>
        <camunda:inputParameter name="message">Summarize: ${feedbackText}</camunda:inputParameter>
        <camunda:inputParameter name="instruction">Summarize the core concern in 10 words or less.</camunda:inputParameter>
        <camunda:inputParameter name="apiKey">${apiKey}</camunda:inputParameter>
        <camunda:outputParameter name="summaryResult">${output}</camunda:outputParameter>
      </camunda:inputOutput>
      <camunda:connectorId>cibseven-ai-agent</camunda:connectorId>
    </camunda:connector>
  </bpmn:extensionElements>
</bpmn:serviceTask>

Tip — async boundaries

AI calls take time and may fail transiently. Mark agent service tasks with camunda:asyncBefore="true" (and often asyncAfter) so the platform’s job executor handles retries and the call runs outside the request thread. The shipped demo models do this.

This snippet is adapted from the customer-feedback demo model. For richer, runnable examples — tool use, RAG, MCP, and a human-in-the-loop conversation — see Examples & Tutorials.

Working with AI output

An LLM is not a deterministic service. Design your process with that in mind:

  • Output varies. The same input can produce different wording — and occasionally different structure — on each run. Don’t assume byte-for-byte reproducibility; branch and validate on meaning, not exact strings.
  • ${output} is plain text. Even when you ask for JSON, the agent returns a String. To use structured fields, instruct the model to return JSON (see Examples) and parse it in a following step with Spin, e.g. ${S(agentOutput).prop("total").numberValue()}. The model can still deviate — keep a fallback path (e.g. an error/validation gateway) for unparseable output.
  • Calls can fail. Network errors, rate limits (429), and provider 5xx happen. The service task throws on failure; with camunda:asyncBefore="true" the job executor retries (per your retry config) and, once retries are exhausted, raises an incident for an operator to inspect. Mark agent tasks async, and consider a timeout/error boundary event for graceful handling.
  • Calls are slow. Expect seconds per call (more with tools/RAG/reasoning). Async execution keeps the call off the request thread. Cost and latency scale with context — see Cost & token usage and Configuring the Agent.

Because the agent can read untrusted content and (if given tools) act on it, also review Security & Data Handling before wiring tools onto tasks that process untrusted input.

Next steps

On this Page: