fix(docs): correct API usage in cookbook examples#1709
Merged
Conversation
|
Contributor
Contributor
🧪 E2E Test Results❌ Some tests failed Summary
❌ Failed Tests▲ Vercel Production (1 failed)fastify (1 failed):
🌍 Community Worlds (74 failed)mongodb (7 failed):
redis (7 failed):
turso (60 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. |
Contributor
📊 Benchmark Results
workflow with no steps💻 Local Development
▲ Production (Vercel)
workflow with 1 step💻 Local Development
▲ Production (Vercel)
workflow with 10 sequential steps💻 Local Development
▲ Production (Vercel)
workflow with 25 sequential steps💻 Local Development
▲ Production (Vercel)
workflow with 50 sequential steps💻 Local Development
▲ Production (Vercel)
Promise.all with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
Promise.all with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
Promise.all with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
Promise.race with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
Promise.race with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
Promise.race with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
workflow with 10 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
workflow with 25 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
workflow with 50 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
workflow with 10 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
workflow with 25 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
workflow with 50 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
Stream Benchmarks (includes TTFB metrics)workflow with stream💻 Local Development
▲ Production (Vercel)
stream pipeline with 5 transform steps (1MB)💻 Local Development
▲ Production (Vercel)
10 parallel streams (1MB each)💻 Local Development
▲ Production (Vercel)
fan-out fan-in 10 streams (1MB each)💻 Local Development
▲ Production (Vercel)
SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
❌ Some benchmark jobs failed:
Check the workflow run for details. |
Contributor
There was a problem hiding this comment.
Pull request overview
Updates cookbook documentation examples to match the current Workflow + AI SDK API surface, avoiding copy/paste code that would fail type-checking or at runtime.
Changes:
- Fixes API route examples to
await start(...)and return an AI SDKcreateUIMessageStreamResponse({ stream: run.readable })(withx-workflow-run-id). - Corrects mismatched/invalid API details (
run.runIdvsrun.id, webhook generics, status names,getWritable()capability table). - Updates the “stop workflow” pattern to use
prepareStepreturning{ toolChoice: "none" }and movesmaxStepstoagent.stream()options; removes an erroneous"use step"directive from a route handler.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| docs/content/docs/cookbook/integrations/chat-sdk.mdx | Fix route handlers to return createUIMessageStreamResponse using run.readable and run.runId. |
| docs/content/docs/cookbook/integrations/ai-sdk.mdx | Same streaming response pattern correction for start() integration example. |
| docs/content/docs/cookbook/common-patterns/child-workflows.mdx | Corrects non-final status comment to match WorkflowRunStatus (pending, running). |
| docs/content/docs/cookbook/agent-patterns/tool-orchestration.mdx | Fixes getWritable() availability table and removes invalid createWebhook<...>() generic usage. |
| docs/content/docs/cookbook/agent-patterns/stop-workflow.mdx | Replaces non-existent { stop: true } with { toolChoice: "none" }; moves maxSteps to stream() options; removes skip-typecheck comments. |
| docs/content/docs/cookbook/advanced/secure-credentials.mdx | Fixes returned run id property from run.id to run.runId. |
| docs/content/docs/cookbook/advanced/durable-objects.mdx | Removes incorrect "use step" directive from an API route snippet using resumeHook. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
VaguelySerious
approved these changes
Apr 13, 2026
TooTallNate
force-pushed
the
fix/docs-cookbook-api-correctness
branch
from
1dbfd1f to
cb0f131
Compare
Fix 9 issues across 6 cookbook files found during API audit:
- ai-sdk, chat-sdk: return start() returned Run not Response;
use createUIMessageStreamResponse with run.readable instead
- tool-orchestration: getWritable() is available at workflow level
(table was wrong); remove invalid generic on createWebhook()
- stop-workflow: replace non-existent { stop: true } prepareStep
return with { toolChoice: "none" }; move maxSteps from
DurableAgent constructor to stream() options
- durable-objects: remove erroneous "use step" from API route
- child-workflows: fix comment referencing non-existent statuses
(queued/starting -> pending/running)
…kbook - Fix @workflow/ai import path: providers/anthropic -> anthropic (serializable-steps, durable-objects) - Remove 'Bundle optimization with dynamic imports' section from serializable-steps — SWC plugin dead-code-eliminates unused imports from the workflow bundle automatically - Fix serialization claims in publishing-libraries: workflow supports Date, Map, Set, RegExp, BigInt, Uint8Array, URL, Error, and custom serde classes — not just JSON. Link to serialization reference. - Rewrite secrets guidance: encryption protects the event log, so this is a best practice not a hard requirement - Fix custom-serialization: class instances throw a serialization error (not silently lose prototype chain); remove incorrect 'Manual Registration for Library Authors' section (the build process discovers classes in node_modules); fix return new this -> return new WorkflowStorageClient; reorder Decision Guide to recommend custom serde as the default approach
…l guidance - Add [!code highlight] markers to key lines across all 23 cookbook files to emphasize important API calls and patterns - Remove step-as-factory comparison section from custom-serialization page — the page should focus solely on custom class serialization - Replace 'serde' shorthand with explicit 'custom class serialization' throughout for clarity - Rewrite credential guidance in publishing-libraries to present both patterns (env vars and passing explicitly) as equally valid when workflow encryption is enabled
TooTallNate
force-pushed
the
fix/docs-cookbook-api-correctness
branch
from
4de140e to
dec27a7
Compare
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
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
Audited all 23 cookbook documentation files against the real SDK API surface. Fixed incorrect APIs, removed aspirational/non-existent patterns, corrected inaccurate claims, and added
[!code highlight]markers throughout.API correctness fixes
return start()returnedRunnotResponse— usecreateUIMessageStreamResponse({ stream: run.readable })insteadgetWritable()is unavailable at workflow level; removed invalid generic oncreateWebhook(){ stop: true }prepareStep return with{ toolChoice: "none" }; movedmaxStepsfrom DurableAgent constructor tostream()options; removed@skip-typecheckcomments"use step"directive from API route handler"queued"/"starting"statuses@workflow/ai/providers/anthropic→@workflow/ai/anthropicContent corrections
Date,Map,Set,RegExp,BigInt,Uint8Array,URL,Error, and custom classes. Added link to serialization reference. Rewrote credential guidance to present env vars and explicit passing as equally valid (both safe with encryption enabled).return new this→return new WorkflowStorageClient. Replaced "serde" shorthand with explicit "custom class serialization" throughout.Code highlights
Added
[!code highlight]markers to key lines across all 23 cookbook files to draw attention to the important API calls and patterns in each example.