Add Steps concept and durable execution docs for AI Transport#3459
Open
zknill wants to merge 6 commits into
Open
Add Steps concept and durable execution docs for AI Transport#3459zknill wants to merge 6 commits into
zknill wants to merge 6 commits into
Conversation
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
VeskeR
reviewed
Jul 9, 2026
VeskeR
reviewed
Jul 9, 2026
VeskeR
reviewed
Jul 9, 2026
VeskeR
reviewed
Jul 9, 2026
VeskeR
reviewed
Jul 9, 2026
VeskeR
reviewed
Jul 9, 2026
VeskeR
reviewed
Jul 9, 2026
VeskeR
reviewed
Jul 9, 2026
VeskeR
reviewed
Jul 9, 2026
VeskeR
requested changes
Jul 9, 2026
Document the Step primitive and the durable-execution pattern that runs AI Transport agents inside a workflow engine. A Step is the re-attemptable unit of output within a Run; a retry under the same stepId supersedes the failed attempt on the channel rather than appending beside it, which is what makes a Run safe to execute across process boundaries and workflow retries. New pages: - concepts/steps: the Step model, lifecycle, and supersede-on-retry semantics, with a diagram. - features/durable-execution: adopt an in-flight Run from a fresh process, retry a failed Step under a stable stepId, close the Run on exhausted retries. - frameworks/temporal, getting-started/temporal: the reference workflow-engine integration, with the openRun / first-inference activity split and channel-routed cancels. - api/javascript/temporal: the stepIdFor helper. Extend agent-session API reference with adoptRun, createStep, detach, and RunStep. Add the ai-step-start / ai-step-end events and step headers to the wire protocol. Cross-link Steps and durable execution from the Runs, Sessions, tool-calling, reconnection, and going-to-production pages, and add nav entries. Promote durable execution to "Available today" on the roadmap.
A verbatim run-through of the Temporal getting-started guide in a fresh Next.js project surfaced compile and setup failures. Correct the guide and the pages it links to so a reader who follows it can build and run. - Pin the install command to the API's target release (@ably/ai-transport@^0.5.0) and the compatible AI SDK line (ai@^6, @ai-sdk/*@^3), and add deps the guide's own code uses but the command omitted: zod, tsx, jsonwebtoken, and the dev typings. - Add a "Set up the project" section: ESM package.json with the worker script, next.config serverExternalPackages for the Temporal client, and the required .env keys. - Type the guide's runInference activity (VercelAgentRun alias) so it compiles under strict TypeScript. - authentication: grant the conversations:* namespace so the token authorizes the channel clients actually open, define the referenced authenticateUser, type the handler, and guard ABLY_API_KEY. - vercel-ai-sdk: type the Providers component and Ably client state. - temporal API reference: drop the incidental "first activity is 1" sentence.
Apply review feedback from PR #3459, correcting statements that diverged from actual SDK behaviour and house conventions. - Correct the retry-supersede edge case: a retry supersedes the prior attempt the moment it calls step.start(), because supersede keys on the fresh higher-serial ai-step-start under the same stepId, not on any output the retry produces. - Qualify Realtime-client sharing as same-process only; Temporal and Vercel Workflow DevKit isolate each activity in its own process, and clarify that session objects must not be shared across activities. - Use key: process.env.ABLY_API_KEY instead of authUrl in server-side and agent code samples, where an API key is the correct credential. - Reference session.end()/session.detach() rather than the non-existent session.close() on AgentSession. - Add 'cancelled' to the terminal StepEndReason list. - Use "realtime" (one word) per house style. - Align the AI Transport SDK version to the two-part '0.5' format used by sibling entries in languageData.ts.
Clarify the auth guidance so agents stop rewriting valid server-side code, and add the "realtime" spelling rule that was previously only enforced by hand. - Principle 17 now states the client/server split explicitly: browser code uses authUrl, but server-side and agent code (activities, agent routes, workers) must use key: process.env.ABLY_API_KEY. An authUrl in a server snippet is a bug, not a pattern to preserve. - Note why the client-key verification grep passes process.env-sourced keys, so the exception is visible at the check itself. - Add "realtime" (one word) as an enforced spelling, with a sweep grep in the verification block.
VeskeR
approved these changes
Jul 9, 2026
Contributor
There was a problem hiding this comment.
LGTM, there are still a couple of outdated AgentSession.close() references and StepEndReason not mentioning cancelled - I'm going to address it in my #3463 (see AI Transport docs: align session teardown and step end reasons with SDK commit)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Document the Step primitive and the durable-execution pattern that runs AI Transport agents inside a workflow engine. A Step is the re-attemptable unit of output within a Run; a retry under the same stepId supersedes the failed attempt on the channel rather than appending beside it, which is what makes a Run safe to execute across process boundaries and workflow retries.
New pages:
concepts/steps: the Step model, lifecycle, and supersede-on-retry semantics, with a diagram.
features/durable-execution: adopt an in-flight Run from a fresh process, retry a failed Step under a stable stepId, close the Run on exhausted retries.
frameworks/temporal, getting-started/temporal: the reference workflow-engine integration, with the openRun / first-inference activity split and channel-routed cancels.
api/javascript/temporal: the stepIdFor helper.
Extend agent-session API reference with adoptRun, createStep, detach, and RunStep. Add the ai-step-start / ai-step-end events and step headers to the wire protocol. Cross-link Steps and durable execution from the Runs, Sessions, tool-calling, reconnection, and going-to-production pages, and add nav entries. Promote durable execution to "Available today" on the roadmap.