google / google/adk-docs

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

Open
#2,124 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Shell
Stars
1.5k
Forks
1.3k
Avg merge
7d 1h
Merged PRs (30d)
34

Description

Following up on #2076, which @kazunori279 closed on placement grounds and then [pointed at a home for](https://github.com/google/adk-docs/pull/2076#issuecomment-5223799176). 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.** #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 google/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.

Contributor guide

Open the contributing guide

Research direction

Read docs/runtime/runconfig.md, docs/runtime/cancel.md, and the linked #2076 material first, then confirm the page path, title, and HTTP scope with maintainers. Done means an approved, shorter TypeScript task-oriented page covering the listed SSE cases without duplicating setup or mode reference material, plus the noted runconfig.md wording fixes if included.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.