Skip to Content
BlogAgenten als External Task

AI-Agenten als External Task: die Agent Runtime an der Engine anschließen

Martin MöllenbeckAgent RuntimeExternal TasksEngineBPMNOpenClawKI-Agenten

Ein BPMN-Prozess, der an einer Stelle eine KI braucht — eine Frage beantworten, einen Text prüfen, einen Bug analysieren. Der naheliegendste Weg wäre Glue-Code: ein eigener Worker, der die KI-API aufruft. Mit der ProcessCube Agent Runtime geht es ohne: Ein Engine-Plugin macht jeden OpenClaw-Agenten zum External-Task-Worker. Im Diagramm ist der Agent dann eine ganz normale ServiceTask mit einem Topic — die Engine merkt keinen Unterschied.

In Entwicklung. Die Agent Runtime und das Engine-Plugin sind Teil der Preview-Phase (1.1.0-develop.x). Schnittstellen, Payload-Schemas und Verhalten können sich vor dem ersten Stable-Release noch ändern.

Nicht der LowCode-Weg. Dieser Artikel beschreibt die External-Task-Anbindung über das Engine-Plugin processcube-engine. Der Weg über die LowCode-Nodes (openclaw-message-send per WebSocket-Gateway) ist ein eigener, paralleler Pfad — den zeigen Agent Runtime in 15 Minuten und OpenClaw-Agenten aus LowCode. Beide Wege sprechen dieselbe Runtime an, aber über verschiedene Mechanismen.

Wie es funktioniert

Im Agent-Runtime-Image steckt das OpenClaw-Channel-Plugin processcube-engine. Für jedes konfigurierte Topic startet es einen eigenen ExternalTaskWorker (aus dem Engine-Client), der Tasks per Fetch-and-Lock von der Engine holt. Welcher Agent den Task bearbeitet, entscheidet ein Binding: Das Topic wird auf eine Agent-ID aufgelöst, der Agent erhält den Task-Payload als Nachricht und seine Antwort finalisiert die ServiceTask.

Für die Topics hat sich eine einfache Konvention bewährt: ai.<prozess>.<rolle> — etwa ai.demo.frage oder ai.bug-fixen.seniordeveloper. So ist am Topic ablesbar, welcher Prozess welche Rolle anspricht, und jede Rolle kann auf einen anderen Agenten gebunden werden.

Einrichten Schritt für Schritt

Vorausgesetzt wird eine laufende Agent Runtime mit aktiviertem KI-Backend — das Setup dafür zeigt der Einstiegs-Artikel bzw. die Erste Einrichtung.

Plugin an die Engine binden

Das Plugin ist im Image bereits installiert und registriert — es braucht nur noch die Engine-Verbindung:

pc-runtime plugin bind --engine-url http://engine:10560 --token <root-access-token>
docker compose restart
pc-runtime plugin status   # erwartet: registriert + geladen + gebunden

Läuft die Engine in einem eigenen Compose-Stack, verbindet ein gemeinsames Docker-Netz (pc-shared) die beiden — wie im Einstiegs-Artikel beschrieben.

Topic und Binding konfigurieren

Pro Topic ein Worker, pro Binding ein Agent. Beides landet in der OpenClaw-Konfiguration (~/.openclaw/openclaw.json) — am einfachsten per config patch:

echo '{
  "channels": {
    "processcube-engine": {
      "tasks": { "topics": ["ai.demo.frage"] }
    }
  },
  "bindings": [
    {
      "agentId": "demo-worker",
      "match": { "channel": "processcube-engine", "accountId": "ai.demo.frage" }
    }
  ]
}' | openclaw config patch --stdin
docker compose restart

Nach dem Neustart zeigt das Gateway-Log pro Topic einen gestarteten Worker:

[processcube-engine:tasks] ExternalTaskWorker started — engineUrl=http://engine:10560 topic=ai.demo.frage

ServiceTask im BPMN modellieren

Im Diagramm ist der Agent eine ServiceTask vom Typ external mit dem Topic — der Payload kommt als camunda:property mit, wahlweise statisch oder aus dem Prozess-Token:

<bpmn:serviceTask id="frageStellen" name="Frage stellen"
                  camunda:type="external" camunda:topic="ai.demo.frage">
  <bpmn:extensionElements>
    <camunda:properties>
      <camunda:property name="payload" value="token.current" />
    </camunda:properties>
  </bpmn:extensionElements>
</bpmn:serviceTask>

Deployen und starten

Ab hier ist es Engine-Alltag — zum Beispiel über die CLI:

pc engine deploy ./processes/demo.bpmn
pc engine start ai_demo_process StartEvent_1 \
  --start-token '{"aufgabe": "Was ist die Hauptstadt von NRW?"}'

Die Engine legt den External Task an, der Worker holt ihn ab, der Agent antwortet — und die Prozess-Instanz läuft mit dem Ergebnis weiter.

Payload und Result

Zwischen Engine und Agent ist ein schlankes JSON-Schema (schemaVersion "0.1") vereinbart. Der Agent bekommt die Aufgabe samt Prozess-Kontext:

type AgentPayload = {
  schemaVersion: '0.1';
  task: string;
  process: { id: string; instanceId: string; activityId?: string };
  context?: Record<string, unknown>;
  references?: { project?: string; repo?: string; stageUrl?: string };
  meta?: { deadline?: string };
};

Zurück kommt ein strukturiertes Ergebnis — kein Freitext:

type AgentResult = {
  schemaVersion: '0.1';
  status: 'ok' | 'needs_clarification' | 'blocked' | 'error';
  summary: string;
  outputs?: Record<string, unknown>; // wird zu Prozessvariablen
  openQuestions?: string[];
  nextHints?: string[];
};

Drei Eigenschaften machen das BPMN-tauglich:

  • outputs werden Prozessvariablen — nachfolgende Tasks und Gateways arbeiten direkt mit dem Agenten-Ergebnis weiter.
  • status: "error" wird zum ExternalTaskError — im Diagramm fängt ihn ein ganz normales Boundary-Event ab.
  • Antwortet der Agent ohne verwertbaren Text, erzeugt das Plugin ein needs_clarification-Fallback statt eines harten BPMN-Errors — der Prozess kann damit kontrolliert umgehen, etwa über einen User Task.

Stolpersteine

  • Token roh übergeben. Der rootAccessToken wird ohne Bearer -Prefix konfiguriert — den hängt der Engine-Client selbst an. Mit Prefix quittiert die Engine mit jwt malformed.
  • Ein Worker pro Topic. Ein leeres tasks.topics bedeutet: kein Worker, keine Abholung. Nach jeder Topic-Änderung das Gateway neu starten und im Log die ExternalTaskWorker started-Zeilen prüfen.
  • Sessions sind pro Task isoliert. Jeder External Task bekommt eine eigene Agent-Session — Kontext zwischen Tasks fließt über Prozessvariablen, nicht über den Chat-Verlauf.

Fazit

Die External-Task-Anbindung macht KI-Agenten zu erstklassigen Prozess-Teilnehmern: Im BPMN bleiben sie gewöhnliche ServiceTasks mit Topic, Fehlerbehandlung läuft über Boundary-Events, Ergebnisse landen als Prozessvariablen im Token. Kein Glue-Code, kein eigener Worker-Prozess — Topic konfigurieren, Agent binden, modellieren.

Weiterführend

Ticketpilot-Release-ProzessAgent Runtime in 15 Minuten