Activity Handlers

Activity handlers replace graph TaskExecutors. They perform side effects and return a typed result. They do not emit routing effects or mutate workflow tokens.

ActivityBinding.from(
  reserve,
  (context, order) => reservationService.reserve(
    order,
    idempotencyKey: context.idempotencyKey,
  ),
);

A class may implement ActivityHandler<I, O>, or use ActivityHandler.from. Concise hosts belong in the product module, not in workflow code.

Rules

• Use context.idempotencyKey for every external write.
• Heartbeat long work; the lease is the liveness signal.
• Classify failures as retryable or permanent.
• Do not start other workflows or complete user tasks from a handler. Return a result and let the workflow decide.

Retries

The runtime creates the next attempt. Manual retry through the service API creates a new attempt and keeps the idempotency key. Exhausted work appears in the dead-letter list.

See Also

• Service Tasks
• Idempotency
• ActivityHandler API