docs: Add durable streaming migration guide, FAQ, and content enhancements#1323
Open
johnlindquist wants to merge 3 commits intomainfrom
Open
docs: Add durable streaming migration guide, FAQ, and content enhancements#1323johnlindquist wants to merge 3 commits intomainfrom
johnlindquist wants to merge 3 commits intomainfrom
Conversation
P0: New content - Add migration guide: ephemeral to durable streaming (foundations/) - Add FAQ section with troubleshooting, migration, compatibility, and advanced usage questions - Wire both into site navigation via meta.json P1: Enhance existing docs - streaming.mdx: Add "Why durable streaming" section explaining the durability model vs ephemeral connections - resumable-streams.mdx: Add common gotchas for WorkflowChatTransport request body customization and local debugging tips - local-world.mdx: Add "Why local development matters" section on debugging silent failures with the step debugger - observability/index.mdx: Add debugging walkthrough for silent step failures using the Web UI
|
Contributor
Contributor
📊 Benchmark Results
workflow with no steps💻 Local Development
workflow with 1 step💻 Local Development
workflow with 10 sequential steps💻 Local Development
workflow with 25 sequential steps💻 Local Development
workflow with 50 sequential steps💻 Local Development
Promise.all with 10 concurrent steps💻 Local Development
Promise.all with 25 concurrent steps💻 Local Development
Promise.all with 50 concurrent steps💻 Local Development
Promise.race with 10 concurrent steps💻 Local Development
Promise.race with 25 concurrent steps💻 Local Development
Promise.race with 50 concurrent steps💻 Local Development
Stream Benchmarks (includes TTFB metrics)workflow with stream💻 Local Development
SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
|
Contributor
🧪 E2E Test Results❌ Some tests failed Summary
❌ Failed Tests🐘 Local Postgres (1 failed)hono-stable (1 failed):
🌍 Community Worlds (56 failed)mongodb (3 failed):
redis (2 failed):
turso (51 failed):
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
❌ 🐘 Local Postgres
✅ 🪟 Windows
❌ 🌍 Community Worlds
✅ 📋 Other
❌ Some E2E test jobs failed:
Check the workflow run for details. |
Use DurableAgent string model IDs ("anthropic/claude-haiku-4.5") instead
of AI SDK provider functions (openai("gpt-4o")) in new docs content.
- Use workflow-level getWritable() instead of wrapping in a step - DurableAgent internally creates steps, no manual "use step" needed - Use ModelMessage type with convertToModelMessages - Split workflow definition and route handler into separate files matching the pattern in ai/index.mdx
Member
VaguelySerious
left a comment
VaguelySerious
left a comment
There was a problem hiding this comment.
Overall LGTM, some preliminary comments, will let @pranaygp comment before approving
| <Callout type="warn"> | ||
| **Request body customization** | ||
|
|
||
| `WorkflowChatTransport` shapes its POST body differently than the default AI SDK transport. If you need custom fields in the request body (such as a model selector, temperature, or session metadata), use the `prepareSendMessagesRequest` hook to override the request: |
Member
There was a problem hiding this comment.
Should ask an agent whether this is still the case on main, we made some minor changes to this in the recent past
| npx workflow inspect runs --web | ||
| ``` | ||
|
|
||
| Check that the run is still active and that the `startIndex` in the reconnection request matches the last chunk the client received. The Web UI shows the full step trace, including stream chunk counts. |
Member
There was a problem hiding this comment.
still active
The run doesn't need to be active to connect to a stream
|
|
||
| ### My reconnection endpoint returns an empty stream. What is wrong? | ||
|
|
||
| Check that the `runId` in the reconnection URL matches the run you want to resume. Verify the run is still active by inspecting it in the Web UI or CLI: |
Member
There was a problem hiding this comment.
still active
The run doesn't need to be active to connect to a stream
|
|
||
| ### What happens to in-progress runs when I redeploy? | ||
|
|
||
| This depends on the [World](/docs/deploying) you are using. With the [Vercel World](/docs/deploying/world/vercel-world), runs are backed by durable infrastructure and survive deployments. With the [Local World](/docs/deploying/world/local-world), the in-memory queue does not persist across server restarts, so in-progress runs will not resume. |
Member
There was a problem hiding this comment.
Suggested change
| This depends on the [World](/docs/deploying) you are using. With the [Vercel World](/docs/deploying/world/vercel-world), runs are backed by durable infrastructure and survive deployments. With the [Local World](/docs/deploying/world/local-world), the in-memory queue does not persist across server restarts, so in-progress runs will not resume. | |
| This depends on the [World](/docs/deploying) you are using. With the [Vercel World](/docs/deploying/world/vercel-world), runs continue to run on their original deployment, so deploying comes without risk. With the [Local World](/docs/deploying/world/local-world), the in-memory queue does not persist across server restarts, so in-progress runs will not resume. |
| @@ -0,0 +1,264 @@ | |||
| --- | |||
| title: Migrate from Ephemeral to Durable Streaming | |||
Member
There was a problem hiding this comment.
This guide is a close copy of the Durable Agent guide I wrote a while back. I think it's nice to have a more focused example like here, though unsure if the duplication is worth it, vs. linking to the durable agent guide in other areas
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
2 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.
Summary
foundations/migrate-ephemeral-streaming.mdx) — Step-by-step guide for moving from ephemeral streaming to durable streaming with Workflow DevKit. Covers wrapping generation in a workflow step, exposingrunId, swapping inWorkflowChatTransport, and common gotchas.faq/index.mdx) — 13 questions covering troubleshooting (silent step failures,WorkflowChatTransportbody shape), migration (incremental adoption, what you get after migrating), compatibility (local dev, AI SDK, frameworks,DurableAgent), and advanced usage (reconnection flow, user input hooks, redeploy behavior, multiple clients).foundations/streaming.mdx— Added "Why durable streaming" section explaining the durability model vs ephemeral connections, with links to migration guide and resumable streams.ai/resumable-streams.mdx— Added common gotchas callout forWorkflowChatTransportrequest body customization viaprepareSendMessagesRequest, and local debugging tips using the Web UI.deploying/world/local-world.mdx— Added "Why local development matters" section highlighting the step debugger for catching silent failures during development.observability/index.mdx— Added debugging walkthrough for silent step failures using the Web UI, with step-by-step instructions.Context
Based on real developer feedback from a Workflow migration (async-recipes app). The feedback identified these gaps:
WorkflowChatTransportgotchas not documented near usage examplesTest plan
npm run dev)