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; Optional vs | None; 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
