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/, and the whole set is re-verified against adk-python main.

Nine commits, meant to be read in order:

Commit	What
d89a3cc	Decompose the development guide into capability pages (index, sessions, events, configuration, voice, audio-video, tools, workflows, custom-server, models)
0f8cbd5	Drop half-cascade model coverage — no longer supported
8716d19	Retire the five-part dev guide and rewire navigation + redirects
fcfed4c	Point at the Python API reference instead of pinned adk-python source where a reference page exists
3caa1db	Fix staleness against adk-python main and drop every link to the bidi-demo sample
04d5755	Refresh the Live API supported-model list
943eaaa	Align the docs with what the current Live API models actually support
8953acf	Trim the response-modality and SSE material
f95b543	Cut duplicated and non-ADK material

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

943eaaa 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.
• voice.md: ADK picks the live API version itself (v1alpha / v1beta1), so proactivity and affective dialog 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

The last two commits remove 694 lines from docs/live/ (6,630 → 6,067) without dropping a capability. Nothing here is a judgement call about what readers need — 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.

8953acf — 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. Net: configuration.md 625 → 405 lines, and explicit_vad_signal, translation_config, avatar_config and model_input_context — previously undocumented — gain coverage.

f95b543 — duplicated and non-ADK material

Section	Lines	Why
sessions.md Best Practices for Live API Connection and Session Management	−50	Verbatim restatement of the Session Resumption and Context Window Compression sections, RunConfig snippets included. Deleted.
sessions.md Concurrency and Thread Safety + Message Ordering Guarantees	−67 → 19	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	−60 → 16	ASCII decision tree and comparison table for two patterns that reduce to a sentence each.
index.md Real-world applications	−55 → 21	Five industry vignettes making one point. The Shopper's Concierge video stays.
events.md Deserializing on the Client	−80 → 33	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	−133 → 38	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).

Deliberately left alone: events.md Optimization for Audio Transmission (practical, documented nowhere else), workflows.md Best Practices Summary (a summary, not a duplicate), and get-started/streaming-java.md, for the same reason as above — the Java behavior is unverified here.

Test plan

• mkdocs build --strict clean
• 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
• 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	f95b543
🔍 Latest deploy log	https://app.netlify.com/projects/adk-docs-preview/deploys/6a7d859d0104c500082442fd
😎 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.