ADK Style Guide
Conventions for src/google/adk/ and tests/unittests/. Most are enforced by
a pre-commit hook or a CI job, so a violation blocks the PR rather than
surfacing in review. Read the one reference for the topic you are touching.
Pick a reference
| Task | Reference |
|---|---|
Adding a .py file; deciding public vs private; __init__.py and __all__ |
visibility.md |
Writing import lines; relative vs absolute; circular imports; TYPE_CHECKING; lazy imports |
imports.md |
Annotating args and returns; AgentMode vs raw mode strings; _NodePathBuilder, _BranchPath, and build_node; X | None and X | Y instead of Optional and Union; keyword-only args; isinstance; asserts; mypy; # type: ignore and cast |
typing.md |
| Defining a Pydantic model, validator, private attribute, or on-wire payload | pydantic.md |
| Indentation, line length, quotes; running the formatter; what each hook checks | formatting.md |
| Writing a docstring or an explanatory comment | documentation.md |
| Emitting a log record; naming the module logger; picking a level | logging.md |
| Anything that performs I/O — network, disk, database | async.md |
| Where a new file goes; license header; where its test goes and what to call it | file-organization.md |
Writing or restructuring a unit test; the testing_utils fakes |
testing.md |
A check failed — where to look
| Failing check | Reference |
|---|---|
check-new-py-prefix |
visibility.md |
compliance-checks |
logging.md (logger name), typing.md (from __future__ import annotations), imports.md (cli/ import direction) |
pyink, isort, ruff, addlicense, codespell |
formatting.md |
| Mypy Check CI job | typing.md |
tests/unittests/test_import_loading.py |
imports.md |