How to contribute
We'd love to accept your patches and contributions to this project.
Sign our Contributor License Agreement
Review our community guidelines
Before you begin
Sign our Contributor License Agreement
Contributions to this project must be accompanied by a
(CLA). You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project.
If you or your current employer have already signed the Google CLA (even if it was for a different project), you probably don't need to do it again.
Visit
https://cla.developers.google.com/
to see your current agreements or to sign a new one.
Review our community guidelines
This project follows
Google's Open Source Community Guidelines
.
Code reviews
All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult
for more information on using pull requests.
How an accepted pull request lands
ADK is developed in an internal repository and mirrored to GitHub with
. An accepted pull request is often landed internally and then mirrored back out, with your authorship preserved on the resulting commit. GitHub shows that as a closed pull request rather than a merged one, and your change appears on main as a separate commit.
So a closed pull request does not on its own mean the change was rejected. When a pull request lands this way, we comment on it with the commit that carries your change and add the merged label. If a pull request is closed without either, please ask on it.
Contribution workflow
Finding Issues to Work On
Browse issues labeled good first issue (newcomer-friendly) or help wanted (general contributions).
For other issues, please kindly ask before contributing to avoid duplication.
Requirement for PRs
All PRs, other than small documentation or typo fixes, should have an Issue associated. If a relevant issue doesn't exist, please create one first or you may instead describe the bug or feature directly within the PR description, following the structure of our issue templates.
Small, focused PRs. Keep changes minimal—one concern per PR.
For bug fixes or features, please provide logs or screenshot after the fix is applied to help reviewers better understand the fix.
Please include a testing plan section in your PR to describe how you will test. This will save time for PR review. See Testing Requirements section for more details.
Large or Complex Changes
For substantial features or architectural revisions:
Open an Issue First: Outline your proposal, including design considerations and impact.
Gather Feedback: Discuss with maintainers and the community to ensure alignment and avoid duplicate work
Testing Requirements
To maintain code quality and prevent regressions, all code changes must include comprehensive tests and verifiable end-to-end (E2E) evidence.
Unit Tests
Please add or update unit tests for your change. Please include a summary of passed pytest results.
Requirements for unit tests:
Coverage: Cover new features, edge cases, error conditions, and typical use cases.
Location: Add or update tests under tests/unittests/, following existing naming conventions (e.g., test_<module>_<feature>.py).
Framework: Use pytest. Tests should be: Fast and isolated.
Written clearly with descriptive names.
Free of external dependencies (use mocks or fixtures as needed).
Quality: Aim for high readability and maintainability; include docstrings or comments for complex scenarios.
Manual End-to-End (E2E) Tests
Manual E2E tests ensure integrated flows work as intended. Your tests should cover all scenarios. Sometimes, it's also good to ensure relevant functionality is not impacted.
Depending on your change:
ADK Web:
Use the adk web to verify functionality.
Capture and attach relevant screenshots demonstrating the UI/UX changes or outputs.
Label screenshots clearly in your PR description.
Runner:
Provide the testing setup. For example, the agent definition, and the runner setup.
Execute the runner tool to reproduce workflows.
Include the command used and console output showing test results.
Highlight sections of the log that directly relate to your change.
Documentation
For any changes that impact user-facing documentation (guides, API reference, tutorials), please open a PR in the
repository to update the relevant part before or alongside your code PR.
Development Setup
Clone the repository:
gh repo clone google/adk-python cd adk-python
Install uv:
Check out
.
Setup Development Tools:
We use pre-commit for code formatting and license enforcement, tox with tox-uv for isolated multi-version testing, and addlicense for Apache 2.0 license headers.
uv tool install pre-commit uv tool install tox --with tox-uvOptionally, install Google's addlicense tool for license header checks (requires Go):
go install github.com/google/addlicense@latestIf addlicense is not installed, the pre-commit hook will be skipped and CI will catch missing headers.
Install the git hooks to automatically format and check your code before committing:
pre-commit installThe pre-commit hooks run isort, pyink, addlicense, and mdformat automatically on each commit.
Create virtual environment and install dependencies:
uv venv --python "python3.11"".venv"source .venv/bin/activate uv sync --all-extras
Run unit tests locally (Fast):
If you just want to run tests quickly while developing, run pytest:
pytest ./tests/unittests
Run multi-version unit tests (Required before PR):
ADK guarantees compatibility across Python versions. You must run the full test suite across all supported versions using tox. This will execute tests in pristine, isolated environments.
tox(Note: uv will automatically download any Python interpreters you are missing!)
Auto-format the code:
If you installed the git hooks in Step 3, this happens automatically on commit. To run it manually across all files:
pre-commit run --all-files
Build the wheel file:
uv build
Test the locally built wheel file: Have a simple testing folder setup as mentioned in the
.
Then following below steps to test your changes:
Create a clean venv and activate it:
VENV_PATH=~/venvs/adk-quickstartcommand -v deactivate >/dev/null 2>&1&& deactivaterm -rf $VENV_PATH \ && python3 -m venv $VENV_PATH \ &&source$VENV_PATH/bin/activateInstall the locally built wheel file:
pip install dist/google_adk-<version>-py3-none-any.whl
Contributing Resources
has resources that are helpful for contributors.
AI-Assisted Development
This repo includes built-in skills for AI coding agents (Antigravity, Gemini CLI, Claude Code, and others) to help with ADK development:
adk-setup — Set up the local development environment: install dependencies, configure pre-commit hooks, verify the setup.
adk-agent-builder — Build, test, and iterate on ADK agents: function nodes, LLM agent nodes, routing, fan-out, human-in-the-loop, and session state.
adk-architecture — ADK internals: the runner, node contracts, context, resumption, observability.
adk-debug — Debug ADK agents: inspect sessions, trace event flows, check LLM requests/responses, diagnose tool call issues. Supports both adk web (browser UI) and adk run (CLI) workflows.
adk-style — Codebase conventions: Python idioms, imports, typing, Pydantic usage.
adk-review — Review local changes for errors, style compliance, and missing tests before opening a pull request.
adk-git — Git operations and the commit message conventions this repo uses.
adk-sample-creator — Author a new sample under contributing/samples/.
adk-unit-design, adk-unit-guide — Write code unit design documents and code unit guides.
adk-verify-snippets — Extract the Python code blocks from a Markdown file and check that they still run.
These skills live in .agents/skills/. Each one is a directory holding a SKILL.md file plus its reference Markdown, and nothing installs them: a coding agent started from a clone of this repo picks them up where they are. To use one outside the repo, copy its directory into the skills folder your agent reads (commonly ~/.agents/skills/).
The AGENTS.md file provides additional project context that can be used as LLM input.