Agent Executor (AX) is Google's open agentic orchestration runtime
How to Contribute
We welcome contributions to AX!
Before You Begin
Sign our Contributor License Agreement
All submissions to this project need to follow Google’s Contributor License Agreement (CLA), which covers any original work of authorship included in the submission. This doesn't prohibit the use of coding assistance tools, including tool-, AI-, or machine-generated code, as long as these submissions abide by the CLA's requirements.
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 sign a new one.
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 GitHub Help for more information on using pull requests.
Every pull request to main needs one approving review and a passing build-and-test check before it can be merged. A push after an approval needs a fresh approval.
When you start on an issue or pull request, assign yourself to it, so others know it is being worked on.
Merging
- Pull requests from project members: The author merges once the pull request is approved and CI is green. The author knows when a change is ready, and is the one who rebases when pull requests have to land in order.
- Pull requests from external contributors: The reviewer who approves also merges, since external contributors cannot merge.
Development Workflow
Prerequisites
- Go 1.27+
ko(for building and deploying control plane images)- Docker or Podman (for building the Linux task-runner container image)
- A Kubernetes cluster with Agent Substrate installed
Building Binaries
Build all local binaries (bin/ax, bin/ax-server):
make build
Or install the ax CLI directly into $(go env GOPATH)/bin:
make install
Make sure that $(go env GOPATH)/bin is on your $PATH:
export PATH="$PATH:$(go env GOPATH)/bin"
Running Tests
Run all unit and integration tests (including the mock Substrate gRPC server and API server tests):
make test
Or run via go test:
go test -v ./...
Building the Task Runner Image
Cross-compile the task runner for linux/amd64 and package the container image:
make build-task-runner
To build and push to a remote container registry:
make push-task-runner TASK_RUNNER_REPO=gcr.io/<your-project>/ax-task-runner
Deploying to Kubernetes
Deploy Redis and server components to your cluster in the ax-system namespace:
make deploy AX_IMAGE_REPO=gcr.io/<your-project>/ax-images
Creating a Pull Request
Fork and Clone the Repository: Fork google/ax on GitHub, then clone your fork. Replace
YOUR_USERNAMEwith your GitHub username:git clone [email protected]:YOUR_USERNAME/ax.git cd ax git remote add upstream [email protected]:google/ax.gitEnsure
mainis up to date:git fetch upstream git checkout main git merge --ff-only upstream/mainCreate a feature branch:
git checkout -b my-featureMake changes and verify:
- Run tests:
make test - Ensure clean modules:
go mod tidyand verify withgit diff --exit-code go.mod go.sum - Build binaries:
make build
- Run tests:
Commit and open a PR:
git add . git commit -m "feat: describe your changes" git push -u origin my-featureOpen a pull request from your fork's
my-featurebranch togoogle/ax'smainbranch, describing the motivation and changes.