Camunda 8 KYC Agent Example

A demo showcasing AI-powered Know Your Customer (KYC) onboarding built on Camunda 8 SaaS. It combines BPMN process orchestration, agentic AI via AWS Bedrock, DMN-based risk scoring, email-driven document collection, and human-in-the-loop approval — all without any custom-deployed application code.

---

Part 1: What This Demo Shows

The Scenario

Allied Henna Bank needs to onboard new customers while satisfying KYC and Anti-Money Laundering (AML) compliance requirements. The process is time-consuming and requires cross-checking multiple data sources, collecting documents from applicants, and producing a formal compliance report for review by a bank clerk.

This demo automates that workflow end-to-end using a Camunda 8 AI agent called Daria Quinn — a sharp, well-read KYC specialist who handles the repetitive legwork so the human clerk can focus purely on final judgment.

The User Journey

1. Application submitted — A customer fills out an intake form with their name, address, email, employment details, and other identity information.
2. Agent investigates — Daria autonomously calls a series of tools to look up the customer in internal systems, check sanctions lists, validate their address, search for existing accounts, and retrieve the latest KYC procedural requirements.
3. Documents requested — When additional evidence is needed, Daria sends an email to the customer requesting specific documents. The process pauses and waits for a reply. Attachments are automatically extracted and their data parsed by a secondary AI agent.
4. Risk scored — A DMN decision table evaluates the customer's trust level, country of residence, and debt level to produce an aggregate risk score.
5. Report produced — Daria compiles her findings into a structured markdown report and routes it to a human clerk via Camunda Tasklist.
6. Clerk decides — The clerk reviews the report, leaves feedback, and either approves or rejects. If approved, a customer record is created in the bank's system. If rejected, the applicant receives a notification email.

What Makes It Interesting

• The AI agent is not a chatbot — it is a process participant. Camunda orchestrates every tool call, and the agent's actions are fully visible in the audit trail.
• The clerk always has the final word. The agent's system prompt explicitly prohibits ending the process without clerk approval, making this a true human-in-the-loop architecture.
• The demo works entirely within Camunda 8 SaaS using built-in connectors — no custom job workers or microservices need to be deployed.

---

Part 2: Technical Features and Implementation Details

Architecture Overview

Camunda 8 SaaS (Zeebe)
│
├── KYC Agent.bpmn              Main orchestration process
│   ├── Ad-hoc subprocess       Agentic execution container
│   │   ├── AI Agent task       AWS Bedrock / Claude Haiku 4.5
│   │   └── Tool tasks (×11)    Connectors called by the agent
│   ├── Human tasks             Clerk review and approval gates
│   └── Event subprocesses      SLA timer, broadcast signal, rejection escalation
│
├── Validate Document.bpmn      Sub-process for per-document AI validation
│
├── Request Document from Customer.bpmn   Email-based document collection
│   ├── SMTP connector          Sends request email to customer
│   ├── IMAP connector          Polls inbox every 3 seconds for reply
│   └── AI Agent task           Extracts structured data from attachments
│
└── risk_calculation.dmn        Multi-criteria risk scoring table

AI Agent Implementation

The main agent uses the Zeebe agenticai connector (io.camunda.agenticai:aiagent-job-worker:1), which implements the agentic loop directly inside Camunda without any external orchestration framework.

Parameter	Value
Provider	AWS Bedrock
Model	us.anthropic.claude-haiku-4-5-20251001-v1:0
Max tokens	20,000
Max model calls	20
Memory type	In-process
Memory window	20 messages
Tool execution mode	WAIT_FOR_TOOL_CALL_RESULTS

The WAIT_FOR_TOOL_CALL_RESULTS mode is key: when the model decides to call a tool, Zeebe pauses the agent job and activates the corresponding tool task as a separate service task in the ad-hoc subprocess. The result is written back to the process, and the agent job resumes with the tool output appended to its context. This means every tool call is a first-class Camunda activity — visible in Operate, tracked in the audit log, and independently retriable on failure.

Ad-hoc Subprocess and Tool Tasks

The agent's tools are modelled as service tasks inside a BPMN Ad-hoc Subprocess. The agent can invoke any combination of them in any order across multiple turns:

Tool	Implementation
Get KYC Procedures	HTTP GET connector → GitHub raw content
Validate Customer Address	Custom match-customer-with-dri connector
Search Accounts	Custom search-account connector
Check Sanctions List	Custom query-for-company connector
Calculate Risk Score	DMN business rule task
Request Documents	Call activity → RequestKYCDocumentCustomer process
Validate Document	Call activity → Validate Document sub-process
Get Document Requirements	HTTP GET connector → GitHub raw content
Ask Clerk for Support	User task in Camunda Tasklist
Create Customer Record	Custom manage-customer-record connector
Send Rejection Email	SMTP email connector

Document Request Sub-Process

Request Document from Customer.bpmn handles asynchronous email-based document collection:

1. An SMTP connector emails the customer requesting specific documents.
2. An event-based gateway races two outcomes:
   • An IMAP connector polls imap.gmail.com:993 every 3 seconds for a reply in the KYCDocumentRequest folder.
   • A 5-minute boundary timer fires if no response arrives.
3. If email is received, attachments are processed in a multi-instance loop — one iteration per attachment — using a secondary AI agent (Claude Sonnet 4.5) to extract structured JSON data from each document.
4. Results are aggregated and returned to the calling process.

Document Validation Sub-Process

Validate Document.bpmn uses a third AI agent (Claude Sonnet 4) to evaluate whether a document satisfies the stated requirements. The agent fetches the requirements definition, reviews the document content, and produces a pass/fail report with detailed feedback. A user task gives the clerk visibility into the result before the sub-process closes.

DMN Risk Scoring

risk_calculation.dmn applies a COLLECT + SUM hit policy across three inputs:

Input	Values
riskLevel	L1, L2, L3 (customer trust tier)
country	Customer's country of residence
currentDebt	Numeric debt value

Rules add to the aggregate score independently, so multiple risk factors compound. An L3 trust level, a country on the high-risk list, and high debt can each contribute 5 points, with medium-risk scenarios contributing 2. The total score is passed back to the agent as tool output.

Human-in-the-Loop Gates

Three user tasks act as explicit approval gates:

• Send Report for Approval and Feedback — The clerk reads Daria's full markdown report and leaves comments. The agent receives this feedback and can act on it before the next decision.
• Validate Customer Record Request — Before a customer record is created, the clerk confirms the name, address, email, and trust level to be written.
• Validate Agent Success — Final sign-off before the process ends successfully.

Event Handling

The main process includes three non-interrupting event subprocesses attached to the ad-hoc container:

• Client update message — The customer can send an unsolicited update mid-process; the agent receives it as context.
• Universal broadcast signal — A company-wide signal (e.g. policy change) can be injected into any active instance.
• SLA warning timer — A 15-minute non-interrupting timer fires a warning if the process is running long, giving operations teams visibility without stopping the flow.

Rejection is handled via an escalation event thrown from within the ad-hoc subprocess, caught by a boundary event on the container, and routed to a rejection end event that triggers the SMTP notification.

Connector Templates

Five custom connector templates live in KYCAgent/KYC Agent/ConnectorTemplates/. These are JSON schema definitions that configure the appearance and input/output mapping of each custom task in Camunda Web Modeler:

• match-customer-with-dri.json — Address and identity matching with fuzzy search
• search-account.json — Account lookup by multiple search modes
• query-for-company.json — Company/sanctions search
• manage-customer-record.json — Customer record CRUD
• search-employee.json — Employee directory lookup

Key Process Variables

Variable	Purpose
applicationId	9-character UUID generated at process start
customerDetails	Initial form submission payload
KYCAgent	Agent context object including conversation history
chainOfThoughtAgent	Structured evaluation from document validation
detailsOfAttachments	Parsed data extracted from email attachments
toolCallResults	Aggregated results returned to the agent after tool execution

---

Part 3: Setup and Running on Camunda 8 SaaS

Prerequisites

• A Camunda 8 SaaS account (camunda.com) with an active cluster running version 8.9.0 or later
• An AWS account with access to AWS Bedrock and the following models enabled in your chosen region:
  • us.anthropic.claude-haiku-4-5-20251001-v1:0
  • us.anthropic.claude-sonnet-4-5-20250929-v1:0
  • us.anthropic.claude-sonnet-4-20250514-v1:0
• A Gmail account configured with an App Password (standard Gmail password authentication does not work with SMTP/IMAP connectors). Create a dedicated label/folder called KYCDocumentRequest in that Gmail account.
• Access to Camunda Web Modeler (included with SaaS)

Step 1: Configure Secrets

In your Camunda 8 SaaS Console, navigate to your cluster and open Connector Secrets. Add the following secrets:

Secret Key	Value
AWS_REGION	Your AWS region (e.g. us-east-1)
AWS_ACCESS_KEY	Your AWS IAM access key ID
AWS_SECRET_KEY	Your AWS IAM secret access key
EMAIL_USER_NAME_DMN	Full Gmail address (e.g. yourname@gmail.com)
EMAIL_PASSWORD_DMN	Gmail App Password (16-character string from Google Account settings)

Step 2: Import Connector Templates

The custom connector templates must be imported before the BPMN files so that Modeler can render the custom task configurations correctly.

1. In Camunda Web Modeler, open your project.
2. Navigate to Connector Templates (or the organization-level template library).
3. Upload each JSON file from the KYCAgent/KYC Agent/ConnectorTemplates/ folder:
   • search-account.json
   • match-customer-with-dri.json
   • query-for-company.json
   • manage-customer-record.json
   • search-employee.json

Step 3: Import Process Files

Import the following files into Web Modeler in this order (dependencies first):

1. KYCAgent/KYC Agent/risk_calculation.dmn
2. DocumentRequestProcess/Document Request Process/Request Document from Customer.bpmn
3. DocumentRequestProcess/Document Request Process/Request Document Call Activity.bpmn
4. KYCAgent/KYC Agent/Validate Document.bpmn
5. KYCAgent/KYC Agent/KYC Agent.bpmn

Also import all .form files found alongside the BPMN files — these define the Tasklist UI for human tasks and must be present before deployment.

Step 4: Deploy to Your Cluster

1. Open KYC Agent.bpmn in Web Modeler.
2. Click Deploy and select your target cluster.
3. Repeat for each of the other BPMN and DMN files listed above.

All five resources (KYC Agent.bpmn, risk_calculation.dmn, Request Document from Customer.bpmn, Request Document Call Activity.bpmn, Validate Document.bpmn) must be deployed to the same cluster.

Step 5: Start a Process Instance

1. In Web Modeler (or via Operate), start an instance of the KYC-Agent process.
2. Provide an initial customerDetails variable as JSON. For example:

{
  "customerDetails": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "address": "123 Main Street, Springfield, USA",
    "employerName": "Acme Corp",
    "country": "United States"
  }
}

Step 6: Monitor and Interact

• Camunda Operate — Watch the process token move through the diagram in real time. Inspect variable state and the full audit trail of agent tool calls.
• Camunda Tasklist — When a user task appears (clerk review, record validation, or final approval), open Tasklist, claim the task, and complete it using the embedded form.
• Email inbox — If the agent decides to request a document from the customer, an email will arrive at the address in customerDetails.email. Reply with the requested document attached to continue the process.

Troubleshooting

Symptom	Likely cause
Agent task fails immediately	AWS credentials or model access not configured; verify secrets and Bedrock model enablement
IMAP connector fails	Gmail App Password not set; ensure 2FA is enabled and an App Password is generated
Custom task shapes show as generic service tasks	Connector templates not imported before BPMN files
Document email never arrives	Check that the Gmail address in the SMTP connector (shearsmithcamunda@gmail.com placeholder) is replaced with your actual EMAIL_USER_NAME_DMN secret reference
Process instance stuck at tool task	Check Operate for an incident; the tool task may have received an error response from the connector — inspect the error message and verify the connector template version matches

External Data Dependencies

The process fetches KYC procedure documents and document requirement definitions from a public GitHub repository at runtime:

https://raw.githubusercontent.com/NPDeehan/TestDataDump/refs/heads/main/KYC/

These files define what the agent knows about current bank procedures and what documents it may request. They can be updated independently of the deployed process.