We'd love to accept your patches and contributions to this project.

• How to contribute
• Before you begin
  • Sign our Contributor License Agreement
  • Review our community guidelines
• Contribution workflow
  • Finding Issues to Work On
  • Requirement for PRs
  • Large or Complex Changes
  • Testing Requirements
  • Unit Tests
  • Manual End-to-End (E2E) Tests
  • Documentation
  • Development Setup
  • Code reviews

Contributions to this project must be accompanied by a Contributor License Agreement (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.

This project follows Google's Open Source Community Guidelines.

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

• Browse issues labeled good first issue (newcomer-friendly) or help wanted (general contributions).
• For other issues, please kindly ask before contributing to avoid duplication.

• 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.

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

To maintain code quality and prevent regressions, all code changes must include comprehensive tests and verifiable end-to-end (E2E) evidence.

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 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.

For any changes that impact user-facing documentation (guides, API reference, tutorials), please open a PR in the adk-docs repository to update the relevant part before or alongside your code PR.

1. Clone the repository:

   gh repo clone google/adk-python -- -b v2
   cd adk-python

2. Install uv:

   Check out uv installation guide.

3. 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-uv

   Optionally, install Google's addlicense tool for license header checks (requires Go):

   go install github.com/google/addlicense@latest

   If 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 install

   The pre-commit hooks run isort, pyink, addlicense, and mdformat automatically on each commit.

4. Create virtual environment and install dependencies:

   uv venv --python "python3.11" ".venv"
   source .venv/bin/activate
   uv sync --all-extras

5. Run unit tests locally (Fast):

   If you just want to run tests quickly while developing, run pytest:

   pytest ./tests/unittests

6. 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!)

7. 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

8. Build the wheel file:

   uv build

9. Test the locally built wheel file: Have a simple testing folder setup as mentioned in the quickstart.

   Then following below steps to test your changes:

   Create a clean venv and activate it:

   VENV_PATH=~/venvs/adk-quickstart

   command -v deactivate >/dev/null 2>&1 && deactivate

   rm -rf $VENV_PATH \
     && python3 -m venv $VENV_PATH \
     && source $VENV_PATH/bin/activate

   Install the locally built wheel file:

   pip install dist/google_adk-<version>-py3-none-any.whl

Contributing folder has resources that are helpful for contributors.

This repo includes built-in skills for AI coding agents (Antigravity, Gemini CLI, and others) to help with ADK development:

• setup-dev-env — Set up the local development environment: install dependencies, configure pre-commit hooks, and verify the setup.

• 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-workflow — Build graph-based workflow agents: function nodes, LLM agent nodes, edge patterns, routing, parallel processing (fan-out and ParallelWorker), human-in-the-loop, state management, and best practices. Includes reference docs and tested samples.

These skills are in .agents/skills/ and are automatically available when using compatible AI coding tools in this repo.

The AGENTS.md file provides additional project context that can be used as LLM input.