docs(live): decompose the dev guide and fix staleness vs adk-python main

[kazunori279]

Summary

Phase 2 of the Live docs revamp: the five-part docs/streaming/dev-guide/ is decomposed into per-capability pages under docs/live/, the whole set is re-verified against adk-python main, and #2150 lands a quality pass on top.

Twelve commits, meant to be read in order:

Commit	What
efa0f54	Decompose the development guide into capability pages (index, sessions, events, configuration, voice, audio-video, tools, workflows, custom-server, models)
6cd6256	Drop half-cascade model coverage — no longer supported
fa8c9a1	Retire the five-part dev guide and rewire navigation + redirects
e852ac5	Point at the Python API reference instead of pinned adk-python source where a reference page exists
83cb5c0	Fix staleness against adk-python main and drop every link to the bidi-demo sample
b384907	Refresh the Live API supported-model list
98c75d4	Align the docs with what the current Live API models actually support
5a28678	Trim the response-modality and SSE material
6e45ad6	Cut duplicated and non-ADK material
08fb638	#2150 — restructure the live docs around ADK ownership
8ea417b	#2150 — standardize page leads and cut duplicated RunConfig prose
363fe0b	#2150 — reframe pages around capabilities, fix eval config key

Net: 25 files, +2,332 / −5,680. Rebased onto main.

Quality pass (#2150, @allen-stephen)

Merged into this branch; it closes every point from Stephen's review of the earlier state of this PR.

Review comment	Resolution
Why Build / Ship instead of the design doc's Building / Production?	Nav renamed to Building / Production
Collapse the new Voice page into Configuration	voice.md deleted, content folded into configuration.md, redirect added
Workflows documents 1.x agents, not 2.0 workflows	Page now leads with the ADK 2.0 graph Workflow (START / edges / mode='task', live_workflow sample). SequentialAgent / LoopAgent / ParallelAgent demoted to a Legacy workflow agents section with the deprecation and the NotImplementedError-under-run_live() caveat
Sessions and Events are too long, and Sessions still reads like a development guide	sessions.md 1,153 → 344, events.md 873 → 205. No "phase one–four" / "part N" / "what we will learn" framing remains anywhere under docs/live/

Also in these three commits:

• Nav: Evaluation moved under Production; get-started rebuilt as an extensible language hub.
• New docs/live/evaluation.md (+ docs/evaluate/user-sim.md gains the live-specific material).
• Editorial pass removing common AI-writing patterns across every page.
• Every page now links its non-live counterpart in the lead; three had none (tools.md, models.md, workflows.md).
• Platform limits and quotas were stated in three places across two pages; now only in models.md.
• Six absolute links converted to relative so --strict actually validates them.

Resulting page sizes under docs/live/:

Page	Lines
index.md	142
get-started/index.md	45
workflows.md	145
tools.md	300
sessions.md	344
events.md	205
audio-video.md	119
configuration.md	424
evaluation.md	122
custom-server.md	256
models.md	169

The bidi-demo sample is not shipped

The sample used to live in adk-samples/python/agents/bidi-demo/ and was removed there, which left every source link in docs/live/ dead. Rather than vendor a copy into this repo, all 38 references to it are removed.

The code snippets in the docs are unchanged. What went away is only the scaffolding that pointed at the sample:

• 32 code fences lost their linked Demo implementation: file.py:NN-MM title and are now plain language-tagged fences.
• The "Complete Demo Implementation" note in custom-server.md and the "Demo Implementation" note in events.md are gone; both existed only to link out.
• The "Learn More" note in tools.md and the model setup step in models.md keep their guidance but no longer cite the sample's files.
• Prose that named the demo ("The bidi-demo demonstrates how to…") is rewritten to describe the pattern directly.
• The Bidi Demo card and its screenshot are removed from the Live demos section of index.md; LensMosaic remains.

Staleness fixes, verified against adk-python main

• StreamingMode.BIDI is inert. Only run_async() reads RunConfig.streaming_mode; run_live() never does — its docstring says so explicitly. Removed from every run_live()-facing sample, and the "StreamingMode: BIDI or SSE" section is rewritten around which Runner method you call. The old anchor is preserved via attr_list so existing cross-references still resolve.
• configuration.md: run_live(session=...) is deprecated (still accepted in ADK 2.6.3); use user_id / session_id.
• tools.md: streaming tools are registered lazily on the first model call, not scanned up front. The input_stream queue is created only for tools annotated with LiveRequestQueue, and stop_streaming resets it to None. The old runners.py:828-865 / function_tool.py:238-253 references pointed at unrelated code even at their pinned SHA.
• sessions.md: document DEFAULT_MAX_RECONNECT_ATTEMPTS = 5 and the go_away reconnect trigger. Correct "automatic closure in SSE mode" — that only happens for the ADK-internal queue under support_cfc.
• events.md: audio artifacts require RunConfig.save_live_blob=True; get_author_for_event() also keys off llm_response.input_transcription, not just content.role.
• configuration.md: document history_config and the initial_history_in_client_content=True that ADK sets when seeding a fresh connection with prior history.

get-started/streaming-java.md still sets StreamingMode.BIDI; left alone because the Java behavior could not be verified without an adk-java checkout.

Model-capability verification pass

98c75d4 re-checks the pages against the Gemini Live API capabilities guide, the Agent Platform Live API docs and ADK 2.6.3, asking two questions: does the guidance match what the current models support, and do the snippets run on both gemini-3.1-flash-live-preview and gemini-live-2.5-flash-native-audio.

Would not have worked on either model:

• response_modalities=["TEXT"] was documented as valid for live agents (configuration.md, events.md, sessions.md). Every Live API model ADK supports is a native audio model, and those accept AUDIO only — configuration.md already said so two paragraphs later. Reframed around AUDIO + output audio transcription; TEXT stays where it is correct, on the run_async() / SSE path.
• docs/runtime/runconfig.md set ["AUDIO", "TEXT"] in the Python, TypeScript and Java samples. A session accepts exactly one modality.
• Four events.md snippets read event.content.parts[0]. gemini-3.1-flash-live-preview sends multiple parts per server event — the exact failure models.md warns about. They now iterate over parts.
• tools.md gave the streaming-tools root agent model="gemini-flash-latest", which has no Live API support, so the example could not run under run_live() at all. The alias is still used for the one-shot generate_content call inside the tool, where it is correct.

Stale or missing:

• configuration.md "Standard Gemini Models (1.5 Series) Accessed via SSE" described a retired family and labelled gemini-pro-latest / gemini-flash-latest as 1.5 with 2M context.
• sessions.md: send_client_content is seeding-only on Gemini 3.x Live. ADK reroutes single-part text to send_realtime_input, but multi-part Content still goes out as LiveClientContent — now documented.
• configuration.md: explicit_vad_signal, translation_config, avatar_config and model_input_context were undocumented.
• Proactivity and affective dialog: ADK picks the live API version itself (v1alpha / v1beta1), so they need no http_options — unlike the raw google-genai examples upstream.
• models.md: gemini-live-2.5-flash-native-audio is the only GA Live API model on Agent Platform, not the only one.
• Redirecting upstream URLs replaced with current targets: live-guide → live-api/capabilities, live-session → live-api/session-management, live → live-api, cloud.google.com/vertex-ai/... → the Agent Platform equivalents.

Checked and correct, left alone: session duration and context limits, audio/video specs, the proactivity + affective dialog model matrix, thinking_level vs thinking_budget, the support_cfc gemini-2 prefix check, and ADK's AUDIO default in run_live().

Simplification pass

5a28678 and 6e45ad6 remove 694 lines from docs/live/ without dropping a capability. Each cut is either a verbatim duplicate, material that documents something the current models no longer let you choose, or code that no longer resolves. Several of the pages touched here are trimmed further by the #2150 commits above — read those for the final shape.

5a28678 — response modality and StreamingMode

Every Live API model ADK supports is a native audio model, so a live session's response modality is always AUDIO; there is no decision left to document. configuration.md's Response Modalities section shrinks to the one thing that still matters — reading text off event.output_transcription.

StreamingMode is only read by run_async(), and an SSE tutorial had grown around it on a page about live agents: protocol diagrams, a progressive-streaming walkthrough, a mode-selection table, and a model list built on the retired 1.5 series. All of it duplicates runtime/runconfig.md#enable-streaming. The inert-BIDI warning and the run_live()/run_async() split stay; the #streamingmode-bidi-or-sse anchor is preserved for inbound links. explicit_vad_signal, translation_config, avatar_config and model_input_context — previously undocumented — gain coverage.

6e45ad6 — duplicated and non-ADK material

Section	Why
sessions.md Best Practices for Live API Connection and Session Management	Verbatim restatement of the Session Resumption and Context Window Compression sections, RunConfig snippets included. Deleted.
sessions.md Concurrency and Thread Safety + Message Ordering Guarantees	An asyncio.Queue primer plus a copy of the upstream task from custom-server.md. Condensed to the three properties that affect calling code; the tip to poll the private _queue.qsize() is gone.
sessions.md Architectural Patterns for Managing Quotas	ASCII decision tree and comparison table for two patterns that reduce to a sentence each.
index.md Real-world applications	Five industry vignettes making one point. The Shopper's Concierge video stays.
events.md Deserializing on the Client	80 lines of the removed bidi-demo's UI code, calling helpers (createMessageBubble, audioPlayerNode) that exist nowhere in these docs. Reduced to the event-shape handling it was there to show.
audio-video.md Handling Image Input at the Client	getUserMedia/canvas/FileReader boilerplate followed by a seven-point recap of itself.

Two dead absolute links fixed in passing: /agents/multi-agents/#workflow-agents-as-orchestrators (the page redirects to workflows/index.md and the anchor no longer exists) and /live/streaming-tools/ (no such page — the content is in tools.md).

Rebase note

Rebasing onto main produced one conflict, in docs/runtime/runconfig.md § Configure live agents. main had grown the duplicated live-parameter list (avatar_config, explicit_vad_signal, history_config, translation_config, plus a TypeScript tab); #2150 replaced that list with links into the live docs. Resolved by keeping the links, after confirming each of the four new parameters is documented in live/configuration.md. Two things were kept from main:

• tool_thread_pool_config, which appears nowhere under docs/live/ — it is a runtime concern, so it stays on the runtime page with its example and GIL note.
• The TypeScript tab. docs/live/ has no TypeScript content at all, so dropping it would remove the only TS example of live RunConfig.

Test plan

• mkdocs build --strict clean, zero warnings, after the docs(live): quality pass on the live and voice agent docs #2150 merge and after the rebase
• All CI green on the rebased head: build, link-check, test ×2, check-changes, header-check, cla, Netlify preview
• No remaining references to bidi-demo outside two APP_NAME = "bidi-demo" string literals in sample snippets
• No github.com/google/adk-docs/.../main/... self-links added by this PR, so the link-checker has nothing unresolvable to hit
• #history_config, #streamingmode-bidi-or-sse and #other-live-related-fields anchors present in built HTML; inbound cross-references resolve
• live/voice.md → live/configuration.md redirect registered in mkdocs.yml
• Every rewritten upstream URL returns HTTP 200 directly (no redirect), and each anchor exists on the target page
• No inbound links to any removed anchor (grepped across docs/)

[netlify]

✅ Deploy Preview for adk-docs-preview ready!

Name	Link
🔨 Latest commit	363fe0b
🔍 Latest deploy log	https://app.netlify.com/projects/adk-docs-preview/deploys/6a86a6355e5a7a0008508ee6
😎 Deploy Preview	https://deploy-preview-2086--adk-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[allen-stephen]

LGTM - thanks @kazunori279!

[joefernandez]

Approved with updates.