Quickstart Guide

Get AgentBreeder running in under 5 minutes.

Prerequisites

Before you install, make sure you have:

Requirement	Min version	Why	How to get it
Python	3.11+	CLI, API server, Python SDK	python.org or `brew install python@3.11`
Docker	24+	`--target local` deploys and all container builds	docs.docker.com/get-docker
Node.js + npx	18+	MCP servers (most run via `npx`), TypeScript SDK	nodejs.org or `brew install node`
Ollama	any	Local model inference — only if you don't have cloud API keys	ollama.com
gcloud CLI	any	GCP Cloud Run deploys only	cloud.google.com/sdk
AWS CLI v2	2+	AWS ECS Fargate / App Runner deploys only	aws.amazon.com/cli
Azure CLI	any	Azure Container Apps deploys only	learn.microsoft.com

Minimum to get started

You only need Python 3.11+ and Docker to run the quickstart locally. Cloud CLIs, Node.js, and Ollama are only needed when you use those specific features.

Install

pip install agentbreeder

brew tap agentbreeder/agentbreeder
brew install agentbreeder

docker pull rajits/agentbreeder-cli

npm install @agentbreeder/sdk

import { Agent } from "@agentbreeder/sdk";

const agent = new Agent("my-agent", { version: "1.0.0", team: "eng" })
  .withModel({ primary: "claude-sonnet-4", fallback: "gpt-4o" })
  .withDeploy({ cloud: "aws", region: "us-east-1" });

agent.toYaml("agent.yaml");

git clone https://github.com/agentbreeder/agentbreeder.git
cd agentbreeder
python -m venv venv && source venv/bin/activate
pip install -e ".[dev]"

Verify:

agentbreeder --help

Create Your First Agent

agentbreeder init

The interactive wizard asks 5 questions:

Framework — LangGraph, OpenAI Agents, Claude SDK, CrewAI, Google ADK, or Custom
Cloud target — Local, AWS, GCP, Azure, or Kubernetes
Agent name — lowercase with hyphens (e.g., support-agent)
Team — your team name
Owner email — who is responsible

It generates a ready-to-run project:

my-agent/
├── agent.yaml          # Configuration — the only file AgentBreeder needs
├── agent.py            # Working agent code for your chosen framework
├── requirements.txt    # Python dependencies
├── .env.example        # Environment variable template
└── README.md           # Getting started guide

Validate

cd my-agent
agentbreeder validate agent.yaml

This runs three checks:

YAML syntax — is the file valid YAML?
JSON Schema — do all fields match the agent.yaml spec?
Semantic validation — is the framework supported? Is the team valid?

Deploy Locally

agentbreeder deploy agent.yaml --target local

This triggers the 8-step atomic pipeline:

✅  YAML parsed & validated
✅  RBAC check passed
✅  Dependencies resolved
✅  Container built (langgraph runtime)
✅  Deployed to Docker Compose
✅  Health check passed
✅  Registered in org registry
✅  Endpoint returned

If any step fails, the entire deploy rolls back. No partial deploys.

Verify It's Running

# Check deploy status
agentbreeder status

# Tail the logs
agentbreeder logs my-agent --follow

# Chat with your agent
agentbreeder chat my-agent

Deploy to the Cloud

All cloud targets use the same agent.yaml. Only the --target flag changes.

# GCP Cloud Run (serverless)
agentbreeder deploy agent.yaml --target cloud-run --region us-central1

# AWS ECS Fargate
agentbreeder deploy agent.yaml --target ecs-fargate --region us-east-1

# AWS App Runner (serverless — no VPC or ALB needed)
agentbreeder deploy agent.yaml --target app-runner --region us-east-1

# Azure Container Apps
agentbreeder deploy agent.yaml --target container-apps

# Kubernetes (EKS / GKE / AKS / self-hosted)
agentbreeder deploy agent.yaml --target kubernetes

# Anthropic Claude Managed Agents (no container build)
agentbreeder deploy agent.yaml --target claude-managed

For cloud: aws targets, set the following in deploy:

deploy:
  cloud: aws
  runtime: app-runner      # or: ecs-fargate
  env_vars:
    AWS_ACCOUNT_ID: "123456789012"
    AWS_REGION: us-east-1

For cloud: claude-managed, add an ANTHROPIC_API_KEY secret and an optional claude_managed: block:

deploy:
  cloud: claude-managed
  secrets:
    - ANTHROPIC_API_KEY

claude_managed:
  environment:
    networking: unrestricted
  tools:
    - type: agent_toolset_20260401

Add MCP Servers

AgentBreeder has first-class support for Model Context Protocol (MCP) servers. Discover available servers on your machine:

agentbreeder scan

Then wire them into your agent:

# agent.yaml
tools:
  - ref: tools/zendesk-mcp       # from org registry
  - ref: tools/order-lookup

Every MCP server is deployed as a sidecar alongside your agent — no extra config required.

Add RAG / Knowledge Bases

Connect vector or graph knowledge bases in one line:

# agent.yaml
knowledge_bases:
  - ref: kb/product-docs
  - ref: kb/return-policy

AgentBreeder supports vector search, graph search, and hybrid search. See RAG Guide for indexing your own data.

Version Your Prompts

Reference versioned prompts from the org registry instead of hardcoding strings:

# agent.yaml
prompts:
  system: prompts/support-system-v3

This enables prompt caching, A/B testing, and rollback without redeploying the agent.

Connect Agents (A2A)

Agents can call each other using the built-in Agent-to-Agent (A2A) protocol over JSON-RPC:

# agent.yaml — declare which agents this one is allowed to call
access:
  allowed_callers:
    - team:engineering
    - team:customer-success

Use agentbreeder list to see all A2A-enabled agents in your org registry.

Three Ways to Build

AgentBreeder supports three builder tiers — all compile to the same agent.yaml and share the same deploy pipeline:

Tier	Who	How
No Code	PMs, analysts, citizen builders	Visual drag-and-drop canvas in the dashboard
Low Code	ML engineers, DevOps	Edit `agent.yaml` directly in any IDE
Full Code	Senior engineers, researchers	Python/TS SDK with full programmatic control

You can start in No Code and eject to YAML or full code at any time:

agentbreeder eject my-agent --to yaml      # No Code → Low Code
agentbreeder eject my-agent --to code      # Low Code → Full Code

Run the Full Platform Locally

If you want the dashboard, registry, and API server running locally:

git clone https://github.com/agentbreeder/agentbreeder.git
cd agentbreeder

python -m venv venv && source venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env

# Start postgres + redis + API + dashboard
docker compose -f deploy/docker-compose.yml up -d

Service	URL
Dashboard	http://localhost:3001
API	http://localhost:8000
API Docs	http://localhost:8000/docs

Default login:

Field	Value
Email	`admin@agentbreeder.local`
Password	`plant`
Role	Admin

Warning

Change the default password before exposing this to a network.

Use Local Models with Ollama

No cloud API keys? Use Ollama for fully local development:

# agent.yaml
model:
  primary: ollama/gemma4
  gateway: ollama

ollama serve &
ollama pull gemma4
agentbreeder deploy agent.yaml --target local

Other models supported: ollama/llama3, ollama/mistral, ollama/phi4, and any model available in the Ollama registry.

Next Steps

What	Where
All CLI commands	CLI Reference
Every agent.yaml field	agent.yaml Reference
MCP server setup	MCP Guide
RAG & knowledge bases	RAG Guide
Versioned prompts	Prompts Guide
Agent-to-agent calls	A2A Guide
Multi-agent pipelines	Orchestration Guide
Governance, RBAC, cost tracking	Governance Guide
Scheduled agent runs	Scheduling Guide
Evaluating agents	Eval Guide
Common workflows	How-To Guide
Migrate from another framework	Migration Guides

Quickstart

On this page