| name | agent |
| description | Design and add a Camunda AI Agent Sub-process to a new or existing BPMN process — model, prompts, tools, and a mocked test scenario. Usage: /bpmnkit:agent [file] <description> |
Design an AI agent: $ARGUMENTS
Read references/agentic.md first — it has the full binding-key facts and a verified example. Read references/connectors.md for tool candidates, references/plan-format.md for the plan shape, and references/feel.md for prompt/condition syntax.
1. Design the agent
From the description, work out:
- Provider/model — default to the user's configured model if the plugin's
userConfig has one set, otherwise ask. Provider auth (provider.<provider>.authentication.*) always uses {{secrets.NAME}}.
- System prompt — a clear brief of the agent's role and constraints, as
systemPrompt.
- User prompt — usually a FEEL reference to an incoming process variable (
"=ticketText"), not a literal.
- Tools — one per capability the agent needs. For each: run
casen connector search "<capability>" first; if a connector template exists, use it (tools[].connector); otherwise use a plain tools[].jobType (and scaffold a worker for it, per /bpmnkit:implement step 6). Every tool needs an id, a description written for the LLM to read, and params for anything the LLM should control at call time.
- Limits — a sensible
maxModelCalls (default 10 is usually fine; lower it for cheap/fast tools, raise it for open-ended research tasks).
- Error boundary — always give the agent step an
errorBoundary (see references/agentic.md's example) so an agent/tool failure has somewhere to go.
2. Write or extend the plan
New process: write a full plan with the aiAgent step per references/plan-format.md. Existing process: use the /bpmnkit:extend flow (casen plan extract → delta plan containing the aiAgent step → casen synth --merge).
3. Compile and lint
casen synth <plan>.json --output <file>.bpmn
casen lint lint <file>.bpmn --categories agentic
Fix any agentic/* findings (a tool with an incoming sequence flow, a tool with no description, a fromAi() call not referencing toolCall.*, missing output aggregation) by editing the plan, then re-synth. Ignore data-flow findings against the agent's own provider/model/prompt bindings — see the "Known noisy finding" note in references/agentic.md.
4. Test with a mocked agent job
Add a scenario mocking io.camunda.agenticai:aiagent-job-worker:1 with a plausible final response (see references/agentic.md's scenario example), then:
casen test <file>.bpmn
This verifies the process routes correctly around the agent step — it does not exercise real model behavior or tool-calling, which is out of scope for casen test.
5. Summarize
Report: the tool schema the LLM will see (tool ids + descriptions + parameters, derived from what you wrote — this is literally what the agent is told), the model/provider, and the test result.
