Skip to content
ArtificialFlow

Workers

Service tasks, send tasks, and connectors become external jobs. A worker activates a job, does the work, then completes or fails it.

Contract

  • Send X-Workflow-Worker-Protocol-Version: v1. The response carries X-Workflow-Engine-Protocol-Version.
  • GET /jobs/capabilities lists the worker features this server supports.
  • Activate with POST /jobs/activate. Complete, fail, and extend the lock at /jobs/{key}/complete, /fail, and /extend-lock.
  • Mutation calls send Idempotency-Key, at most 128 characters. Complete, fail, and extend-lock each use a distinct key, even on the same job. A retry of the same operation reuses that key and replays the accepted result. The scope is the operation plus the job key.
  • If the work can outlast the lock, call extend-lock before it expires. A lock-ownership error ends that activation.
  • gRPC JobWorkerService listens on the command process at GRPC_ADDR, default :50051. The gateway does not publish it. Use HTTP /jobs/* unless you control the pod network.

The caller needs artificialflow client. The maintained clients are createWorker in @artificialflow/nodejs-sdk, artificialflow_worker.Worker in the Python package, and backend/libs/worker for Go. Another language uses these same HTTP routes. make worker-conformance is the wire check for /jobs/*.

Connectors

Set artificialflow:taskType on a service or send task. The modeler properties panel lists the official types. Input names are copied onto the job when the instance does not already have them. Start variables with the same names override the diagram.

Job typeInputs
io.artificialflow.connector.httpurl, method, headers, body, timeoutMs, failOnNon2xx
io.artificialflow.connector.webhookwebhookUrl, payload, webhookToken
io.artificialflow.connector.kafkakafkaTopic, kafkaKey, kafkaValue
io.artificialflow.connector.emailemailTo, emailSubject, emailBody
io.artificialflow.connector.s3s3Bucket, s3Key, s3Body, contentType
io.artificialflow.connector.sendDefault type for a send task that does not name another connector.

HTTP and webhook connectors re-check redirect targets against the configured allowlist. There is no built-in mailer: an email job is work for your worker.

curl -fsS http://localhost:9100/api/jobs/capabilities \
  -H "Authorization: Bearer $ARTIFICIALFLOW_TOKEN" \
  -H "X-Workflow-Worker-Protocol-Version: v1"