adk-unit-guide

name

adk-unit-guide

description

Writes a hands-on developer guide for one ADK code unit — a minimal runnable example, how it works, a configuration-option table, advanced uses, limitations, and links to related samples — to `docs/guides/{topic}/{unit}/index.md`, then lists it in the index at `docs/guides/README.md`. Its reader is a developer calling the unit from their own application, at more depth than the published adk.dev documentation carries. Use when asked to "write a unit guide for {class}", "document how to use {feature}", "add a guide for {file}", or after shipping a user-facing class, node, or plugin. Don't use for internals documentation aimed at someone changing or extending the unit — that is a design document under `docs/design/` (use `adk-unit-design`). Don't use to write a runnable sample under `contributing/samples/` (use `adk-sample-creator`).

ADK code unit guide

A unit guide is granular usage documentation for one code unit, deeper than what ships on adk.dev — so detail that would bloat the published documentation has somewhere to live. The reader wants to call the unit from an application, so lead with working code.

Inputs

Require the source file, or a class or method named inside it. Also read, when they exist: its unit tests (they give you an example to adapt) and its design document at docs/design/{topic}/{unit}/index.md.

Analyse before writing

• Purpose and intended use of the unit.
• Which classes depend on it, and which it depends on.
• Configuration options the unit itself introduces, ignoring inherited ones.
• Known limitations.

Where the guide goes

Mirror the source path under docs/guides/, one directory per unit, guide named index.md. Drop the leading underscore of a private module:

Source	Guide
src/google/adk/workflow/_function_node.py	docs/guides/workflow/function_node/index.md
src/google/adk/plugins/reflect_retry_tool_plugin.py	docs/guides/plugins/reflect_retry_tool_plugin/index.md

Use named files instead of index.md only when one source file has genuinely separate usage modes — docs/guides/agents/llm_agent/ holds single_turn.md and task.md for that reason.

Update an existing guide in place, keeping the existing wording wherever the code has not changed, so the diff shows only what the change actually altered.

Then add the guide to docs/guides/README.md under the right category heading, as * [Title](path/index.md) - one-line summary. That index is the only table of contents; a guide missing from it is unreachable.

Code examples

• One minimal example under "Get started", with enough of the surrounding classes to show where the call belongs. Start from a unit test if one exists.
• Do not set model= on a sample agent — guides stay model-agnostic, and no guide in docs/guides/ currently pins a model.
• For workflow nodes, show the logic as a plain Python function rather than a BaseNode subclass, unless the use case genuinely requires the subclass.
• Wrap a function as a node with the @node decorator rather than FunctionNode directly, except when demonstrating FunctionNode configuration itself.

Link related samples

Link samples by repo-relative path from the guide, not by GitHub URL: [Node Output](../../../../contributing/samples/workflows/node_output/agent.py). Confirm the file exists before linking it.

Structure

Follow references/guide-template.md section by section.