[AIT-1073] Vercel WDK docs for AI Transport by VeskeR · Pull Request #3463 · ably/docs

VeskeR · 2026-07-08T12:13:48Z

Description

Docs for running the AI Transport SDK with Vercel Workflow DevKit (WDK), alongside the existing Temporal integration.

Framework page (frameworks/workflow-devkit.mdx) — how AIT composes with WDK: one activity per Step, WDK step ids used as stepIds (no helper needed), channel-routed cancels, and how the driver-owned loop handles server, client, and approval-gated tool calls.
Getting-started guide (getting-started/workflow-devkit.mdx) — a Next.js walkthrough mirroring the Temporal one.
Nav entries plus cross-links from the durable-execution, Steps, tool-calling, roadmap, and Temporal pages.

Based on the WDK demo from ably/ably-ai-transport-js#253

Resolves AIT-1073

Checklist

Commits have been rebased.
Linting has been run against the changed file(s).
The PR adheres to the writing style guide and contribution guide.

coderabbitai · 2026-07-08T12:13:59Z

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 4413ba4e-f829-409d-9074-472ad23fc19f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch AIT-1073/WDK-docs

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

zknill

There should be a skill in this repo called /write-docs that encodes some of the anti-llm language rules. Might be worth running it on the diff.

zknill · 2026-07-09T12:59:32Z

+
+A WDK step that produces agent output publishes it as a single Step, using the WDK step id as that Step's `stepId`. That is the join between the two systems: WDK's retryable unit and AI Transport's supersedable unit share one identifier.
+
+Read the id with [`getStepMetadata()`](https://useworkflow.dev/docs/api-reference/workflow/get-step-metadata) from the `workflow` package, inside the step. WDK step ids are stable across retries of the same step and unique across workflow runs, so they pass straight into `createStep` with no prefixing. This is where the composition is lighter than [Temporal's](/docs/ai-transport/frameworks/temporal), whose per-workflow activity ids need the `stepIdFor` helper to stay distinct on the channel.


I don't think we need to reference temporal here

zknill · 2026-07-09T13:00:05Z

+        {
+          name: 'Vercel WDK',
+          link: '/docs/ai-transport/frameworks/workflow-devkit',
+        },


lets have this above "temporal" so that all the vercel stuff is grouped

zknill · 2026-07-09T13:03:50Z

+
+## Suspend and resume across workflows <a id="suspend-resume"/>
+
+A [suspend](/docs/ai-transport/features/human-in-the-loop) does not park the workflow to wait. The WDK step holding the Run calls `run.suspend()`, publishes `ai-run-suspend`, and returns; the workflow completes. When the client posts a continuation invocation (a tool result or an approval response), the agent route starts a fresh workflow. That workflow's `openRun` step calls `createRun` as usual; the SDK reads the existing `runId` the continuation's trigger names and publishes `ai-run-resume` rather than `ai-run-start`.


Drop first sentence, it reads weird: A suspend does not park the workflow to wait.

zknill · 2026-07-09T13:06:38Z

+
+The invocation is a poke and a pointer. Its HTTP body carries no session content, only the id of the channel event the client just published; the agent reads that event from the channel to learn what to do. One workflow run per HTTP POST, so continuations are new workflow runs on the same AI Transport `runId`, not resumes of the original workflow.
+
+WDK's own hooks can hold a workflow open while it waits for external input. The composition here ends the workflow instead, because the continuation arrives as a fresh POST from the AI Transport client and its trigger already points at the channel event that resumes the Run. The client stays identical to the [Vercel AI SDK integration](/docs/ai-transport/frameworks/vercel-ai-sdk-ui), with no workflow-aware code on the browser side.


"The composition" reads weird here, maybe "The design in the Getting Started workflow" with a link.

zknill · 2026-07-09T13:08:28Z

+
+In local development the runtime stores run state in `.workflow-data/`; add that directory to `.gitignore`.
+
+## Define the workflow <a id="define-workflow"/>


I mentioned in slack that we could make these H3s under a H2, so that the ToC reads nicer

zknill · 2026-07-09T13:08:56Z

+
+`runInference` adopts the Run and runs one model call. `stripToolExecutes` and `stopWhen: stepCountIs(1)` keep the Vercel AI SDK from running its own tool loop, so the model emits its tool-call parts and stops; the workflow drives the loop. `runInference` then routes the pending calls: a tool with a server `execute` becomes a `runTool` step; anything else suspends the Run for the client to answer. This guide uses a single server tool; the [framework page](/docs/ai-transport/frameworks/workflow-devkit#tool-calls) and [tool calling](/docs/ai-transport/features/tool-calling) cover client-executed and approval-gated tools.
+
+`awaitAttemptVisible` covers the one retry hazard. When WDK re-runs an inference, the superseding `ai-step-start` is not in the read model the instant it publishes, so reading the prompt too early would trail the failed attempt's half-streamed reply as an assistant prefill that real providers reject. The guard waits for the retry's attempt to reflect and returns at once on the first attempt.


I mentioned in slack that this is the only bit I didn't really understand.

awaitAttemptVisible was a leftover from the previous fused "open + first inference" step. The guard is not needed anymore, I've removed it from the docs and from the WDK demo in ably/ably-ai-transport-js#258

Document running the AI Transport SDK on Vercel Workflow Development Kit (Vercel WDK), the in-app durable-execution integration, alongside the existing Temporal one. - frameworks/workflow-devkit: how AI Transport composes with Vercel WDK. The workflow opens the Run and runs each model call and tool as its own WDK step, using the WDK step id as the AI Transport Step id so a retry supersedes the failed attempt on the channel rather than appending beside it. Covers the driver-owned tool loop for server, client-executed, and approval-gated tools, channel-routed cancels, and suspend and resume across workflows. - getting-started/workflow-devkit: a Next.js walkthrough that opens the Run and runs each inference as its own retryable step, with a flaky tool that shows a retry superseding the failed attempt on the channel. Add the two framework diagrams, nav entries under By SDK and Frameworks, and cross-links from the Steps, durable-execution, tool-calling, concepts, roadmap, going-to-production, and Temporal pages. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Two documentation-wide accuracy fixes against @ably/ai-transport v0.5.0. AgentSession no longer has close(): teardown is end(), which closes any still-open Run as `cancelled` then detaches. detach() alone is reserved for durable cross-process handoff. Every agent-side example that tore down with session.close() now uses session.end(), and the connections concept describes the ClientSession/AgentSession teardown split correctly. Client-side ClientSession.close() is unchanged. StepEndReason is `complete` | `failed` | `cancelled`: a cancel arriving while a Step is open closes ai-step-end{cancelled} before the Run ends. The Steps concept, the AgentSession step-end reference (including the end() default derivation), and the wire-protocol step-reason header and ai-step-end rows now list all three. The Run-level run-reason (RunEndReason) is left as complete/cancelled/error. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

VeskeR added the review-app Create a Heroku review app label Jul 8, 2026

ably-ci temporarily deployed to ably-docs-ait-1073-wdk--rhvtnr July 8, 2026 12:14 Inactive

VeskeR changed the title ~~Ait 1073/wdk docs~~ [AIT-1073] Vercel WDK docs for AI Transport Jul 8, 2026

zknill force-pushed the durable-execution branch 4 times, most recently from b84eb55 to 7e2d018 Compare July 9, 2026 10:05

ably-ci temporarily deployed to ably-docs-ait-1073-wdk--rhvtnr July 9, 2026 10:35 Inactive

VeskeR force-pushed the AIT-1073/WDK-docs branch from bb215f4 to eb1c5e9 Compare July 9, 2026 10:53

ably-ci temporarily deployed to ably-docs-ait-1073-wdk--rhvtnr July 9, 2026 10:53 Inactive

VeskeR force-pushed the AIT-1073/WDK-docs branch from eb1c5e9 to 3d7d5f7 Compare July 9, 2026 10:54

ably-ci temporarily deployed to ably-docs-ait-1073-wdk--rhvtnr July 9, 2026 10:54 Inactive

VeskeR force-pushed the AIT-1073/WDK-docs branch from 3d7d5f7 to 6671812 Compare July 9, 2026 11:09

ably-ci temporarily deployed to ably-docs-ait-1073-wdk--rhvtnr July 9, 2026 11:09 Inactive

VeskeR force-pushed the AIT-1073/WDK-docs branch from 6671812 to b49bda1 Compare July 9, 2026 11:16

ably-ci temporarily deployed to ably-docs-ait-1073-wdk--rhvtnr July 9, 2026 11:17 Inactive

VeskeR marked this pull request as ready for review July 9, 2026 11:21

VeskeR requested a review from zknill July 9, 2026 11:21

VeskeR force-pushed the AIT-1073/WDK-docs branch from b49bda1 to 68846c6 Compare July 9, 2026 11:21

ably-ci temporarily deployed to ably-docs-ait-1073-wdk--rhvtnr July 9, 2026 11:21 Inactive

VeskeR force-pushed the AIT-1073/WDK-docs branch from 68846c6 to 9e99136 Compare July 9, 2026 11:59

ably-ci temporarily deployed to ably-docs-ait-1073-wdk--rhvtnr July 9, 2026 12:00 Inactive

zknill reviewed Jul 9, 2026

View reviewed changes

zknill force-pushed the durable-execution branch from 7e2d018 to f3bc49c Compare July 9, 2026 13:31

VeskeR mentioned this pull request Jul 9, 2026

Add Steps concept and durable execution docs for AI Transport #3459

Open

VeskeR force-pushed the AIT-1073/WDK-docs branch from 9e99136 to 288790d Compare July 9, 2026 16:01

ably-ci temporarily deployed to ably-docs-ait-1073-wdk--rhvtnr July 9, 2026 16:02 Inactive

VeskeR and others added 2 commits July 9, 2026 17:26

VeskeR force-pushed the AIT-1073/WDK-docs branch from 288790d to e7c34a5 Compare July 9, 2026 16:28

ably-ci deployed to ably-docs-ait-1073-wdk--rhvtnr July 9, 2026 16:28 View deployment


		A WDK step that produces agent output publishes it as a single Step, using the WDK step id as that Step's `stepId`. That is the join between the two systems: WDK's retryable unit and AI Transport's supersedable unit share one identifier.

		Read the id with [`getStepMetadata()`](https://useworkflow.dev/docs/api-reference/workflow/get-step-metadata) from the `workflow` package, inside the step. WDK step ids are stable across retries of the same step and unique across workflow runs, so they pass straight into `createStep` with no prefixing. This is where the composition is lighter than [Temporal's](/docs/ai-transport/frameworks/temporal), whose per-workflow activity ids need the `stepIdFor` helper to stay distinct on the channel.


		## Suspend and resume across workflows <a id="suspend-resume"/>

		A [suspend](/docs/ai-transport/features/human-in-the-loop) does not park the workflow to wait. The WDK step holding the Run calls `run.suspend()`, publishes `ai-run-suspend`, and returns; the workflow completes. When the client posts a continuation invocation (a tool result or an approval response), the agent route starts a fresh workflow. That workflow's `openRun` step calls `createRun` as usual; the SDK reads the existing `runId` the continuation's trigger names and publishes `ai-run-resume` rather than `ai-run-start`.


		The invocation is a poke and a pointer. Its HTTP body carries no session content, only the id of the channel event the client just published; the agent reads that event from the channel to learn what to do. One workflow run per HTTP POST, so continuations are new workflow runs on the same AI Transport `runId`, not resumes of the original workflow.

		WDK's own hooks can hold a workflow open while it waits for external input. The composition here ends the workflow instead, because the continuation arrives as a fresh POST from the AI Transport client and its trigger already points at the channel event that resumes the Run. The client stays identical to the [Vercel AI SDK integration](/docs/ai-transport/frameworks/vercel-ai-sdk-ui), with no workflow-aware code on the browser side.


		In local development the runtime stores run state in `.workflow-data/`; add that directory to `.gitignore`.

		## Define the workflow <a id="define-workflow"/>


		`runInference` adopts the Run and runs one model call. `stripToolExecutes` and `stopWhen: stepCountIs(1)` keep the Vercel AI SDK from running its own tool loop, so the model emits its tool-call parts and stops; the workflow drives the loop. `runInference` then routes the pending calls: a tool with a server `execute` becomes a `runTool` step; anything else suspends the Run for the client to answer. This guide uses a single server tool; the [framework page](/docs/ai-transport/frameworks/workflow-devkit#tool-calls) and [tool calling](/docs/ai-transport/features/tool-calling) cover client-executed and approval-gated tools.

		`awaitAttemptVisible` covers the one retry hazard. When WDK re-runs an inference, the superseding `ai-step-start` is not in the read model the instant it publishes, so reading the prompt too early would trail the failed attempt's half-streamed reply as an assistant prefill that real providers reject. The guard waits for the retry's attempt to reflect and returns at once on the first attempt.

Uh oh!

Conversation

VeskeR commented Jul 8, 2026 • edited by atlassian Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

coderabbitai Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

zknill left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

VeskeR commented Jul 8, 2026 •

edited by atlassian Bot

Loading

coderabbitai Bot commented Jul 8, 2026 •

edited

Loading