[Docs] Fix cookbook pattern for AI SDK#2099
Conversation
|
📊 Benchmark Results
workflow with no steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 1 step💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro | Express workflow with 10 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express workflow with 25 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 50 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro Promise.all with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro Promise.all with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Promise.all with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro Promise.race with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro | Express Promise.race with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) Promise.race with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 10 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 25 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express | Nitro workflow with 50 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 10 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 25 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 50 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express Stream Benchmarks (includes TTFB metrics)workflow with stream💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro | Express stream pipeline with 5 transform steps (1MB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro | Express 10 parallel streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) fan-out fan-in 10 streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
|
🧪 E2E Test Results✅ All tests passed Summary
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
✅ 📋 Other
|
027316f to
c661ac8
Compare
VaguelySerious
left a comment
There was a problem hiding this comment.
LGTM assuming this was tested, some wording nits
The AI SDK cookbook entry presented `streamText` inside a `"use step"` turn function with tools also marked `"use step"`. That implies tools are individually durable, but the `"use step"` directive is a no-op when called from another step — so tools run as plain inline functions inside `runTurn`, and the durability boundary is the entire turn. Changes: - Remove the `"use step"` directive from tool implementations in the workflow code sample and add an explanatory comment. - Update the frontmatter summary and intro paragraph to drop the inaccurate "tools remain durable steps" claim. - Add a "Tools are not individually durable" entry to Pitfalls with consequences and mitigations (idempotency or `DurableAgent`). - Add a `runTurn` durability-boundary bullet to "How it works". - Add a "Tool call durability" row to the `streamText` vs `DurableAgent` comparison table. - Fix two misleading Key APIs bullets that claimed tools wrap `"use step"` functions and that `"use step"` makes tool executions durable. Applied identically to both v4 and v5 cookbook entries. Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Peter Wielander <mittgfu@gmail.com> Signed-off-by: Karthik Kalyan <105607645+karthikscale3@users.noreply.github.com>
The callout and comparison table incorrectly claimed DurableAgent lacks stopWhen, structured output, and onStepFinish — update them to reflect the actual implementation and clarify when raw streamText() is still appropriate. Co-authored-by: Cursor <cursoragent@cursor.com>
Address review feedback: the inline comment should explain how tools run inside runTurn without referencing removed "use step" directives. Co-authored-by: Cursor <cursoragent@cursor.com>
|
No backport to This commit only modifies To override, re-run the Backport to stable workflow manually via |
Summary
The AI SDK cookbook entry (
docs/content/docs/v{4,5}/cookbook/integrations/ai-sdk.mdx) showsstreamTextinside a"use step"turn function with the example tools (lookupOrder,processRefund) also marked"use step". That presentation implies tool calls are individually durable, but per Workflows & Steps the"use step"directive is a no-op when called from another step. So in this pattern tools run as plain inline functions insiderunTurn, and the durability boundary is the entire turn — if anything in the turn throws, every tool call that already ran is replayed.This PR fixes the cookbook to reflect that reality and gives readers an explicit migration path (idempotent tools or
DurableAgent).Changes (applied identically to v4 and v5)
"use step"directive fromlookupOrderandprocessRefundin the workflow code sample, with an inline comment explaining why.summaryand intro paragraph: dropped the inaccurate "tools remain durable steps" claim; explicitly call out the per-turn durability boundary.runTurn, not the tool call.processRefund) can run multiple times if the turn retries.DurableAgent(each tool call becomes its own durable step).runTurndurability-boundary bullet to How it works.tool()no longer claims tools wrap"use step"functions / are replayed from the log."use step"is now described as applied torunTurn, not to "tool executions".DurableAgentguidance after verifying the implementation:DurableAgentlacksstopWhen, structured output, oronStepFinish— it reimplements the same agent loop and already supports those options.sliceUntilFinish).stopWhen/prepareStep;DurableAgentsupportsexperimental_outputand step callbacks (onStepFinish,onFinish, etc.); notedonChunkas the main gap.Test plan
/cookbook/integrations/ai-sdkpage on v4 and v5.#tools-are-not-individually-durable) resolves from the intro paragraph, How it works, and Key APIs cross-links.Made with Cursor