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.