Skip to content

[Docs] Fix cookbook pattern for AI SDK#2099

Merged
karthikscale3 merged 4 commits into
mainfrom
karthik/cookbook-ai-sdk-tools-not-durable
May 25, 2026
Merged

[Docs] Fix cookbook pattern for AI SDK#2099
karthikscale3 merged 4 commits into
mainfrom
karthik/cookbook-ai-sdk-tools-not-durable

Conversation

@karthikscale3
Copy link
Copy Markdown
Contributor

@karthikscale3 karthikscale3 commented May 22, 2026

Summary

The AI SDK cookbook entry (docs/content/docs/v{4,5}/cookbook/integrations/ai-sdk.mdx) shows streamText inside 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 inside runTurn, 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)

  • Removed the "use step" directive from lookupOrder and processRefund in the workflow code sample, with an inline comment explaining why.
  • Updated the frontmatter summary and intro paragraph: dropped the inaccurate "tools remain durable steps" claim; explicitly call out the per-turn durability boundary.
  • Added a new Tools are not individually durable entry to Pitfalls covering:
    • The retry unit is runTurn, not the tool call.
    • A side-effectful tool (e.g. processRefund) can run multiple times if the turn retries.
    • Mitigations: idempotent tool implementations, or DurableAgent (each tool call becomes its own durable step).
  • Added a runTurn durability-boundary bullet to How it works.
  • Added a Tool call durability row to the streamText vs DurableAgent table.
  • Rewrote two misleading Key APIs bullets:
    • tool() no longer claims tools wrap "use step" functions / are replayed from the log.
    • "use step" is now described as applied to runTurn, not to "tool executions".
  • Corrected outdated DurableAgent guidance after verifying the implementation:
    • Callout no longer claims DurableAgent lacks stopWhen, structured output, or onStepFinish — it reimplements the same agent loop and already supports those options.
    • Rewrote When to use streamText directly to focus on the raw AI SDK API, per-turn durability boundaries, and custom multi-turn orchestration (hook loops, sliceUntilFinish).
    • Updated the streamText vs DurableAgent comparison table: both support stopWhen/prepareStep; DurableAgent supports experimental_output and step callbacks (onStepFinish, onFinish, etc.); noted onChunk as the main gap.

Test plan

  • Visual check of the rendered /cookbook/integrations/ai-sdk page on v4 and v5.
  • Confirm the new in-page anchor (#tools-are-not-individually-durable) resolves from the intro paragraph, How it works, and Key APIs cross-links.
  • Confirm the code sample still typechecks in the docs typecheck pipeline.

Made with Cursor

@karthikscale3 karthikscale3 requested a review from a team as a code owner May 22, 2026 23:54
@changeset-bot
Copy link
Copy Markdown

changeset-bot Bot commented May 22, 2026

⚠️ No Changeset found

Latest commit: 3270975

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 22, 2026

📊 Benchmark Results

📈 Comparing against baseline from main branch. Green 🟢 = faster, Red 🔺 = slower.

workflow with no steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Express 0.031s (-30.5% 🟢) 1.006s (~) 0.975s 10 1.00x
💻 Local Nitro 0.033s (-23.7% 🟢) 1.006s (~) 0.973s 10 1.07x
🐘 Postgres Nitro 0.042s (-55.7% 🟢) 1.010s (-3.1%) 0.968s 10 1.37x
💻 Local Next.js (Turbopack) 0.048s 1.006s 0.958s 10 1.55x
🐘 Postgres Express 0.053s (-8.1% 🟢) 1.014s (~) 0.960s 10 1.73x
🐘 Postgres Next.js (Turbopack) 0.056s 1.011s 0.955s 10 1.82x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 0.279s (-31.9% 🟢) 2.044s (-18.6% 🟢) 1.764s 10 1.00x
▲ Vercel Express 0.296s (+25.6% 🔺) 2.469s (+15.6% 🔺) 2.173s 10 1.06x
▲ Vercel Next.js (Turbopack) 0.304s (+21.0% 🔺) 2.151s (-7.8% 🟢) 1.847s 10 1.09x

🔍 Observability: Nitro | Express | Next.js (Turbopack)

workflow with 1 step

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Express 1.075s (-4.4%) 2.006s (~) 0.931s 10 1.00x
💻 Local Nitro 1.076s (-4.9%) 2.006s (~) 0.930s 10 1.00x
🐘 Postgres Nitro 1.079s (-5.4% 🟢) 2.008s (~) 0.929s 10 1.00x
🐘 Postgres Express 1.083s (-5.5% 🟢) 2.009s (~) 0.926s 10 1.01x
💻 Local Next.js (Turbopack) 1.112s 2.006s 0.895s 10 1.03x
🐘 Postgres Next.js (Turbopack) 1.120s 2.009s 0.890s 10 1.04x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Next.js (Turbopack) 1.585s (-22.1% 🟢) 3.301s (-13.8% 🟢) 1.716s 10 1.00x
▲ Vercel Nitro 1.677s (-56.9% 🟢) 3.257s (-44.9% 🟢) 1.579s 10 1.06x
▲ Vercel Express 1.731s (-7.7% 🟢) 3.615s (-5.1% 🟢) 1.884s 10 1.09x

🔍 Observability: Next.js (Turbopack) | Nitro | Express

workflow with 10 sequential steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 10.423s (-4.1%) 11.015s (~) 0.592s 3 1.00x
💻 Local Express 10.423s (-4.6%) 11.021s (~) 0.598s 3 1.00x
💻 Local Nitro 10.425s (-4.8%) 11.021s (~) 0.596s 3 1.00x
🐘 Postgres Express 10.445s (-4.7%) 11.017s (~) 0.572s 3 1.00x
💻 Local Next.js (Turbopack) 10.652s 11.020s 0.367s 3 1.02x
🐘 Postgres Next.js (Turbopack) 10.694s 11.020s 0.326s 3 1.03x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 13.232s (-44.2% 🟢) 15.258s (-39.2% 🟢) 2.026s 2 1.00x
▲ Vercel Next.js (Turbopack) 13.769s (-20.5% 🟢) 15.278s (-21.2% 🟢) 1.509s 2 1.04x
▲ Vercel Express 16.197s (-4.6%) 17.973s (-10.2% 🟢) 1.777s 2 1.22x

🔍 Observability: Nitro | Next.js (Turbopack) | Express

workflow with 25 sequential steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 13.457s (-7.8% 🟢) 14.018s (-6.7% 🟢) 0.561s 5 1.00x
🐘 Postgres Express 13.492s (-7.5% 🟢) 14.017s (-6.7% 🟢) 0.525s 5 1.00x
💻 Local Express 13.498s (-9.8% 🟢) 14.027s (-6.7% 🟢) 0.529s 5 1.00x
💻 Local Nitro 13.506s (-10.3% 🟢) 14.029s (-12.5% 🟢) 0.523s 5 1.00x
💻 Local Next.js (Turbopack) 14.038s 15.029s 0.991s 4 1.04x
🐘 Postgres Next.js (Turbopack) 14.121s 15.019s 0.898s 4 1.05x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 21.119s (-67.2% 🟢) 22.768s (-65.8% 🟢) 1.649s 3 1.00x
▲ Vercel Express 21.128s (-58.0% 🟢) 22.810s (-56.6% 🟢) 1.683s 3 1.00x
▲ Vercel Next.js (Turbopack) 21.868s (-58.4% 🟢) 22.948s (-58.0% 🟢) 1.080s 3 1.04x

🔍 Observability: Nitro | Express | Next.js (Turbopack)

workflow with 50 sequential steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Express 11.935s (-28.1% 🟢) 12.022s (-29.4% 🟢) 0.087s 8 1.00x
🐘 Postgres Express 11.955s (-14.7% 🟢) 12.142s (-16.8% 🟢) 0.187s 8 1.00x
💻 Local Nitro 11.982s (-28.6% 🟢) 12.147s (-28.7% 🟢) 0.165s 8 1.00x
🐘 Postgres Nitro 11.987s (-14.2% 🟢) 12.393s (-13.4% 🟢) 0.406s 8 1.00x
💻 Local Next.js (Turbopack) 12.945s 13.023s 0.078s 7 1.08x
🐘 Postgres Next.js (Turbopack) 13.222s 14.015s 0.794s 7 1.11x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 32.014s (-73.6% 🟢) 33.895s (-72.6% 🟢) 1.881s 3 1.00x
▲ Vercel Next.js (Turbopack) 32.210s (-91.8% 🟢) 33.857s (-91.4% 🟢) 1.647s 3 1.01x
▲ Vercel Nitro 32.225s (-92.4% 🟢) 34.212s (-91.9% 🟢) 1.987s 3 1.01x

🔍 Observability: Express | Next.js (Turbopack) | Nitro

Promise.all with 10 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 1.141s (-10.5% 🟢) 2.006s (~) 0.865s 15 1.00x
🐘 Postgres Express 1.150s (-8.7% 🟢) 2.007s (~) 0.857s 15 1.01x
💻 Local Express 1.176s (-21.0% 🟢) 2.007s (~) 0.831s 15 1.03x
💻 Local Nitro 1.185s (-27.4% 🟢) 2.007s (-3.2%) 0.822s 15 1.04x
🐘 Postgres Next.js (Turbopack) 1.198s 2.007s 0.809s 15 1.05x
💻 Local Next.js (Turbopack) 1.279s 2.006s 0.728s 15 1.12x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 2.551s (-10.8% 🟢) 4.135s (-10.6% 🟢) 1.584s 8 1.00x
▲ Vercel Next.js (Turbopack) 2.592s (-23.7% 🟢) 4.220s (-14.5% 🟢) 1.628s 8 1.02x
▲ Vercel Nitro 2.674s (-5.1% 🟢) 4.354s (+0.7%) 1.680s 7 1.05x

🔍 Observability: Express | Next.js (Turbopack) | Nitro

Promise.all with 25 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 1.191s (-49.3% 🟢) 2.006s (-33.3% 🟢) 0.815s 15 1.00x
🐘 Postgres Express 1.212s (-48.7% 🟢) 2.007s (-33.3% 🟢) 0.796s 15 1.02x
🐘 Postgres Next.js (Turbopack) 1.339s 2.006s 0.667s 15 1.12x
💻 Local Nitro 1.771s (-43.7% 🟢) 2.006s (-48.4% 🟢) 0.236s 15 1.49x
💻 Local Next.js (Turbopack) 1.799s 2.073s 0.274s 15 1.51x
💻 Local Express 1.891s (-35.9% 🟢) 2.142s (-38.0% 🟢) 0.250s 15 1.59x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 3.385s (-16.5% 🟢) 4.730s (-20.1% 🟢) 1.345s 7 1.00x
▲ Vercel Express 3.711s (+2.5%) 5.633s (+10.2% 🔺) 1.922s 6 1.10x
▲ Vercel Next.js (Turbopack) 4.474s (-37.0% 🟢) 5.883s (-33.9% 🟢) 1.408s 6 1.32x

🔍 Observability: Nitro | Express | Next.js (Turbopack)

Promise.all with 50 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 1.301s (-62.6% 🟢) 2.007s (-49.9% 🟢) 0.707s 15 1.00x
🐘 Postgres Express 1.323s (-62.0% 🟢) 2.007s (-49.9% 🟢) 0.684s 15 1.02x
🐘 Postgres Next.js (Turbopack) 1.595s 2.007s 0.412s 15 1.23x
💻 Local Next.js (Turbopack) 4.947s 5.344s 0.397s 6 3.80x
💻 Local Nitro 5.412s (-35.2% 🟢) 5.847s (-35.2% 🟢) 0.435s 6 4.16x
💻 Local Express 5.621s (-32.6% 🟢) 6.013s (-33.4% 🟢) 0.391s 5 4.32x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 5.258s (+24.0% 🔺) 7.088s (+15.7% 🔺) 1.831s 5 1.00x
▲ Vercel Next.js (Turbopack) 6.447s (-27.7% 🟢) 7.992s (-27.1% 🟢) 1.544s 4 1.23x
▲ Vercel Nitro 6.804s (+93.0% 🔺) 8.588s (+55.2% 🔺) 1.784s 4 1.29x

🔍 Observability: Express | Next.js (Turbopack) | Nitro

Promise.race with 10 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 1.131s (-10.0% 🟢) 2.007s (~) 0.876s 15 1.00x
🐘 Postgres Express 1.158s (-7.9% 🟢) 2.008s (~) 0.850s 15 1.02x
🐘 Postgres Next.js (Turbopack) 1.198s 2.006s 0.808s 15 1.06x
💻 Local Next.js (Turbopack) 1.303s 2.006s 0.703s 15 1.15x
💻 Local Nitro 1.410s (-24.4% 🟢) 2.006s (-14.3% 🟢) 0.595s 15 1.25x
💻 Local Express 1.460s (-22.9% 🟢) 2.006s (-15.1% 🟢) 0.546s 15 1.29x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Next.js (Turbopack) 2.421s (-17.4% 🟢) 3.689s (-20.5% 🟢) 1.268s 9 1.00x
▲ Vercel Nitro 2.507s (+2.0%) 3.960s (-5.0% 🟢) 1.452s 8 1.04x
▲ Vercel Express 2.626s (+1.7%) 4.498s (+3.4%) 1.872s 7 1.08x

🔍 Observability: Next.js (Turbopack) | Nitro | Express

Promise.race with 25 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 1.182s (-49.5% 🟢) 2.007s (-33.3% 🟢) 0.825s 15 1.00x
🐘 Postgres Express 1.212s (-48.2% 🟢) 2.009s (-33.3% 🟢) 0.797s 15 1.03x
🐘 Postgres Next.js (Turbopack) 1.353s 2.008s 0.654s 15 1.14x
💻 Local Next.js (Turbopack) 2.024s 2.674s 0.650s 12 1.71x
💻 Local Express 2.077s (-33.7% 🟢) 2.508s (-33.3% 🟢) 0.431s 12 1.76x
💻 Local Nitro 2.081s (-32.1% 🟢) 2.507s (-35.5% 🟢) 0.427s 12 1.76x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 3.363s (+5.3% 🔺) 5.109s (+6.6% 🔺) 1.746s 6 1.00x
▲ Vercel Nitro 3.543s (+9.6% 🔺) 4.722s (-7.0% 🟢) 1.179s 7 1.05x
▲ Vercel Next.js (Turbopack) 3.827s (+21.8% 🔺) 5.241s (+15.9% 🔺) 1.414s 6 1.14x

🔍 Observability: Express | Nitro | Next.js (Turbopack)

Promise.race with 50 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 1.288s (-63.0% 🟢) 2.007s (-49.9% 🟢) 0.719s 15 1.00x
🐘 Postgres Express 1.318s (-62.3% 🟢) 2.008s (-49.9% 🟢) 0.690s 15 1.02x
🐘 Postgres Next.js (Turbopack) 1.603s 2.010s 0.408s 15 1.24x
💻 Local Next.js (Turbopack) 5.253s 6.013s 0.760s 5 4.08x
💻 Local Nitro 5.567s (-39.1% 🟢) 6.014s (-40.0% 🟢) 0.447s 5 4.32x
💻 Local Express 6.097s (-30.7% 🟢) 6.415s (-30.8% 🟢) 0.318s 5 4.73x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 5.083s (-20.8% 🟢) 6.959s (-14.9% 🟢) 1.876s 5 1.00x
▲ Vercel Nitro 5.184s (+1.8%) 7.046s (+3.4%) 1.862s 5 1.02x
▲ Vercel Next.js (Turbopack) 5.777s (-14.5% 🟢) 7.101s (-16.9% 🟢) 1.323s 5 1.14x

🔍 Observability: Express | Nitro | Next.js (Turbopack)

workflow with 10 sequential data payload steps (10KB)

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 0.442s (-46.1% 🟢) 1.006s (~) 0.564s 60 1.00x
💻 Local Express 0.484s (-50.8% 🟢) 1.004s (-6.7% 🟢) 0.520s 60 1.10x
🐘 Postgres Express 0.486s (-42.1% 🟢) 1.024s (~) 0.538s 59 1.10x
💻 Local Nitro 0.525s (-46.5% 🟢) 1.005s (-8.1% 🟢) 0.480s 60 1.19x
🐘 Postgres Next.js (Turbopack) 0.682s 1.006s 0.325s 60 1.54x
💻 Local Next.js (Turbopack) 0.705s 1.005s 0.300s 60 1.59x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 4.886s (-74.3% 🟢) 6.422s (-69.9% 🟢) 1.536s 10 1.00x
▲ Vercel Nitro 5.443s (-75.3% 🟢) 6.976s (-71.0% 🟢) 1.533s 9 1.11x
▲ Vercel Next.js (Turbopack) 5.491s (-62.1% 🟢) 6.854s (-57.4% 🟢) 1.362s 9 1.12x

🔍 Observability: Express | Nitro | Next.js (Turbopack)

workflow with 25 sequential data payload steps (10KB)

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Express 1.031s (-47.8% 🟢) 1.586s (-29.8% 🟢) 0.555s 57 1.00x
🐘 Postgres Nitro 1.053s (-45.4% 🟢) 1.603s (-23.7% 🟢) 0.550s 57 1.02x
💻 Local Express 1.209s (-59.9% 🟢) 2.006s (-44.1% 🟢) 0.797s 45 1.17x
💻 Local Nitro 1.225s (-59.6% 🟢) 2.006s (-46.6% 🟢) 0.781s 45 1.19x
🐘 Postgres Next.js (Turbopack) 1.631s 2.009s 0.377s 45 1.58x
💻 Local Next.js (Turbopack) 1.767s 2.006s 0.239s 45 1.71x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Next.js (Turbopack) 13.045s (-73.8% 🟢) 14.636s (-71.7% 🟢) 1.592s 7 1.00x
▲ Vercel Express 13.474s (-61.0% 🟢) 15.249s (-58.6% 🟢) 1.776s 6 1.03x
▲ Vercel Nitro 13.618s (-65.5% 🟢) 15.326s (-62.9% 🟢) 1.708s 6 1.04x

🔍 Observability: Next.js (Turbopack) | Express | Nitro

workflow with 50 sequential data payload steps (10KB)

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 2.009s (-51.0% 🟢) 2.407s (-47.7% 🟢) 0.398s 50 1.00x
🐘 Postgres Express 2.175s (-45.5% 🟢) 2.758s (-36.9% 🟢) 0.583s 44 1.08x
💻 Local Express 2.767s (-70.0% 🟢) 3.032s (-69.7% 🟢) 0.265s 40 1.38x
💻 Local Nitro 2.796s (-69.9% 🟢) 3.033s (-69.7% 🟢) 0.237s 40 1.39x
🐘 Postgres Next.js (Turbopack) 3.182s 4.009s 0.827s 30 1.58x
💻 Local Next.js (Turbopack) 3.712s 4.008s 0.296s 30 1.85x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 27.669s (-78.7% 🟢) 29.488s (-77.7% 🟢) 1.819s 5 1.00x
▲ Vercel Nitro 29.741s (-69.3% 🟢) 31.477s (-68.0% 🟢) 1.736s 4 1.07x
▲ Vercel Next.js (Turbopack) 31.048s (-71.0% 🟢) 32.776s (-69.9% 🟢) 1.727s 4 1.12x

🔍 Observability: Express | Nitro | Next.js (Turbopack)

workflow with 10 concurrent data payload steps (10KB)

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 0.163s (-42.6% 🟢) 1.005s (~) 0.843s 60 1.00x
🐘 Postgres Express 0.171s (-39.4% 🟢) 1.006s (~) 0.835s 60 1.05x
🐘 Postgres Next.js (Turbopack) 0.229s 1.006s 0.777s 60 1.41x
💻 Local Nitro 0.412s (-31.8% 🟢) 1.004s (-1.7%) 0.592s 60 2.54x
💻 Local Express 0.419s (-25.2% 🟢) 1.004s (~) 0.585s 60 2.58x
💻 Local Next.js (Turbopack) 0.510s 1.004s 0.494s 60 3.13x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 2.414s (+45.3% 🔺) 4.251s (+26.9% 🔺) 1.838s 16 1.00x
▲ Vercel Express 2.559s (+30.9% 🔺) 4.101s (+12.7% 🔺) 1.542s 15 1.06x
▲ Vercel Next.js (Turbopack) 2.607s (+28.9% 🔺) 3.926s (+3.5%) 1.320s 16 1.08x

🔍 Observability: Nitro | Express | Next.js (Turbopack)

workflow with 25 concurrent data payload steps (10KB)

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 0.282s (-43.3% 🟢) 1.005s (~) 0.724s 90 1.00x
🐘 Postgres Express 0.306s (-39.9% 🟢) 1.007s (~) 0.701s 90 1.09x
🐘 Postgres Next.js (Turbopack) 0.449s 1.007s 0.558s 90 1.59x
💻 Local Nitro 2.140s (-15.7% 🟢) 2.852s (-5.2% 🟢) 0.712s 32 7.60x
💻 Local Express 2.162s (-14.0% 🟢) 2.943s (-2.2%) 0.781s 31 7.68x
💻 Local Next.js (Turbopack) 2.219s 2.944s 0.726s 31 7.88x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 4.743s (+55.7% 🔺) 6.348s (+32.0% 🔺) 1.604s 15 1.00x
▲ Vercel Nitro 5.316s (+64.8% 🔺) 6.877s (+42.6% 🔺) 1.561s 14 1.12x
▲ Vercel Next.js (Turbopack) 5.355s (+51.5% 🔺) 6.768s (+30.3% 🔺) 1.413s 14 1.13x

🔍 Observability: Express | Nitro | Next.js (Turbopack)

workflow with 50 concurrent data payload steps (10KB)

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 0.557s (-29.5% 🟢) 1.005s (~) 0.448s 120 1.00x
🐘 Postgres Express 0.626s (-23.6% 🟢) 1.006s (-1.1%) 0.380s 120 1.12x
🐘 Postgres Next.js (Turbopack) 0.919s 1.207s 0.288s 100 1.65x
💻 Local Express 10.512s (-6.1% 🟢) 11.119s (-6.9% 🟢) 0.607s 11 18.87x
💻 Local Nitro 10.566s (-5.6% 🟢) 11.119s (-4.7%) 0.553s 11 18.97x
💻 Local Next.js (Turbopack) 10.761s 11.481s 0.720s 11 19.32x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 14.165s (+83.4% 🔺) 15.767s (+67.7% 🔺) 1.603s 9 1.00x
▲ Vercel Next.js (Turbopack) 14.811s (+43.4% 🔺) 16.301s (+32.7% 🔺) 1.490s 8 1.05x
▲ Vercel Express 16.474s (+122.0% 🔺) 18.379s (+98.8% 🔺) 1.905s 7 1.16x

🔍 Observability: Nitro | Next.js (Turbopack) | Express

Stream Benchmarks (includes TTFB metrics)
workflow with stream

💻 Local Development

World Framework Workflow Time TTFB Slurp Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 1.135s (+453.5% 🔺) 2.002s (+100.3% 🔺) 0.001s (-13.3% 🟢) 2.009s (+98.7% 🔺) 0.874s 10 1.00x
💻 Local Express 1.135s (+470.1% 🔺) 2.006s (+99.7% 🔺) 0.012s (+2.5%) 2.020s (+98.5% 🔺) 0.885s 10 1.00x
🐘 Postgres Express 1.141s (+456.3% 🔺) 2.001s (+100.4% 🔺) 0.001s (-25.0% 🟢) 2.011s (+98.9% 🔺) 0.871s 10 1.01x
💻 Local Nitro 1.142s (+434.4% 🔺) 2.005s (+99.6% 🔺) 0.013s (+0.8%) 2.020s (+98.3% 🔺) 0.878s 10 1.01x
💻 Local Next.js (Turbopack) 1.170s 2.004s 0.012s 2.019s 0.849s 10 1.03x
🐘 Postgres Next.js (Turbopack) 1.195s 2.002s 0.002s 2.011s 0.815s 10 1.05x

▲ Production (Vercel)

World Framework Workflow Time TTFB Slurp Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Next.js (Turbopack) 2.151s (-68.6% 🟢) 2.881s (-66.7% 🟢) 2.305s (+264.7% 🔺) 5.547s (-43.3% 🟢) 3.397s 10 1.00x
▲ Vercel Nitro 2.196s (-42.7% 🟢) 2.985s (-43.4% 🟢) 2.267s (+205.5% 🔺) 5.704s (-12.0% 🟢) 3.508s 10 1.02x
▲ Vercel Express 2.949s (+17.7% 🔺) 4.011s (-1.9%) 14.047s (+1362.0% 🔺) 18.574s (+232.2% 🔺) 15.625s 10 1.37x

🔍 Observability: Next.js (Turbopack) | Nitro | Express

stream pipeline with 5 transform steps (1MB)

💻 Local Development

World Framework Workflow Time TTFB Slurp Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 1.498s (+140.0% 🔺) 2.007s (+99.3% 🔺) 0.003s (-19.4% 🟢) 2.022s (+97.8% 🔺) 0.524s 30 1.00x
🐘 Postgres Express 1.520s (+141.3% 🔺) 2.006s (+99.3% 🔺) 0.004s (+4.4%) 2.025s (+98.0% 🔺) 0.505s 30 1.01x
💻 Local Nitro 1.555s (+85.4% 🔺) 2.013s (+98.9% 🔺) 0.011s (+16.0% 🔺) 2.026s (+81.5% 🔺) 0.471s 30 1.04x
💻 Local Next.js (Turbopack) 1.657s 2.014s 0.010s 2.026s 0.369s 30 1.11x
🐘 Postgres Next.js (Turbopack) 1.712s 2.010s 0.004s 2.028s 0.316s 30 1.14x
💻 Local Express 1.739s (+129.7% 🔺) 2.012s (+95.6% 🔺) 0.011s (+13.9% 🔺) 2.198s (+111.4% 🔺) 0.459s 29 1.16x

▲ Production (Vercel)

World Framework Workflow Time TTFB Slurp Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Next.js (Turbopack) 6.010s (-64.5% 🟢) 6.776s (-62.9% 🟢) 0.173s (-18.3% 🟢) 7.342s (-61.2% 🟢) 1.331s 9 1.00x
▲ Vercel Nitro 6.068s (-79.4% 🟢) 7.063s (-77.1% 🟢) 0.275s (+145.2% 🔺) 7.733s (-75.7% 🟢) 1.664s 8 1.01x
▲ Vercel Express 6.459s (-0.7%) 7.852s (-2.0%) 0.234s (-42.7% 🟢) 8.609s (-2.6%) 2.149s 7 1.07x

🔍 Observability: Next.js (Turbopack) | Nitro | Express

10 parallel streams (1MB each)

💻 Local Development

World Framework Workflow Time TTFB Slurp Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 0.610s (-37.1% 🟢) 1.016s (-18.6% 🟢) 0.000s (-58.6% 🟢) 1.038s (-17.5% 🟢) 0.428s 58 1.00x
🐘 Postgres Express 0.695s (-27.6% 🟢) 1.052s (-17.7% 🟢) 0.000s (+101.8% 🔺) 1.064s (-18.5% 🟢) 0.369s 57 1.14x
🐘 Postgres Next.js (Turbopack) 0.768s 1.053s 0.000s 1.059s 0.292s 57 1.26x
💻 Local Express 1.370s (+11.8% 🔺) 2.015s (~) 0.000s (-50.0% 🟢) 2.017s (~) 0.647s 30 2.25x
💻 Local Next.js (Turbopack) 1.402s 2.013s 0.000s 2.016s 0.615s 30 2.30x
💻 Local Nitro 1.431s (+17.0% 🔺) 2.016s (~) 0.000s (-66.7% 🟢) 2.018s (~) 0.587s 30 2.35x

▲ Production (Vercel)

World Framework Workflow Time TTFB Slurp Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 3.669s (+20.3% 🔺) 4.647s (+5.8% 🔺) 0.000s (-100.0% 🟢) 5.059s (+5.2% 🔺) 1.389s 12 1.00x
▲ Vercel Express 3.790s (+1.3%) 5.277s (+3.4%) 0.000s (-100.0% 🟢) 5.812s (+5.1% 🔺) 2.022s 11 1.03x
▲ Vercel Next.js (Turbopack) 3.849s (-62.2% 🟢) 4.996s (-56.6% 🟢) 0.000s (+Infinity% 🔺) 5.474s (-54.6% 🟢) 1.625s 11 1.05x

🔍 Observability: Nitro | Express | Next.js (Turbopack)

fan-out fan-in 10 streams (1MB each)

💻 Local Development

World Framework Workflow Time TTFB Slurp Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 1.254s (-30.0% 🟢) 1.847s (-13.7% 🟢) 0.000s (+154.5% 🔺) 1.872s (-13.9% 🟢) 0.617s 33 1.00x
🐘 Postgres Express 1.325s (-25.2% 🟢) 2.066s (-5.1% 🟢) 0.000s (NaN%) 2.076s (-5.6% 🟢) 0.751s 30 1.06x
🐘 Postgres Next.js (Turbopack) 1.530s 2.106s 0.000s 2.114s 0.585s 29 1.22x
💻 Local Next.js (Turbopack) 2.579s 3.187s 0.000s 3.190s 0.611s 19 2.06x
💻 Local Express 3.164s (-8.7% 🟢) 4.029s (~) 0.001s (-33.3% 🟢) 4.032s (~) 0.867s 15 2.52x
💻 Local Nitro 3.346s (-1.2%) 3.968s (-1.6%) 0.001s (+28.9% 🔺) 3.971s (-1.6%) 0.625s 16 2.67x

▲ Production (Vercel)

World Framework Workflow Time TTFB Slurp Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Next.js (Turbopack) 5.599s (~) 6.937s (-0.6%) 0.000s (-11.1% 🟢) 7.371s (-2.2%) 1.772s 9 1.00x
▲ Vercel Express 7.865s (+71.5% 🔺) 9.206s (+52.9% 🔺) 0.000s (+Infinity% 🔺) 9.666s (+49.7% 🔺) 1.801s 7 1.40x
▲ Vercel Nitro ⚠️ missing - - - - -

🔍 Observability: Next.js (Turbopack) | Express

Summary

Fastest Framework by World

Winner determined by most benchmark wins

World 🥇 Fastest Framework Wins
💻 Local Express 12/21
🐘 Postgres Nitro 19/21
▲ Vercel Express 8/21
Fastest World by Framework

Winner determined by most benchmark wins

Framework 🥇 Fastest World Wins
Express 🐘 Postgres 15/21
Next.js (Turbopack) 🐘 Postgres 14/21
Nitro 🐘 Postgres 18/21
Column Definitions
  • Workflow Time: Runtime reported by workflow (completedAt - createdAt) - primary metric
  • TTFB: Time to First Byte - time from workflow start until first stream byte received (stream benchmarks only)
  • Slurp: Time from first byte to complete stream consumption (stream benchmarks only)
  • Wall Time: Total testbench time (trigger workflow + poll for result)
  • Overhead: Testbench overhead (Wall Time - Workflow Time)
  • Samples: Number of benchmark iterations run
  • vs Fastest: How much slower compared to the fastest configuration for this benchmark

Worlds:

  • 💻 Local: In-memory filesystem world (local development)
  • 🐘 Postgres: PostgreSQL database world (local development)
  • ▲ Vercel: Vercel production/preview deployment
  • 🌐 Turso: Community world (local development)
  • 🌐 MongoDB: Community world (local development)
  • 🌐 Redis: Community world (local development)
  • 🌐 Jazz: Community world (local development)
  • 🌐 Redis: Community world (local development)
  • 🌐 Redis + BullMQ: Community world (local development)
  • 🌐 Cloudflare: Community world (local development)
  • 🌐 MySQL: Community world (local development)
  • 🌐 Azure: Community world (local development)
  • 🌐 NATS JetStream: Community world (local development)
  • 🌐 Upstash: Community world (local development)

📋 View full workflow run

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 22, 2026

🧪 E2E Test Results

All tests passed

Summary

Passed Failed Skipped Total
✅ ▲ Vercel Production 1222 0 219 1441
✅ 💻 Local Development 1615 0 219 1834
✅ 📦 Local Production 1615 0 219 1834
✅ 🐘 Local Postgres 1615 0 219 1834
✅ 🪟 Windows 131 0 0 131
✅ 📋 Other 741 0 176 917
Total 6939 0 1052 7991

Details by Category

✅ ▲ Vercel Production
App Passed Failed Skipped
✅ astro 105 0 26
✅ example 105 0 26
✅ express 105 0 26
✅ fastify 105 0 26
✅ hono 105 0 26
✅ nextjs-turbopack 129 0 2
✅ nextjs-webpack 129 0 2
✅ nitro 105 0 26
✅ nuxt 105 0 26
✅ sveltekit 124 0 7
✅ vite 105 0 26
✅ 💻 Local Development
App Passed Failed Skipped
✅ astro-stable 106 0 25
✅ express-stable 106 0 25
✅ fastify-stable 106 0 25
✅ hono-stable 106 0 25
✅ nextjs-turbopack-canary 112 0 19
✅ nextjs-turbopack-stable-lazy-discovery-disabled 131 0 0
✅ nextjs-turbopack-stable-lazy-discovery-enabled 131 0 0
✅ nextjs-webpack-canary 112 0 19
✅ nextjs-webpack-stable-lazy-discovery-disabled 131 0 0
✅ nextjs-webpack-stable-lazy-discovery-enabled 131 0 0
✅ nitro-stable 106 0 25
✅ nuxt-stable 106 0 25
✅ sveltekit-stable 125 0 6
✅ vite-stable 106 0 25
✅ 📦 Local Production
App Passed Failed Skipped
✅ astro-stable 106 0 25
✅ express-stable 106 0 25
✅ fastify-stable 106 0 25
✅ hono-stable 106 0 25
✅ nextjs-turbopack-canary 112 0 19
✅ nextjs-turbopack-stable-lazy-discovery-disabled 131 0 0
✅ nextjs-turbopack-stable-lazy-discovery-enabled 131 0 0
✅ nextjs-webpack-canary 112 0 19
✅ nextjs-webpack-stable-lazy-discovery-disabled 131 0 0
✅ nextjs-webpack-stable-lazy-discovery-enabled 131 0 0
✅ nitro-stable 106 0 25
✅ nuxt-stable 106 0 25
✅ sveltekit-stable 125 0 6
✅ vite-stable 106 0 25
✅ 🐘 Local Postgres
App Passed Failed Skipped
✅ astro-stable 106 0 25
✅ express-stable 106 0 25
✅ fastify-stable 106 0 25
✅ hono-stable 106 0 25
✅ nextjs-turbopack-canary 112 0 19
✅ nextjs-turbopack-stable-lazy-discovery-disabled 131 0 0
✅ nextjs-turbopack-stable-lazy-discovery-enabled 131 0 0
✅ nextjs-webpack-canary 112 0 19
✅ nextjs-webpack-stable-lazy-discovery-disabled 131 0 0
✅ nextjs-webpack-stable-lazy-discovery-enabled 131 0 0
✅ nitro-stable 106 0 25
✅ nuxt-stable 106 0 25
✅ sveltekit-stable 125 0 6
✅ vite-stable 106 0 25
✅ 🪟 Windows
App Passed Failed Skipped
✅ nextjs-turbopack 131 0 0
✅ 📋 Other
App Passed Failed Skipped
✅ e2e-local-dev-nest-stable 106 0 25
✅ e2e-local-dev-tanstack-start- 106 0 25
✅ e2e-local-postgres-nest-stable 106 0 25
✅ e2e-local-postgres-tanstack-start- 106 0 25
✅ e2e-local-prod-nest-stable 106 0 25
✅ e2e-local-prod-tanstack-start- 106 0 25
✅ e2e-vercel-prod-tanstack-start 105 0 26

📋 View full workflow run

@karthikscale3 karthikscale3 changed the title docs(cookbook): clarify tools are not individually durable in streamText pattern Fix cookbook pattern for AI SDK May 22, 2026
@karthikscale3 karthikscale3 changed the title Fix cookbook pattern for AI SDK [Docs] Fix cookbook pattern for AI SDK May 22, 2026
@karthikscale3 karthikscale3 force-pushed the karthik/cookbook-ai-sdk-tools-not-durable branch from 027316f to c661ac8 Compare May 22, 2026 23:56
@vercel
Copy link
Copy Markdown
Contributor

vercel Bot commented May 22, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
example-nextjs-workflow-turbopack Ready Ready Preview, Comment May 25, 2026 5:04pm
example-nextjs-workflow-webpack Ready Ready Preview, Comment May 25, 2026 5:04pm
example-workflow Ready Ready Preview, Comment May 25, 2026 5:04pm
workbench-astro-workflow Ready Ready Preview, Comment May 25, 2026 5:04pm
workbench-express-workflow Ready Ready Preview, Comment May 25, 2026 5:04pm
workbench-fastify-workflow Ready Ready Preview, Comment May 25, 2026 5:04pm
workbench-hono-workflow Ready Ready Preview, Comment May 25, 2026 5:04pm
workbench-nitro-workflow Ready Ready Preview, Comment May 25, 2026 5:04pm
workbench-nuxt-workflow Ready Ready Preview, Comment May 25, 2026 5:04pm
workbench-sveltekit-workflow Ready Ready Preview, Comment May 25, 2026 5:04pm
workbench-tanstack-start-workflow Ready Ready Preview, Comment May 25, 2026 5:04pm
workbench-vite-workflow Ready Ready Preview, Comment May 25, 2026 5:04pm
workflow-docs Ready Ready Preview, Comment, Open in v0 May 25, 2026 5:04pm
workflow-swc-playground Ready Ready Preview, Comment May 25, 2026 5:04pm
workflow-tarballs Ready Ready Preview, Comment May 25, 2026 5:04pm
workflow-web Ready Ready Preview, Comment May 25, 2026 5:04pm

@karthikscale3 karthikscale3 reopened this May 22, 2026
@karthikscale3 karthikscale3 deleted the karthik/cookbook-ai-sdk-tools-not-durable branch May 22, 2026 23:57
@karthikscale3 karthikscale3 restored the karthik/cookbook-ai-sdk-tools-not-durable branch May 22, 2026 23:59
@karthikscale3 karthikscale3 reopened this May 22, 2026
Comment thread docs/content/docs/v4/cookbook/integrations/ai-sdk.mdx Outdated
Copy link
Copy Markdown
Member

@VaguelySerious VaguelySerious left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM assuming this was tested, some wording nits

Comment thread docs/content/docs/v4/cookbook/integrations/ai-sdk.mdx Outdated
karthikscale3 and others added 4 commits May 25, 2026 09:59
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>
@github-actions
Copy link
Copy Markdown
Contributor

No backport to stable for ff167d0 (AI decision).

This commit only modifies docs/content/docs/v4/cookbook/integrations/ai-sdk.mdx and docs/content/docs/v5/cookbook/integrations/ai-sdk.mdx. Verified via git ls-tree origin/stable that the v4/v5 versioned docs directory structure (and the cookbook/integrations/ai-sdk.mdx files) does not exist on stable — stable has a flat docs/content/docs/ layout. There is nothing to backport.

To override, re-run the Backport to stable workflow manually via workflow_dispatch and paste this commit SHA into the ref input:

ff167d005d7b13163fe5819e132266afe3501fa4

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants