Proposal: task-oriented page for TypeScript HTTP token streaming under Run Agents → Agent Runtime

[AmaadMartin]

Following up on #2076, which @kazunori279 closed on placement grounds and then pointed at a home for. Opening this to settle scope before writing anything, per CONTRIBUTING.md.

Proposal

A task-oriented page on HTTP token streaming in TypeScript, under Run Agents → Agent Runtime, alongside runtime/cancel.md and runtime/runconfig.md.

To be explicit about what this is not: it is not the Live API. It covers StreamingMode.SSE — ordinary incremental delivery of a text reply — which is a different feature from the bidirectional audio/video live.connect() path that docs/live/ documents. TypeScript has the former and not the latter, which is exactly why #2076 was in the wrong section.

Kaz's two reasons for this placement, which I verified:

• runtime/cancel.md is already TypeScript-only (docs/runtime/cancel.md:3-5 carries TypeScript v1.0.0 and no other language tag), so a single-language page in this section is established precedent, not an exception. Python/Go/Java tabs can be added later without moving the page.
• runtime/runconfig.md#enable-streaming already covers the reference material and already has TypeScript tabs. What's missing is the walkthrough, which is a different genre and shouldn't be crammed into a config reference.

Scope

Assumes runconfig.md for "what the modes are" and links to it rather than restating. Assumes get-started/typescript.md for project setup and credentials.

In:

• The runAsync + StreamingMode.SSE loop, and the fact that streaming is off by default
• The duplication trap: the final event repeats the entire answer with partial: false, so naive text += chunk renders it twice (measured at exactly 2.000×), and the accumulation helper that avoids it
• Text arriving only as partial: false when a chunk carries both text and a functionCall — the case that silently loses output once an agent has tools
• Errors arriving as events with errorCode, not as thrown exceptions
• Minimal SSE-over-HTTP plumbing, including flushHeaders()

Out: project scaffolding, dependency install, credential setup, the browser UI walkthrough, and a restatement of the streaming modes.

That should land it well under half of #2076's 389 lines. Kaz asked for "noticeably shorter", and most of what I'd cut is the setup material that duplicates get-started/typescript.md.

Open questions

1. Page path and title — runtime/streaming.md, "Stream agent responses"? Happy to take whatever fits the section's naming.
2. How far to take the HTTP plumbing. docs(live): add a streaming quickstart for ADK TypeScript #2076 ended in a working browser UI, which is the actual task a JS developer arrives with, but it's also the largest chunk of the page and the part that most overlaps a general Express tutorial. I'd propose a minimal SSE endpoint and a fetch + getReader() client, and stop there. Say if even that is too much.
3. Whether to wait. Two SDK-side things touch this: StreamingMode.BIDI silently degrading (filed as StreamingMode.BIDI is accepted but has no effect — silently degrades to NONE with no error or warning adk-js#676) and Runner.runLive not existing. Neither blocks an SSE page, but if BIDI is about to start throwing, the page's wording should anticipate that.

Related, on your side

Kaz already spotted that runconfig.md:106 tells readers to "use runner.run_live() instead" for bidirectional streaming — true for Python, not for TypeScript, on a page carrying a TypeScript tab. One adjacent nit while that page is open: line 97 says "set the streaming_mode parameter" in language-neutral prose, but the TypeScript property is streamingMode (the code tabs at :34 and :134 get it right). Both are one-line fixes; glad to fold them into a small PR if that's easier than doing it yourselves.

Everything proposed here was executed and measured while writing #2076, so this is a matter of reshaping verified material rather than new research. I won't start until scope is agreed.

[AmaadMartin]

Correction to the issue body above: I wrote "well under half of #2076's 389 lines". The page closed at 498 lines, not 389 — 389 was its first commit, and it grew through three rounds of review (389 → 413 → 454 → 498) as I added the fixes Joe and Kaz asked for.

So the size commitment was anchored to the wrong number. Restating it against the real one, and tightening rather than loosening it: I'm targeting ~200 lines, which is well under half of 498 and roughly the size of runtime/cancel.md. Dropping the scaffolding, credentials and browser-UI sections is most of the difference.

This is the second time in this workstream I've cited a figure about my own work without re-reading the source — the other was on adk-js#628. Flagging the pattern rather than just the instance, since it bears on how much weight to give any number I quote unprompted. Everything in the scope proposal that came from a measurement is re-checkable from the closed PR's diff.

[kazunori279]

Scope approved as written — this is the right shape and the right place. Three answers plus some shaping notes, then please go ahead.

1. Path and title

runtime/streaming.md works. Two conventions to match:

• Nav entry in Title Case, H1 in sentence case. The section does this consistently: Cancel Agent Runs / # Cancel agent runs, Resume Agents / # Resume agents. So: nav Stream Agent Responses, H1 # Stream agent responses.
• Slot it after Cancel Agent Runs and before Runtime Config in mkdocs.yml. The section is ordered task pages first, reference pages after, and this is a task page that leans on the reference.

Carry a <div class="language-support-tag"> with just the TypeScript version, as cancel.md:3-5 does, and wrap the code in === "TypeScript" tabs even though there is only one — that is what makes adding Python/Go tabs later a non-event.

2. How far to take the HTTP plumbing

Your proposal is right: a minimal SSE endpoint plus a fetch + getReader() client, and stop. Two things that make that cheaper than you may be budgeting for:

Put the code in snippet files, not in the page. cancel.md keeps every line of TypeScript in examples/typescript/snippets/runtime/cancel/*.ts and pulls named regions in:

--8<-- "examples/typescript/snippets/runtime/cancel/basic-usage.ts:full"

Do the same under examples/typescript/snippets/runtime/streaming/. The server then costs the page one include line instead of eighty lines of inline Express, and the code stays compilable and checkable in CI rather than rotting in a fence. This is also why the overlap with "a general Express tutorial" mostly evaporates — the framework stays out of the reader's field of view.

The one exception is flushHeaders(). Keep that in prose, with the measurement. It is the piece a reader cannot infer and will not notice is missing until their stream feels broken.

3. Whether to wait

Don't wait. Write against today's behaviour.

Better still, don't document BIDI on this page at all — that belongs in runconfig.md, and it is now there. #2101 landed the correction you flagged (the run_live() pointer), plus the streaming_mode/streamingMode naming nit, plus two more I found while in there: the TypeScript tab was recommending supportCfc: true, which produces errorCode: 'UNKNOWN_ERROR' and no response text, and the Configure live agents section was carrying a TypeScript tag for fields that are typed but inert. So both of your line-level fixes are done — nothing to fold in. Just link to runconfig.md#enable-streaming and let it carry the modes. If adk-js#676 changes BIDI to throw, that is a one-sentence edit on a page you won't own.

Shaping notes

Lead with the duplication trap. Of everything in your In list, that is the item with the highest value per line: it silently breaks working-looking code, and it appears in no reference. The partial: false + functionCall case is the second, for the same reason — it costs a reader output the moment they add a tool. Errors-as-events is third. The runAsync + SSE loop is table stakes and should be short. If the page runs long, cut from the bottom of that list, not the top.

On length. Thank you for the correction, and for flagging it as a pattern rather than an instance — that is more useful to me than the number was. One more calibration in the same direction: runtime/cancel.md is 101 lines, not ~200. I am not asking you to hit 101, and I would rather have the duplication trap explained properly than a page trimmed to a target. But the snippet-include convention above tends to get you there without trying, so treat ~150 as comfortable and anything past 200 as a signal to re-read the Out list.

One addition to In, if it is cheap: streaming being off by default is on your list, and it is worth one sentence saying what the default actually yields — a single complete event — so a reader who forgot the flag recognises the symptom.

Go ahead and open the PR whenever you're ready.