[Docs] Add a canonical "Run agents in code" page under runtime/ (and fix dangling xref in apps/index.md)
- Dominant language
- Shell
- Stars
- 1.5k
- Forks
- 1.3k
- Avg merge
- 7d 1h
- Merged PRs (30d)
- 34
Description
Follow-up from #866 / #870 (closed as already-covered/stale). Two real gaps surfaced during that review, both originally raised by @koverholt.
### 1. No canonical page for running an agent programmatically
`docs/runtime/index.md` (L10-48) lists exactly four ways to run an agent — Dev UI, CLI, API Server, and ambient agents. Invoking an agent from Python code is absent, so there is no canonical `Runner` sample anywhere under **Run Agents**.
Today the only `run_debug()` narrative lives in `docs/apps/index.md` (L105-163), which is filed under *Components -> Apps* (`mkdocs.yml` L252, nav L377-378), not *Run Agents* (nav L324-336).
Proposal: a new `docs/runtime/run-in-code.md` (or "Querying agents") covering:
- `Runner.run_debug()` for quick experimentation — see [`runners.py#L1938-L2045`](https://github.com/google/adk-python/blob/main/src/google/adk/runners.py#L1938) and the sample at [`contributing/samples/core/runner_debug_example/`](https://github.com/google/adk-python/tree/main/contributing/samples/core/runner_debug_example)
- the full `Runner` / `run_async()` path for anything beyond that (session service, event streaming, `RunConfig`)
Note there is still no standalone canonical runner sample in adk-python's `contributing/samples/` — it only appears embedded in larger samples.
Related cleanup: ~16 pages (mostly `docs/integrations/*`) each carry their own near-identical copy of the manual `Runner` + session-service + `types.Content` + `run_async` boilerplate. A canonical page would give those something to link to.
### 2. Dangling cross-reference in apps/index.md
`docs/apps/index.md` L158-163 ends mid-sentence:
> The `Runner.run_debug()` command requires ADK Python v1.18.0 or higher. You can also use `Runner.run()`, which requires more setup code. For more details, see the
...with no link. Almost certainly pointing at the page proposed in (1). Also at L124, `response = await runner.run_debug(...)` is assigned but never used, and the name is misleading — `run_debug()` returns `list[Event]`.
### Also worth fixing (separate, in adk-python)
`contributing/samples/core/runner_debug_example/README.md` L34 has a stale invocation path — `python -m contributing.samples.runner_debug_example.main`, missing the `core.` segment.
Contributor guide
Research direction
Start with docs/runtime/index.md, docs/apps/index.md, mkdocs.yml, runners.py, and the runner_debug_example sample. Add the canonical runtime page and navigation entry, complete the dangling reference and misleading example in apps/index.md, then build the documentation to verify links and navigation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100