Adk Unit Guide

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.

Unit guides focus on public APIs and caller-visible behavior. Do not discuss internal implementation details (such as private methods, internal state mechanisms, or unexported helpers).

Voice

Write to help the reader understand, not to instruct them from above.

• Give the reason, not only the rule. Whenever the guide states a constraint, a default, or a recommendation, say why it is that way. A reader who knows the reason can handle the case the guide did not anticipate.
• Do not decide for the reader. Phrasings such as "most applications never need this" or "you will rarely" tell people what they want. State the trade-off and let them choose.
• Explain at the caller's level. Explaining what happens is required; explaining the machinery that makes it happen is not. If an explanation needs a private symbol to make sense, it is pitched at the wrong layer.
• Length follows understanding. Brevity is not the goal. Where a reader would have a follow-up question, answer it. Where the sentence already lands, leave it.
• Problem before syntax. Say what the reader is trying to do, then show the code.
• Every heading has at least one sentence under it before the next heading, and every code block has a sentence introducing what it does.

Sentence-level rules, following the Google developer documentation style guide: present tense, no contractions, no parentheticals (use commas), no bare "This" as a subject, no e.g. or etc., no superlatives, sentence case in headings, and no heading deeper than H3.

What the difference looks like

From the BaseNode guide. Before:

Most applications never subclass BaseNode, so the sections that follow cover the settings first.

That decides for the reader and gives them nothing to check their own case against. After:

You usually configure a node rather than subclass one, because the settings below cover what most graphs need. Subclassing earns its keep when you want behavior the settings cannot express, and that case is at the end.

Same length, same facts. The second one names the reason, so a reader can tell which of the two situations is theirs.

A second pair, from the JoinNode guide. Before:

Here three tasks run in parallel on the same input, and a JoinNode collects their results.

That opens in speech rather than documentation, and it drops the name of the pattern the reader would search for. After:

This example builds a fan-out/fan-in workflow. Three tasks run in parallel on the same input, and a JoinNode aggregates their results so that a final node can present all three together.

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.
• Exclude internal implementation details such as private methods and attributes, internal helper functions, private execution state, or internal data structures.

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:

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.

When a guide is not required

scripts/check_new_py_files.py enforces this convention on the Python files a change adds under src/google/adk/. Some it passes over without asking, and the rest you can waive, so work out which case you are in before writing a guide the rule does not ask for.

Three subtrees sit outside the rule, because nothing in them is published: src/google/adk/internal/, src/google/adk/platform/internal/, and src/google/adk/v1/.

Elsewhere a file is exempt on one of two grounds. It carries no unit of its own, which covers __init__.py and any path with a cli/ or utils/ component. Or it holds declarations that belong in the guide of whatever uses them rather than in a guide of their own, which covers any filename ending _utils.py, _helper.py, _helpers.py, _types.py, _errors.py, _exceptions.py, or _constants.py.

A module is also exempt when no package __init__.py imports from it or names it, because then it has no public interface for a guide to describe. The check reads every __init__.py under src/google/adk/, and lazy re-exports count: an import under if TYPE_CHECKING: or inside __getattr__, and a string that names the module in a lazy-import table. Its _ prefix decides nothing, so export a name from a new module and that module needs a guide.

Everything else needs a guide or a waiver. A waiver is a NO_UNIT_GUIDE= or SKIP_UNIT_GUIDE= tag carrying the reason, and the two names behave identically. It waives the unit guide requirement alone; the _ prefix rule shares the same hook and the same error report, and has no waiver at all. One tag waives every file the change adds, not the one its reason names, so a change adding several needs a reason that covers all of them.

Write a reason a reviewer can check against the code, because the tag becomes the only record of why the guide is absent:

NO_UNIT_GUIDE=InvocationNotFoundError is covered by docs/guides/errors/index.md.