Bpmn2ai

APMN — AI Process Model and Notation

BPMN for the AI era.

BPMN gave the world a shared language for business processes.
APMN gives the world a shared language for agentic processes.

---

What is APMN?

AI Process Model and Notation (APMN) is an open, vendor-neutral, visual notation standard for designing workflows where humans, AI agents, and automated systems collaborate.

It is a superset of BPMN 2.0 — every APMN file is a valid BPMN 2.0 XML document. APMN-specific constructs live in the apmn: extension namespace, meaning existing BPMN tools open APMN files without modification.

APMN adds what BPMN was never designed for:

BPMN 2.0	APN
Deterministic flow only	Probabilistic (confidence-based) routing
Human tasks and service calls	Agents, RAG, MCP tools, vector stores, memory
Binary gateways (yes/no)	Confidence gates, reasoning gates, semantic gates
No observability concept	Observability events baked into the notation
No multi-agent concept	Agent handoff as a first-class flow element

---

New Node Types

Node	Type	Description
🤖 agentTask	Task	LLM-driven task. Attrs: model, system_prompt, tools[], temperature
📚 ragTask	Task	Retrieval-augmented generation. Attrs: vector_store, top_k, similarity_threshold
🔌 mcpToolTask	Task	Invoke an MCP server tool. Attrs: server, tool_name, input_schema
👤 humanInLoopTask	Task	Agent proposes, human approves. Attrs: confidence_threshold, timeout
↗ agentHandoff	Task	Delegate to a specialist agent. Multi-agent orchestration.
🧠 memoryTask	Task	Read/write agent memory (session or long-term).
⬡ vectorTask	Task	Embed content into or query a vector store.
📡 observeEvent	Event	Emit a trace/span to an observability platform (LangFuse, Phoenix, OTEL).

New Gate Types

Gate	Description
confidenceGate	Routes on agent confidence score (0.0–1.0). Replaces binary exclusiveGateway.
reasoningGate	Routes by parsing LLM chain-of-thought output. No hard-coded condition.
modelVersionGate	A/B or canary route between model versions. Safe model upgrade pattern.
semanticGate	Routes by vector similarity — input matched against intent clusters.
mcpGate	Calls an MCP tool and routes on result (pass/fail/review).
escapeGate	Auto-escalation. If agent fails, times out, or hits confidence floor — route to human.

---

Quick Example

# APMN v0.1 — Patient Preadmission
# xmlns:apmn="http://apmn.kshetra.studio/ns/1.0"

process:
  id: patient_preadmission
  name: Patient Preadmission
  targets: [orkes, google_adk]

nodes:
  - id: verify_insurance
    type: agentTask
    model: gemini-2.0-flash
    tools: [mcp://insurance-api, mcp://medicare-lookup]
    confidence_threshold: 0.95

  - id: check_policy_docs
    type: ragTask
    vector_store: hospital_policy_kb
    top_k: 5

  - id: gw_confidence
    type: confidenceGate
    source: verify_insurance.confidence
    routes:
      high:   ">= 0.95 → proceed"
      medium: "0.7–0.95 → human_review"
      low:    "< 0.7 → escalate"

  - id: compliance_check
    type: mcpToolTask
    server: mcp://compliance-checker.kshetra.studio
    tool: check_hipaa_consent

  - id: log_trace
    type: observeEvent
    platform: langfuse
    trace_name: insurance_verification

---

Reference Implementation

TwinTrack is the reference compiler for APMN.

APMN YAML / BPMN 2.0 + apmn: XML
             ↓
         TwinTrack
        /         \
Orkes JSON   Google ADK Python   (LangGraph, AWS Bedrock — coming)

---

Relationship to BPMN 2.0

APMN is designed as a superset, not a replacement:

• APMN YAML files are the primary authoring format (human-readable, diff-friendly)
• APMN also supports BPMN 2.0 XML with apmn: extension elements as an alternative input
• All existing BPMN 2.0 node types (serviceTask, userTask, parallelGateway, etc.) are valid APMN and pass through unchanged
• APMN extension elements are ignored by BPMN tools that don't support them — full backward compatibility

---

Spec

• APMN Specification v0.1
• YAML Schema
• BPMN Extension Schema (XSD)
• Examples

---

TwinTrack MCP Server

TwinTrack is the reference compiler for APMN. It exposes an MCP server so any MCP-compatible AI client can convert and compile APMN workflows directly.

Tools

Tool	Description	Cost
migrate_bpmn	Convert BPMN 2.0 XML → APMN YAML	1 credit
compile_apmn	Compile APMN YAML → Orkes JSON or Google ADK Python	1 credit
suggest_node_upgrade	Guidance on upgrading a node to a better APMN type	Free
review_model	Best-practice review of a complete APMN model	Free
get_apmn_spec	Spec and platform mappings for any APMN node type	Free
list_samples	List bundled demo BPMN files	Free

Connect

Claude Desktop / Cursor — add to claude_desktop_config.json:

"twintrack": {
  "command": "npx",
  "args": ["-y", "mcp-remote", "https://bpmn2ai.kshetra.studio/mcp/", "--header", "X-Api-Key: YOUR_KEY"]
}

Claude Code CLI:

claude mcp add --transport http twintrack https://bpmn2ai.kshetra.studio/mcp/ --header "X-Api-Key: YOUR_KEY"

Get your API key at bpmn2ai.kshetra.studio — free tier available.

---

Roadmap

Version	Theme
v0.1 (now)	Core node types, gates, YAML schema, XSD extension
v0.2	Visual shape library, BPMN.io plugin
v0.3	VS Code extension, APMN Playground
v1.0	Stable spec, multiple reference implementations
v2.0	Submit to OMG BPMN 3.0 working group

---

Contributing

APMN is governed as an open community standard. See CONTRIBUTING.md.

All contributions are welcome — spec clarifications, new node type proposals, example workflows, tooling.

---

License

Apache License 2.0 — see LICENSE.

The APN specification and all artefacts in this repository are free to use, implement, and extend without restriction.

---

APMN is an open standards initiative by Kshetra Studio.
Website: apmn.kshetra.studio · GitHub: kshetra-studio/apmn