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 |
imports.md |
Annotating args and returns; Optional vs | None; keyword-only args; isinstance; asserts; mypy |
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 | 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 |