Vibeleaderboard
← All Intel
Intel / article

Workflow SDK adds idempotent starts

Source
vercel.com
Author
Alex Langenfeld
Date

Context

Version 5.4.0 of Vercel's Workflow SDK lets an application start a workflow run at most once per key, even when the same request arrives twice. The SDK runs workflows built from steps that the framework can retry. It also has hooks: channels identified by a that let outside code send data into a running workflow with `resumeHook()`. According to the changelog, the previous approach was to look a up with `getHookByToken()` and then call `start()`, and the gap between those two calls left a documented race in which the same run could be started twice.

In the new version, `start()` accepts an `experimental_hook` option with a token and admits the run and claims that token in one atomic step. The token comes from the application's own data, such as an order or invoice ID. Exactly one run owns it; a duplicate `start()` throws `HookConflictError` carrying the owner's `conflictingRunId`, and the duplicate never becomes a run. Because the hook exists from the moment the run is admitted, the duplicate request's data can be forwarded to the owning run with `resumeHook()`, and payloads sent before the workflow starts listening are kept and delivered in order.

The guarantee lasts only while the token is held. The idempotency documentation says the token is released when the run ends unless `experimental_minRetention` is set, so without it a late duplicate starts a new run; there is no default retention. Disposing the start hook inside the workflow also releases the token at once, even while the run continues.

Key takeaways · AI-distilled
  • The idempotency key is a token from your own domain, such as an order, invoice, import or request ID. Exactly one run owns it, and a duplicate start() throws HookConflictError carrying the owner's conflictingRunId and never becomes a run.
  • The claimed hook exists from the moment the run is admitted, so resumeHook works before the run begins executing, and payloads that arrive early are buffered and delivered in order.
  • Inside the workflow, createHook with the same token binds to the already-claimed hook without registering anything new or adding a step. A workflow that never opens the hook still completes normally, with the token serving only as an idempotency key.
  • Setting experimental_minRetention keeps the token unavailable after the run ends, counted from start(), so late duplicates are still refused. The change ships in workflow 5.4.0.
Terms in this piece · Glossary
  • token — The chunk of text a model reads and writes in — roughly three-quarters of a word — and the unit AI usage is billed in.
  • agent hook — A script the harness runs automatically at a fixed point in an agent's loop — before a tool call, after an edit, on session start.
Recommended reads
Comments

Checking sign-in…

Loading comments…