Alpha preview: pin 3.0.0a3 when you install. A bare pip install agentbreeder still installs the unmaintained 2.x: known issues.
agentbreeder

Install

Install the AgentBreeder 3.0.0a3 preview from PyPI or npm with an exact version pin, and see what has been verified on macOS and Linux.

Always pin the version

3.0.0a3 is an alpha preview. A bare pip install agentbreeder, uvx agentbreeder or pipx run agentbreeder installs 2.7.3, which is unmaintained and has known functional and security issues (see Legacy 2.x). 3.x is a rebuild: no 2.x command, config or data carries over.

Requirements

  • macOS (verified end to end) or Linux (install, --version and doctor only, on 3.0.0a3; see what has been verified). Windows is not supported.
  • A running Docker engine with a local context.
  • For pip: Python 3.11 or newer.
  • For uvx: uv 0.11.6 or newer.
  • For npx: Node.js 18 or newer, and uv 0.11.6 or newer.

Install and run the demo

Pick one path. Each runs the same PyPI release.

pip, in a virtual environment
python3 -m venv .venv
.venv/bin/python -m pip install "agentbreeder[eval]==3.0.0a3"
.venv/bin/agentbreeder quickstart
uvx
uvx --from "agentbreeder[eval]==3.0.0a3" agentbreeder quickstart
npx
npx agentbreeder@3.0.0-alpha.3 quickstart

The npm package is a launcher with no Python code of its own. It runs the pinned PyPI release through uvx, and exits with install guidance if uvx is missing.

quickstart builds a sample image, deploys it through a demo identity gate, invokes it, retries the same deployment, checks the saved history and removes the container. It needs no model account or API key. The sample echoes JSON; it is not an AI agent. Add --dry-run to run doctor and validate the sample without building or deploying anything. If it stops, run agentbreeder doctor first.

Run more commands

npx and uvx run the CLI without installing an agentbreeder command. After either, a bare agentbreeder is either not found or an older install. Repeat the prefix for every command (npx agentbreeder@3.0.0-alpha.3 up), or install the command with uv:

uv tool install "agentbreeder[eval]==3.0.0a3"
agentbreeder --version   # 3.0.0a3

This puts agentbreeder in uv's executable directory (~/.local/bin in our run), which must be on your PATH ahead of any older install. uv tool uninstall agentbreeder removes it. Run on macOS in a clean sandbox: on 3.0.0a3 (2026-11-16), --version and doctor (which warns until uv's executable directory is on your PATH); on 3.0.0a2 (2026-11-11), --version, doctor and a real quickstart (5/5). up and Northwind have not been run this way.

An older agentbreeder on your PATH

If a bare agentbreeder fails with ModuleNotFoundError: No module named 'cli', or does not report 3.0.0a3, an older install comes first on your PATH:

  1. which -a agentbreeder lists every copy, in PATH order.
  2. Run each one by its full path with --version. The one that fails or reports another version is the old one; leave the 3.0.0a3 copy alone.
  3. Remove the old one with the tool that installed it: pipx uninstall agentbreeder, brew uninstall agentbreeder, or for a pip install PYTHON -m pip uninstall agentbreeder, where PYTHON is the interpreter on the first line of that script. If pip says it is not installed (a leftover from a deleted editable install), delete that script file.
  4. Run hash -r or open a new shell.

Try Northwind

Northwind is a customer support agent built from an agent.yaml. It needs GEMINI_API_KEY and TAVILY_API_KEY, in the environment or in an env file. These commands need agentbreeder on your PATH: after the pip install above, run export PATH=$PWD/.venv/bin:$PATH first, or use uv tool install (Run more commands).

agentbreeder example northwind   # copies it to ./northwind
cd northwind
agentbreeder services up --environment dev --env-file ~/.env --yes
agentbreeder release agent.yaml --stack . --environment dev

With uvx or npx, replace agentbreeder with uvx --from "agentbreeder[eval]==3.0.0a3" agentbreeder or npx agentbreeder@3.0.0-alpha.3. On 3.0.0a3 these CLI commands ran from the pip install (61/61, a live invoke, full teardown); through uvx and npx they have not been run. On 3.0.0a2, Northwind ran through the command center instead, started with npx and driven by a script through its API, with no browser.

To use the command center, run npx agentbreeder@3.0.0-alpha.3 up and follow the steps in the browser; see Local command center.

To tear it down, run agentbreeder remove ID --local --stack ., then agentbreeder services down --purge --yes. See Backing services and Build from agent.yaml.

What has been verified

3.0.0a3, installed from the public registries on 2026-11-16:

pipuvxnpx
macOS: real quickstart (5/5)PassedPassedPassed
macOS: Northwind through the CLI (services up, release 61/61, a live invoke, full teardown)PassedNot runNot run
macOS: agentbreeder up starts (scripted, no browser): one-time link redeemed, UI and API served, link reuse refusedNot runNot runPassed
macOS: Northwind through up, or a kind clusterNot runNot runNot run
Linux: install, --versionPassedPassedPassed
Linux: doctor passes every checkPassedRan, Docker unreachableRan, Docker unreachable
Linux: real quickstart or NorthwindNot runNot runNot run
  • Northwind runs on runtime/adk@1.3.0. The new agent starter's runtime/adk@1.4.0 was not part of this run.
  • On Linux, doctor passed every check on the pip path once the user could reach the Docker socket and Compose v2 was installed. On the uvx and npx paths it ran as a user without socket access, and reported Docker as unreachable; it was not rerun with access.
  • uv tool install on macOS: --version and doctor (doctor warned that agentbreeder was not on PATH, because uv's executable directory was not on it).
  • For a few minutes after the upload, uv reported that agentbreeder==3.0.0a3 did not exist while PyPI already listed it. It resolved on its own; if you see this right after a release, retry.

3.0.0a2, installed from the public registries on 2026-11-11:

pipuvxnpx
macOS: real quickstart (5/5)PassedPassedPassed
macOS: agentbreeder up starts, sign-in, UI servedNot runPassedPassed
macOS: Northwind through up's API (scripted, no browser): release 61/61, kind promote 61/61, full teardownNot runNot runPassed
Linux: anythingNot runNot runNot run

uv tool install on macOS, 2026-11-11: --version, doctor and a real quickstart (5/5); up and Northwind not run.

3.0.0a1, installed from the public registries on 2026-11-10:

pipuvxnpx
macOS: real quickstart (5/5)PassedPassedPassed
macOS: Northwind to 61/61, live /invoke, full teardownPassedNot runNot run
Linux: install, --version, doctorPassedPassedPassed
Linux: real quickstart or NorthwindNot runNot runNot run
  • macOS means macOS 13 with Docker Desktop, in a clean sandbox: a fresh HOME (with ~/.docker linked in for the Docker context), empty package caches and no checkout. Docker images and build layers on the host were not cleared.
  • Linux means Ubuntu 24.04 in a container, with Node 18.19.1.

For 3.0.0a3, the wheel and sdist on PyPI and the npm tarball are byte-identical to the ones attested by the release workflow. Installing from the hashed requirements file worked on macOS with pip and with uv pip (--version on both; doctor, every check passed, in the pip install).

For 3.0.0a2, the wheel and sdist on PyPI are byte-identical to the ones attested by the release workflow, and installing the wheel with pip from the hashed requirements file passed doctor and started up in the TestPyPI rehearsal on macOS (pip only; uv pip was not run on 3.0.0a2). For 3.0.0a1, the hashed install passed the install smoke test with pip and uv pip, on macOS from PyPI and on macOS and Ubuntu from TestPyPI.

How long it took

Measured once each on macOS, each path in its own clean sandbox (the 3.0.0a1 rows on 2026-11-10, the 3.0.0a3 rows on 2026-11-16). Docker images and build layers already on the machine were not cleared, so a first run on a new machine will take longer.

StepTime
Create a virtual environment and pip install (3.0.0a1)9 s
agentbreeder quickstart, cold sample build (3.0.0a1)62 s
quickstart including the install, Docker image cache not cleared (3.0.0a2: pip, uvx, npx)22 s, 9 s, 11 s
quickstart, Docker image cache not cleared (3.0.0a3): pip after a 10 s install; uvx and npx including the fetch15 s, 10 s, 12 s
Northwind: services up (5 services, 3.0.0a3, pip)245 s
Northwind: release (build, 61 evals, promote, 3.0.0a3, pip)277 s
Command center: start services (5 services, 3.0.0a2)162 s
Command center: release (build, 61 evals, promote, 3.0.0a2)189 s
Command center: connect a kind cluster, then start services again after the grant change (3.0.0a2)45 s + 12 s
Command center: promote to the cluster (push, deploy, 61 evals, 3.0.0a2)241 s
Command center: remove both deployments, the cluster and the services (3.0.0a2)57 s

Not measured: installing Docker, Python, uv or Node, or getting the API keys.

Install with hashes

The v3.0.0a3 GitHub release carries requirements-3.0.0a3.txt, with a hash for every package, and a SHA256SUMS file.

uv pip install --require-hashes -r requirements-3.0.0a3.txt
# or
pip install --require-hashes -r requirements-3.0.0a3.txt

Neither uvx nor npx enforces hashes. The npx launcher bounds what resolves with --exclude-newer and a constraints file. The uvx command above pins only agentbreeder itself, so its dependencies resolve to the newest versions allowed. On both paths, your uv index settings decide where the packages come from.

Install from a checkout

Use a fresh virtual environment: an older install can expose the 2.x CLI.

git clone https://github.com/agentbreeder/agentbreeder.git
cd agentbreeder
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'

Using 2.x

If you need 2.x, pin agentbreeder<3 and read Legacy 2.x first. There is no migration path between 2.x and 3.x.

On this page