Examples & Tutorials

Worked examples that combine the features from the previous chapters. Each corresponds to a demo BPMN model.

Note on the demo files

Some demo models were authored against an earlier revision of the element template and use older field names (e.g. mcpServerUrl, openaiCustomHeaders, and the output variable agentResult). The current parameter names are the ones documented in Configuring the Agent and used in the snippets below — prefer those when building new models. The mcpToolsAgent.bpmn model already uses the current names (customHeaders, instructionMode, persistChatLog, agentOutput/agentOutput_aiMeta).

Invoice processing — extract structured data

Goal: read an invoice’s text and return structured fields for the next BPMN step.

Use a single AI Agent task with an instruction that asks for a specific JSON shape, and feed the document text as the message. The bundled system prompt steers the model toward a clean JSON contract (exact keys, no prose, no fences) when you ask for structured output — but an LLM can still deviate, so parse defensively: read agentOutput with Spin (e.g. ${S(agentOutput).prop("total").numberValue()}) in a following step and route unparseable output through a validation/error gateway. See Getting Started — Working with AI output.

<camunda:inputParameter name="agentName">InvoiceExtractor</camunda:inputParameter>
<camunda:inputParameter name="instruction">Extract the invoice as JSON: {"invoiceNumber": string, "total": number, "currency": string, "dueDate": string}. Use null for unknown fields.</camunda:inputParameter>
<camunda:inputParameter name="message">${invoiceText}</camunda:inputParameter>
<camunda:outputParameter name="invoiceJson">${output}</camunda:outputParameter>

A runnable invoice model also exists as a connector test resource (invoice-processing.bpmn) in the module’s src/test/resources.

RAG knowledge base — ingest then ask

Demo: knowledge-base.bpmn (process key read-from-rag).

Two connectors working together:

  1. Knowledge Ingestor task — embeds a document into pgvector (content, source, pgHost…, embeddingModelName, embeddingDimension) → ${chunksIngested}.
  2. AI Agent task — points at the same pgvector store (pgHost…pgTable, matching embeddingDimension/embeddingModelName). Setting pgHost activates RAG, and the agent answers from the retrieved chunks.

The classic demo ingests a made-up term (e.g. “Nevesbig”) and then asks the agent what it means; the agent retrieves the definition and answers from it rather than from training data. Keep embeddingModelName/embeddingDimension identical across both tasks. See RAG.

MCP tools — discover and call external tools

Demo: mcpToolsAgent.bpmn.

Configure one or more MCP servers in mcpServers; the agent lists the exposed tools, calls them, and aggregates the results into its answer:

<camunda:inputParameter name="agentName">McpAgent</camunda:inputParameter>
<camunda:inputParameter name="message">${userMessage}</camunda:inputParameter>
<camunda:inputParameter name="mcpServers">[{"name": "engine", "url": "http://localhost:8080/mcp"}]</camunda:inputParameter>
<camunda:outputParameter name="agentOutput">${output}</camunda:outputParameter>
<camunda:outputParameter name="agentOutput_aiMeta">${outputAiMeta}</camunda:outputParameter>

Tools appear to the model as engine__<toolName>. Each call’s provenance (server + original tool name) is captured in the audit trail. See Tools.

Process-as-tool — let the agent start a process

Demo: ai-agent-with-tools.bpmn (process key agent-with-tool-usage).

Register the built-in ProcessStarterTool and instruct the agent to launch a process and read its output:

<camunda:inputParameter name="agentName">Orchestrator</camunda:inputParameter>
<camunda:inputParameter name="toolClasses">org.cibseven.connect.ai.agent.impl.ProcessStarterTool</camunda:inputParameter>
<camunda:inputParameter name="message">Start the process "process-as-a-tool" and read its output variables whose names start with "out_".</camunda:inputParameter>
<camunda:outputParameter name="agentOutput">${output}</camunda:outputParameter>

The agent calls runProcessByKey, the connector starts the process under the caller’s identity, polls until it ends, and returns the out_-prefixed variables to the model. The started process appears in the audit log with its processInstanceId and executedAs. See Tools.

Human-in-the-loop — a memory-backed review loop

Demo: human-in-the-loop.bpmn (process key main-ai-process).

Enable chat memory and loop the agent through a user task so a person can review and refine its output across turns:

<camunda:inputParameter name="useChatMemory">${true}</camunda:inputParameter>
<camunda:inputParameter name="memoryId">${execution.getVariable('memoryId')}</camunda:inputParameter>
<camunda:inputParameter name="message">${feedback}</camunda:inputParameter>
<camunda:outputParameter name="agentOutput">${output}</camunda:outputParameter>
<camunda:outputParameter name="memoryId">${memoryId}</camunda:outputParameter>

First iteration creates the conversation (ID returned); subsequent iterations reuse it, so the agent sees the full exchange. See Chat Memory.

Customer feedback — sentiment + summary fan-out

Demo: customer-feedback.bpmn.

Two AI Agent tasks run in parallel (classify sentiment; summarize the concern), a gateway routes on the sentiment, and negative feedback goes to a human task showing the AI summary. A good template for mixing AI tasks with ordinary BPMN control flow. The Getting Started snippet is the summarizer task from this model.

On this Page: