[FEATURE] Server-side transport helpers for SSE streaming (pipeTextStreamToResponse)

[ErikCH]

Problem Statement

The SDK provides agent.stream() (async iterator) and event.toJSON() (serialization), but no server-side transport helpers.

Every developer building a chat UI writes the same ~20 lines of SSE boilerplate:

• Set response headers (Content-Type: text/event-stream, Cache-Control: no-cache)
• Iterate agent.stream() events
• Check 3 levels of nesting to extract text deltas
• Format as data: {...}\n\n lines
• Handle errors gracefully
• Call res.end()

This is the most common integration pattern for TypeScript agents, and every consumer reinvents it.

Proposed Solution

Server-side transport helpers, similar to what the Vercel AI SDK provides:

• result.pipeTextStreamToResponse(res) — pipes text directly to an Express response
• result.pipeUIMessageStreamToResponse(res) — pipes structured events (text deltas, tool calls, reasoning) with a defined SSE protocol
• result.toDataStreamResponse() — returns a Web Response for edge/serverless runtimes

They also define a "Data Stream Protocol" — a standard SSE format with typed events (text-delta, tool-call, tool-result, reasoning-start, etc.) so frontends know exactly what to expect.

Vercel AI SDK docs for reference:

• Stream protocol: https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol
• streamText API: https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text
• Express example: https://ai-sdk.dev/cookbook/node/stream-text-express

For Strands, even a minimal helper would eliminate the most common boilerplate:

// Minimal — just pipe text deltas as SSE
pipeTextStreamToResponse(agent, message, res)

// Richer — structured events with a defined protocol
pipeEventStreamToResponse(agent, message, res)
// Emits: { type: 'text-delta', content: '...' }
//        { type: 'tool-start', tool: '...' }
//        { type: 'tool-end', tool: '...' }
//        { type: 'done', metrics: {...} }

Use Case

Building an Express.js SSE endpoint for a chat UI where you need to:

• Stream text deltas token-by-token to the frontend
• Show tool call start/end indicators
• Capture metrics from the final result event
• Handle errors without crashing the stream

Currently requires ~20 lines of boilerplate per endpoint, including the 3-level event nesting check from #1030.

Alternatives Solutions

• AG-UI ([FEATURE] AG-UI for Strands Agents SDK (Typescript) #347) may eventually provide a standard protocol, but a simple utility would help today
• The A2A Express server (@strands-agents/sdk/a2a/express) exists but only serves the A2A protocol, not general SSE streaming to frontends

Additional Context

• Related: [FEATURE] Stream helper utility for extracting text deltas without 3 levels of nesting #1030 (stream helper for extracting text deltas)
• Related: [FEATURE] AG-UI for Strands Agents SDK (Typescript) #347 (AG-UI integration)
• The official streaming docs example just does JSON.stringify(event) and dumps everything — it doesn't show selective extraction for a real chat UI

[wchon]

Hi @ErikCH, This is Allen I'm excited to contribute to the Strands project.
I’ve read contributing guide and both #1030 and #1031 carefully. I understand the problem is that every developer currently has to write repetitive boilerplate with three levels of nesting just to extract text deltas from agent.stream(), I’d like to start by implementing a minimal SSE helper as suggested:
pipeTextStreamToResponse(agent, message, res)

Draft Implementation Plan

1. New Function and Function Signature

export async function pipeTextStreamToResponse(
  agent: Agent,
  input: AgentInput,
  res: http.ServerResponse | express.Response,
  options?: PipeTextStreamOptions
): Promise<void>;

interface PipeTextStreamOptions {
  sendDoneEvent?: boolean;        // default: true
  doneEventType?: 'done' | 'complete';
}

2. What the helper will do:

• Set SSE headers
• Call agent.stream(input) and iterate
• Extract only text deltas (hide 3-level nesting)
• Write each text chunk as SSE (data: chunk\n\n)
• Error handling
• End the response properly (res.end())

Would love feedback on:

The proposed function name, signature, implementation plan
Preferred location for the file

[notowen333]

Hey @ErikCH

Maintaining generic SSE transform utility functions in the SDK would probably be out of scope.

Is there an approach on this topic which would follow SDK patterns that makes sense to you? Maybe through updating a config to invoke or a mechanism like a vended plugin.