adk-setup

# ADK Python Development Setup Set up a working `adk-python` checkout: a uv-managed virtual environment with every dependency extra, pre-commit hooks, and a green unit-test run. ## Prerequisites 1. **Python.** ADK supports 3.11 through 3.15 (`requires-python = ">=3.11"` in `pyproject.toml`). These steps use 3.11, the version the repo's own tooling defaults to. ```bash python3 --version ``` 2. **uv.** Dependencies are declared in `pyproject.toml`. The `uv sync` step below creates a local `uv.lock`, which this repository ignores. Run that step before `tox`, whose lock runner requires the file. ```bash uv --version ``` Install it if missing: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` ## Setup Run these from the repository root. 1. **Create and activate the virtual environment:** ```bash uv venv --python "python3.11" ".venv" source .venv/bin/activate ``` 2. **Install every dependency extra:** ```bash uv sync --all-extras ``` `--all-extras` is what pulls in the `test` and `dev` extras. Syncing only the default dependencies leaves `pytest` and the linters uninstalled. 3. **Install pre-commit and tox as standalone tools:** ```bash uv tool install pre-commit uv tool install tox --with tox-uv ``` Both are also in the `dev` extra; installing them as uv tools puts them on PATH so the git hook and multi-version test runs work without an activated venv. 4. **Install `addlicense` (optional, requires Go):** ```bash go install github.com/google/addlicense@latest ``` Without it the pre-commit hook prints `Warning: addlicense not installed, skipping` and passes, so a missing Go toolchain does not block setup — CI catches missing license headers instead. 5. **Install the git hooks:** ```bash pre-commit install ``` On each commit the hooks auto-format with `isort`, `pyink`, and `mdformat`, then run `ruff`, `addlicense`, `codespell`, and the repo's own compliance checks. 6. **Verify the environment:** ```bash pytest tests/unittests -n auto ``` A green run here is the success criterion for setup. `-n auto` needs `pytest-xdist`, which arrives with the `test` extra in step 2. ## Key commands | Task | Command | | :----------------------------------- | :------------------------------------------------- | | Run unit tests | `pytest tests/unittests` | | Run unit tests in parallel | `pytest tests/unittests -n auto` | | Run one test file | `pytest tests/unittests/agents/test_base_agent.py` | | Run tests on every supported Python | `tox` (uv downloads any missing interpreters) | | Format and lint everything | `pre-commit run --all-files` | | Launch the web UI | `adk web {agents_dir}` | | Run an agent from the CLI | `adk run {agent_dir}` | | Build the wheel | `uv build` |