docs(runtime): correct API routes, CLI flags, and RunConfig fields

[GWeale]

Audit of the runtime pages (event loop, api server, command line, resume, runconfig, web interface, ambient agents) plus the apps page, where documented HTTP routes, CLI flags, defaults and example code had drifted from the v2.5.0 Python source.

Changes

• docs/runtime/ambient-agents.md — the webhook example and the curl example both POSTed to /apps/my_agent/run, which is not a route the API server serves; both now POST to /run (the body already carries app_name).
• docs/runtime/command-line.md — the Python option table was missing six real flags (--use_local_storage/--no_use_local_storage, --state, --timeout, --in_memory, --jsonl, --default_llm_model) and did not mention that adk run <agent> "hello" sends one message and exits instead of starting an interactive session.
• docs/runtime/web-interface/index.md — --session_service_uri was documented as defaulting to in-memory; it defaults to SQLite under .adk/session.db. Adds a note that --no_use_local_storage is what falls back to in-memory services.
• docs/runtime/api-server.md — session delete was documented as returning 204 No Content in Python; Python returns 200 OK with a null body (TypeScript is the one returning 204).
• docs/runtime/resume.md — the curl body had a trailing comma (invalid JSON); run_async was shown called without being iterated, though it is an async generator; and the resumable-agent example had a commented-out state class, passed the enum instead of the state model to _load_agent_state, and called _create_agent_state_event with arguments it does not take — state is now set via ctx.set_agent_state(...).
• docs/runtime/runconfig.md — adds model_input_context, history_config and translation_config; corrects the max_llm_calls limit to only reject the exact value sys.maxsize; notes save_input_blobs_as_artifacts is deprecated in Python in favor of SaveFilesAsArtifactsPlugin.
• docs/runtime/event-loop.md — the blocking-I/O section claimed the framework prevents stalls for sync tools; Python calls a sync tool inline on the asyncio loop, so it does stall, and RunConfig.tool_thread_pool_config is the live-mode escape hatch. Also fixes the Runner module path to google.adk.runners.
• docs/apps/index.md — the list of optional App features omitted events_compaction_config.

How this was produced

Part of a page-by-page audit of the Python docs against the google/adk-python v2.5.0 source: every import resolved against a real 2.5.0 install, every constructor kwarg checked against model_fields / inspect.signature, every documented default read off the field. A second independent pass re-derived each claim from source rather than trusting the finding, and a third conformed the new wording to the surrounding pages. mkdocs build --strict is clean.

Only Python tabs and language-neutral prose were touched — this audit had no ground truth for the Go / Java / TypeScript SDKs.

Split out of a larger audit branch so each area can be reviewed on its own.

Staged pages:

• https://deploy-preview-2020--adk-docs-preview.netlify.app/apps/
• https://deploy-preview-2020--adk-docs-preview.netlify.app/runtime/web-interface/

[netlify]

✅ Deploy Preview for adk-docs-preview ready!

Name	Link
🔨 Latest commit	d82bfa3
🔍 Latest deploy log	https://app.netlify.com/projects/adk-docs-preview/deploys/6a7f8c8c3af85000087ce52a
😎 Deploy Preview	https://deploy-preview-2020--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.

[joefernandez]

Technical review report

Verified claims in PR #2020 against google/adk-python main @ 2353dde (post-v2.6.3, newer than the v2.5.0 the author audited).

Verdict: approve — all ~14 corrections are technically correct, no false claims found.

Highest-signal evidence:

• /apps/my_agent/run → /run: the server serves only /run and /run_sse; no /apps/{app_name}/run exists. app_name is read from the body (L1668-1675).
• Delete session is 200/null, not 204: handler returns None with no status_code (api_server.py L1371-1377); upstream's own test asserts 200 (test_fast_api.py L1462-1469).
• Six missing adk run flags + positional query: all present at cli_tools_click.py L774-L905; single-shot dispatch at L939-961.
• Session default is per-agent SQLite, not in-memory: service_factory.py L222-228 + dot_adk_folder.py L51-56.
• resume.md API fixes: _load_agent_state requires a BaseAgentState subclass (base_agent.py L179-196, TypeVar at L89), _create_agent_state_event takes only ctx (L198-220), and upstream's test uses the exact set-then-create pattern the PR adopts (test_base_agent.py L1036-1077).
• Sync tools do stall the loop (the PR's most substantive fix): function_tool.py L369-378 calls target(**args) inline; the thread pool is reachable only from the live path (functions.py L1180-1196).
• max_llm_calls: validator is exact-equality value == sys.maxsize (run_config.py L287-291), so "at or above" was genuinely wrong.
• v1.14.0 → v1.16.0: "Support pause and resume an invocation in ADK" lands in the 1.16.0 section (CHANGELOG.md L2070/L2076).

Three non-blocking nits (detailed in the artifact): the --use_local_storage + URI combination is a hard UsageError not a no-op; local storage silently degrades to in-memory on a read-only agents dir (relevant to the new web-interface note); and SaveFilesAsArtifactsPlugin is not re-exported from google.adk.plugins — harmless as the PR words it, but a trap for a follow-up.

[joefernandez]

Approved with minor updates.