adk-style

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

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