How-To Guide

Recipes for everything that isn't covered by agentbreeder quickstart. Each section is self-contained.

Install

We recommend pipx — it installs agentbreeder into an isolated environment and puts the executable on your PATH automatically:

pipx install agentbreeder            # full CLI + API server + engine
pipx install agentbreeder-sdk        # lightweight SDK only (uncommon — usually you want the full install)

No pipx? Use the standard installer instead:

python3 -m pip install agentbreeder          # works regardless of whether pip / pip3 is on PATH
python3 -m pip install agentbreeder-sdk

Requires Python 3.11+. brew and npx support coming soon. macOS users hitting command not found — see Troubleshooting.

Configure a provider

v2 ships nine OpenAI-compatible providers as catalog presets — Nvidia NIM, OpenRouter, Moonshot/Kimi, Groq, Together, Fireworks, DeepInfra, Cerebras, Hyperbolic. To use any of them you only need an API key.

agentbreeder provider list
agentbreeder secret set NVIDIA_API_KEY
agentbreeder provider test nvidia

model:
  primary: nvidia/meta-llama-3.1-405b-instruct
  fallback: groq/mixtral-8x7b-32768

For private/self-hosted endpoints (vLLM, internal mirrors), add a user-local entry:

agentbreeder provider add my-vllm \
  --type openai_compatible \
  --base-url https://vllm.internal/v1 \
  --api-key-env COMPANY_VLLM_KEY

Full reference — Providers · Gateways · Secrets.

Manage secrets

Secrets are bound to the workspace, not env vars. Default backend: OS keychain locally, AWS Secrets Manager / Vault for cloud and team installs.

agentbreeder secret set OPENAI_API_KEY    # prompted; never echoed
agentbreeder secret list                  # values are NEVER printed
agentbreeder secret rotate OPENAI_API_KEY
agentbreeder secret sync --target gcp     # mirror to cloud-native store

agentbreeder deploy automatically mirrors deploy.secrets: into the target cloud's secret store under agentbreeder/{agent}/{secret}, grants the runtime SA scoped read access, and wires the env. Plaintext never lives on disk. Full reference — Secrets.

Scaffold a new agent

agentbreeder init runs an interactive wizard. The Claude Code skill /agent-build adds a guided advisory experience with two paths:

• Fast Path — six questions, then scaffold (you know your stack)
• Advisory Path — describe your use case; it recommends framework, model, RAG, memory, MCP, deploy, evals — with reasoning — before scaffolding

Install /agent-build as a Claude Code plugin:

claude plugin marketplace add agentbreeder/agentbreeder
claude plugin install agent-build@agentbreeder

Then run /agent-build in Claude Code. No AgentBreeder install needed — the skill generates a complete project you can deploy with agentbreeder deploy.

Both produce the same artifacts: agent.yaml, agent.py, tools/, requirements.txt, .env.example, Dockerfile, deploy/, criteria.md, README.md. Advisory adds memory/, rag/, mcp/servers.yaml, tests/evals/, ARCHITECT_NOTES.md, plus IDE context files (CLAUDE.md, AGENTS.md, .cursorrules, .antigravity.md).

cd my-agent/
agentbreeder validate
agentbreeder deploy --target local
agentbreeder chat

Chat to build (BYO Claude key)

AgentBreeder Studio includes a Chat to build tab at /agents/new that lets you describe your agent in plain language and have Claude generate a ready-to-deploy agent.yaml for you.

How it works:

1. Go to Studio → Agents → New agent (/agents/new).
2. Click the Chat to build toggle (top-right of the page header).
3. On first use, connect your Claude API key — it is stored in your workspace secrets backend under the key name AGENTBREEDER_CLAUDE_BUILDER_KEY (never in the database, never returned to the browser, never logged). Get a key at console.anthropic.com.
4. Describe what you want your agent to do. Claude asks a few focused questions (framework, model, deploy target) and then calls the submit_agent_spec tool to emit a structured spec.
5. The backend validates the spec against the agent.yaml JSON schema before showing it to you. A "Create agent" button appears only when the spec is valid.
6. Clicking Create agent runs the spec through the same POST /api/v1/agents/from-yaml path used by the form wizard — no shortcuts or schema bypasses.

Security notes:

• Your Claude API key is read server-side on every request from the workspace secrets backend. It is never sent from the browser to the chat endpoint.
• If the key is absent or invalid, the endpoint returns HTTP 400 with a clear "add your key" message — the provider is never constructed.
• The conversation is bounded: maximum 40 turns and 100 000 total characters.
• Claude's output (the agent spec) is always re-validated by validate_config_yaml() on the backend before valid: true is returned. Untrusted model output cannot bypass the schema.

Deploy to different targets

What's fully shipped today: Local, AWS ECS Fargate, GCP Cloud Run, and Azure Container Apps deploy with full governance parity (sidecar + secret mirroring); AWS App Runner is single-container (no sidecar, rejects guardrails:/secrets:); Kubernetes and Claude-managed are in flight. The canonical matrix is the deploy-target status table; per-target prereq checklists are in deployment.mdx.

Cloud auth is the standard CLI for each provider (gcloud auth login, aws configure, az login, kubectl context). Secrets named in deploy.secrets: must already exist in the target cloud's secret store — or use agentbreeder secret sync --target <cloud>.

Reference: GCP Cloud Run end-to-end

The microlearning-ebook-agent example ships a verified scripts/deploy_gcp.sh that automates the full chain — APIs, Artifact Registry, Secret Manager, Cloud Build, Cloud Run — in one command:

cd microlearning-ebook-agent/
./scripts/deploy_gcp.sh

Defaults: region us-central1, 2 GiB / 2 vCPU, scale 0 → 5, concurrency 10, port 8080, --allow-unauthenticated (auth happens at the agent layer via bearer token).

One-time IAM grants for the Cloud Build SA (<project-num>-compute@developer.gserviceaccount.com): roles/storage.objectViewer, roles/cloudbuild.builds.builder, roles/logging.logWriter, roles/secretmanager.secretAccessor.

Push prompts and tools to the registry

Agents reference prompts and tools from the registry instead of inlining them. Each entity is kebab-cased, versioned, and resolved at agent startup (file-first — local override always wins).

# 1. Auth (every /api/v1/* route is auth-gated)
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@company.com","password":"…"}'
export AGENTBREEDER_API_TOKEN=eyJ…

# 2. Push a prompt (semver auto-bumps on update)
agentbreeder registry prompt push prompts/system.md \
  --version 1.0.0 --team eng --description "..."

# 3. Push a tool — extension auto-detected
agentbreeder registry tool push tools/my_tool.py        # python:/abs/path
agentbreeder registry tool push tools/my_tool.ts        # node:/abs/path
agentbreeder registry tool push engine.tools.standard.web_search  # in-process

Verify in Studio at /prompts (with Test tab) and /tools (with Try it tab).

Run a registered tool

agentbreeder registry tool run web-search \
  --args '{"query":"What is RAG?","max_results":2}'

engine/tool_runner.py dispatches based on the endpoint field:

Standard library ships with web_search (Tavily) and markdown_writer.

Chat with a deployed agent

Three paths — all enforce a runtime bearer token (AGENT_AUTH_TOKEN). /health stays open; /invoke and /stream are gated.

agentbreeder registry agent invoke microlearning-ebook-agent \
  --input "What is your job?" \
  --endpoint https://<your-agent>.run.app \
  --token $AGENT_AUTH_TOKEN

curl -X POST https://<your-agent>.run.app/invoke \
  -H "Authorization: Bearer $AGENT_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":"What is your job?"}'

POST /api/v1/agents/{id}/invoke

Use different frameworks

Set framework: in agent.yaml. Each runtime auto-discovers your entrypoint.

Claude SDK — adaptive thinking + prompt caching

claude_sdk:
  thinking:
    type: adaptive    # activates thinking when beneficial
    effort: high      # "low" | "medium" | "high"
  prompt_caching: true   # cache system prompts ≥8 192 chars (Sonnet)

Google ADK — backends

google_adk:
  session_backend: vertex_ai      # or: memory | database
  session_db_url: ""              # required if backend=database (or DATABASE_URL)
  memory_service: vertex_ai_bank  # or: memory | vertex_ai_rag
  artifact_service: gcs
  gcs_bucket: my-bucket

CrewAI — hierarchical process

from crewai import Crew, Process
crew = Crew(agents=[analyst], tasks=[task], manager_agent=manager,
            process=Process.hierarchical)

Stream responses

Every deployed agent exposes /stream as Server-Sent Events.

curl -N -X POST https://<agent>/stream \
  -H "Content-Type: application/json" \
  -d '{"input": "Write a report on renewable energy"}'

import httpx, json
with httpx.stream("POST", "https://<agent>/stream", json={"input": "..."}) as r:
    for line in r.iter_lines():
        if line.startswith("data: "):
            data = line[6:]
            if data == "[DONE]": break
            event = json.loads(data)
            if "text" in event: print(event["text"], end="", flush=True)

Use local models with Ollama

agentbreeder quickstart installs Ollama and pulls gemma3 automatically. Manually:

brew install ollama
ollama serve &
ollama pull gemma3      # or: llama3.2, mistral, phi4-mini, qwen2.5

model:
  primary: ollama/gemma3
  gateway: ollama

No data leaves the machine.

Route through the model gateway

AgentBreeder ships a self-hosted LiteLLM proxy at :4000 that adds budget enforcement, PII guardrails, Redis caching, and live spend tracking.

model:
  primary: claude-sonnet-4
  fallback: gpt-4o
  gateway: litellm

When active: every LLM call routes through the proxy with the agent's scoped virtual key; cost is tracked per agent and per team in the Costs page of Studio.

Secrets backends

Agents reference secrets by name regardless of backend.

echo 'OPENAI_API_KEY=sk-...' >> .env

deploy:
  secrets: [OPENAI_API_KEY]

agentbreeder secret set OPENAI_API_KEY --backend aws --value sk-...

agentbreeder secret set OPENAI_API_KEY --backend gcp --value sk-...

agentbreeder secret set OPENAI_API_KEY --backend vault --value sk-...

Orchestrate multiple agents

# orchestration.yaml
name: support-pipeline
strategy: router
team: customer-success
agents:
  triage:
    ref: agents/triage-agent
    routes:
      - { condition: billing,   target: billing }
      - { condition: technical, target: technical }
      - { condition: default,   target: general }
  billing:   { ref: agents/billing-agent }
  technical: { ref: agents/technical-agent }
  general:   { ref: agents/general-agent }
shared_state: { type: session_context, backend: redis }
deploy: { target: local }

agentbreeder orchestration deploy orchestration.yaml
agentbreeder orchestration chat support-pipeline

Programmatic equivalent: see Full Code →.

Use the Python SDK

from agenthub import Agent

agent = (
    Agent("support-agent", version="1.0.0", team="engineering")
    .with_model(primary="claude-sonnet-4", fallback="gpt-4o")
    .with_tools(["tools/zendesk-mcp", "tools/order-lookup"])
    .with_prompts(system="prompts/support-system-v3")
    .with_deploy(cloud="gcp", min_scale=1, max_scale=10)
)
agent.to_yaml("agent.yaml")
agent.deploy()

Full reference: Full Code →.

Migrate from another framework

Wrap existing code in agent.yaml without rewriting it.

Eject between tiers

agentbreeder eject my-agent --to code    # YAML → Python/TS SDK
agentbreeder eject my-agent --to yaml    # Visual builder → YAML

agent.yaml is preserved. No Code → Low Code → Full Code, no lock-in.

MCP, RBAC, costs, git, evals, templates, teardown

# MCP
agentbreeder scan                        # discover servers
agentbreeder list tools

# Costs
agentbreeder list costs --group-by team  # also: --group-by agent | model

# Git workflow
agentbreeder submit agent.yaml --title "..."
agentbreeder review approve 42
agentbreeder publish 42

# Evals
agentbreeder eval run --agent support-agent --dataset tests.json
agentbreeder eval results --agent support-agent

# Templates
agentbreeder template use customer-support --name my-agent
agentbreeder template create --from agent.yaml --name "My Template"

# Teardown
agentbreeder teardown support-agent [--force]

RBAC is enforced at deploy time and cannot be bypassed:

team: customer-success
owner: alice@company.com
access:
  visibility: team           # public | team | private
  allowed_callers: [team:engineering, team:customer-success]
  require_approval: false

Full lifecycle for each: MCP Servers · Evaluations.

CI/CD

The rajits/agentbreeder-cli Docker image is the recommended way to run AgentBreeder in pipelines.

# .github/workflows/deploy-agent.yml
name: Deploy Agent
on:
  push:
    paths: ['agents/support-agent/**']
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: docker run --rm -v $PWD:/work -w /work rajits/agentbreeder-cli validate agents/support-agent/agent.yaml
      - run: docker run --rm -v $PWD:/work -w /work -e GOOGLE_APPLICATION_CREDENTIALS=/work/sa.json rajits/agentbreeder-cli deploy agents/support-agent/agent.yaml --target cloud-run

deploy-agent:
  image: rajits/agentbreeder-cli:latest
  script:
    - agentbreeder validate agents/support-agent/agent.yaml
    - agentbreeder deploy agents/support-agent/agent.yaml --target cloud-run

Run the platform with Docker Compose

agentbreeder studio is the fastest path — pulls pre-built images and opens http://localhost:3001. Or run compose directly:

# Standalone — no repo clone
curl -O https://raw.githubusercontent.com/agentbreeder/agentbreeder/main/deploy/docker-compose.standalone.yml
docker compose -f docker-compose.standalone.yml up -d

# From source
docker compose -f deploy/docker-compose.yml up -d

Default login: admin@agentbreeder.local / plant. Studio and agentbreeder login both force a password rotation on first sign-in (the default is publicly documented).

Networking from inside a container

localhost inside a container is the container itself. To reach the AgentBreeder API from a deployed agent:

Troubleshooting