Docs: Need better documentation for using streams

[mmmcccarter]

• Workflow DevKit: 4.0.1-beta.2
• Next.js: 16
• node: 22
• World: world-local

Problem

Workflow streaming writes chunks successfully to .next/workflow-data/streams/chunks/ but workflowHandle.getReadable() never yields them. The stream reader blocks forever.

Expected:

const handle = await run(myWorkflow, 'test-stream');
const readable = await handle.getReadable({ startIndex: 0 });
const reader = readable.getReader();
const { value } = await reader.read(); // Should return chunk

Actual:

• reader.read() blocks indefinitely
• Chunks exist on disk with correct data
• Workflow completes successfully
• No errors logged

Reproduction:

// workflow
export async function testWorkflow(streamName: string) {
  'use workflow';
  const writer = await getWritable(streamName);
  for (let i = 0; i < 3; i++) {
    await writer.write({ chunk: i });
  }
  await writer.close();
}

// route handler
export async function POST(req: Request) {
  const handle = await run(testWorkflow, 'test');
  const readable = await handle.getReadable({ startIndex: 0 });
  const reader = readable.getReader();
  const { value } = await reader.read(); // Blocks forever
  return Response.json({ value });
}

Hypothesis

The readFromStream() function should:

1. Read existing chunk files from disk
2. Subscribe to EventEmitter for real-time chunks

Both appear broken - EventEmitter likely doesn’t work across Next.js route boundaries, and file reading logic may also have issues.

Note: This may be the first streaming bug report for world-local. Happy to provide additional debugging info.

Have reviewed all examples but no luck

[pranaygp]

What is await run(myWorkflow, 'test-stream')?

Do you mean start from the workflow/api package?
also the arguments should be proviaded as an array

Also, since you're naming the stream, you have to use the same stream name in the workflow when using getReadable({namespace: "test"}) in your case

You can also simply not name the stream - which will then use the run's "default" stream.

Try this:
Update: See @TooTallNate's comment below for the right answer (you can't write to streaming inside the workflow)

---

We certainly need better documentation for streams

[TooTallNate]

You can't write to the stream directly in the workflow function, you need to pass it into a step function and do the writing there. This workflow will throw an error.

This works:

// route.ts
import { start } from "workflow/api";
import { testWorkflow } from "@/workflows/user-signup";

export async function POST() {
	const handle = await start(testWorkflow);
	const readable = handle.getReadable();
	return new Response(readable);
}


// workflow.ts
import { getWritable } from "workflow";

export async function testWorkflow() {
	"use workflow";

	const writable = getWritable();
	await writeToStream(writable);
}

async function writeToStream(writable: WritableStream) {
	"use step";

	const writer = writable.getWriter();
	for (let i = 0; i < 3; i++) {
		await writer.write(`${JSON.stringify({ chunk: i })}\n`);
	}
	await writer.close();
}

[rown89]

.getReadable();

What if i want to stream to ai-sdk/react?
Should i use createUIMessageStreamResponse or return new Response(readable); it's ok in the POST?

[TooTallNate]

I suggest checking out the @workflow/ai package which is in development which has a couple Workflow compatible classes to aid in usage with @ai-sdk/react:

• https://useworkflow.dev/docs/api-reference/workflow-ai/durable-agent
• https://useworkflow.dev/docs/api-reference/workflow-ai/workflow-chat-transport

There is this flight-booking-app which shows usage of these two classes together.

[rown89]

I suggest checking out the @workflow/ai package which is in development which has a couple Workflow compatible classes to aid in usage with @ai-sdk/react:

* https://useworkflow.dev/docs/api-reference/workflow-ai/durable-agent

* https://useworkflow.dev/docs/api-reference/workflow-ai/workflow-chat-transport

There is this flight-booking-app which shows usage of these two classes together.

Thx!
Currently i'm tring DurableAgent but i'm getting this error when a tool trigger a step:

[Workflows] "wrun_01K8RWNHKPSGMAYXWBD9K6EV4S" - Encountered `Error` while executing step "step//node_modules/.pnpm/@workflow+ai@4.0.1-beta.4_ai@5.0.82_zod@3.25.55__workflow@4.0.1-beta.4_@aws-sdk+client-_93cd206134776949218c56c10fd2c691/node_modules/@workflow/ai/dist/agent/do-stream-step.js//doStreamStep" (attempt 3):
  > GatewayAuthenticationError: AI Gateway authentication failed: No authentication provided.
    > 
    > Option 1 - API key:
    > Create an API key: https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%2Fapi-keys

I've seen the gateway docs and set a key from vercel gateway, but no luck.
I'm still getting this same error.

Seems that DurableAgent model prop accept a string only, and i can't import from @ai-sdk/openai using my own key directly.
As DurableAgent is my workflow entry point and one of the tools use streamText should i use the string like DurableAgent for the model or can I use openai('gpt-5') imported from @ai-sdk/openai?