Deployment

Once your agent runs locally and is registered (prompts + tools + agent record), the deploy step packages the agent + the AgentBreeder runtime into a container, pushes it to your cloud's image registry, and rolls it out as a managed service with secrets and auth wired in.

AgentBreeder supports three clouds — AWS, GCP, and Azure — plus local Docker Compose for development. This page covers two verified end-to-end reference deploys — GCP Cloud Run and AWS ECS Fargate (with auto-provisioned RDS pgvector + ElastiCache) — and the same pattern applies to AWS App Runner and Azure Container Apps with the per-cloud user-input contract below.

User-input contract per cloud (BYO existing infra)

For each cloud, AgentBreeder needs a minimum set of inputs from you so it can deploy into your existing infrastructure. Two modes are supported:

• simple — account + region + credentials. AgentBreeder uses cloud defaults for the rest (cluster names, IAM roles, networking).
• full — describe every specific resource (cluster, subnets, IAM role, registry).

Both modes are served by two API endpoints:

# Fresh AWS account: just creds + region in agent.yaml — no BYO env_vars.
agentbreeder deploy agent.yaml --target ecs-fargate --provision --local

Calling validate-infra from your terminal

TOKEN=$AGENTBREEDER_API_TOKEN

curl -X POST http://localhost:8000/api/v1/deployments/validate-infra \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "engineering",
    "cloud": "aws",
    "region": "us-east-1",
    "mode": "simple",
    "fields": {
      "AWS_ACCOUNT_ID": "123456789012",
      "AWS_ACCESS_KEY_ID": "AKIA...",
      "AWS_SECRET_ACCESS_KEY": "..."
    }
  }'
# {"data":{"valid":true,"cloud":"aws","region":"us-east-1","checks":[...]},"errors":[]}

If a referenced resource is missing or you lack permission, the response carries a populated errors array and the individual check status (missing / forbidden / error) for each resource.

What the deploy script does

microlearning-ebook-agent/scripts/deploy_gcp.sh automates five stages:

Total: ~5 minutes from scratch.

Prerequisites

# 1. Authenticate
gcloud auth login
gcloud auth application-default login

# 2. Set the target project
gcloud config set project <PROJECT_ID>

# 3. .env in your agent project with the runtime secrets
cat > microlearning-ebook-agent/.env <<EOF
GOOGLE_API_KEY=AIza...
TAVILY_API_KEY=tvly-...
AGENT_AUTH_TOKEN=$(openssl rand -hex 16)
EOF

One-time IAM grants

Cloud Build and Cloud Run both default to the same service account (<project-number>-compute@developer.gserviceaccount.com). You need four roles on it the first time you deploy from a project:

PROJECT=$(gcloud config get-value project)
SA="$(gcloud projects describe $PROJECT --format='value(projectNumber)')-compute@developer.gserviceaccount.com"

for role in \
  roles/storage.objectViewer \
  roles/cloudbuild.builds.builder \
  roles/logging.logWriter \
  roles/secretmanager.secretAccessor
do
  gcloud projects add-iam-policy-binding "$PROJECT" \
    --member="serviceAccount:$SA" --role="$role" --condition=None
done

CLI: --remote vs --local

agentbreeder deploy runs in one of two modes:

• Remote (production) — POSTs /api/v1/deploys against $AGENTBREEDER_URL. The bearer token comes from agentbreeder login (OS keychain) or $AGENTBREEDER_API_TOKEN. Team-scoped RBAC, audit logging, and team-scoped cloud credentials are all enforced.
• Local (dev / offline) — runs the deploy engine in-process. Bypasses every server-side gate; intended for laptop development and the local Docker Compose target.

# Production — talks to the API
export AGENTBREEDER_URL=https://api.example.com
agentbreeder login
agentbreeder deploy ./agent.yaml --target cloud-run    # remote mode (auto)

# Force remote even without the env var
agentbreeder deploy ./agent.yaml --target cloud-run --remote

# Force local even when AGENTBREEDER_URL is set
agentbreeder deploy ./agent.yaml --target local --local

Mode resolution: --local wins over --remote wins over the env var. Without flags or env, the CLI defaults to local mode.

--remote is what makes the team-scope RBAC gate fire — without it, a developer with shell access + cloud creds can run the deploy engine in-process and skip the gate entirely. Production environments should set $AGENTBREEDER_URL so that agentbreeder deploy defaults to the gated path.

Run the deploy

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

The first run will print the public service URL when it's done:

════════════════════════════════════════════════════════════════
  Deployed: https://microlearning-ebook-agent-sizukgalta-uc.a.run.app
════════════════════════════════════════════════════════════════

What gets deployed

The container is built from microlearning-ebook-agent/Dockerfile.cloudrun, which bundles:

• The AgentBreeder engine (engine/, registry/, api/) — so engine.prompt_resolver and engine.tool_resolver can read the agent's registered prompts + tools at startup.
• The agent project (microlearning-ebook-agent/) including its agent.py, agent.yaml, local tools/ and prompts/ directories.
• The runtime wrapper (engine/runtimes/templates/google_adk_server.py) which serves /health, /invoke, /stream with bearer-token auth.

# Excerpt from Dockerfile.cloudrun
COPY engine /app/engine
COPY registry /app/registry
COPY api /app/api
COPY microlearning-ebook-agent /app/agent

ENV PYTHONPATH="/app:/app/agent"
WORKDIR /app/agent
CMD exec uvicorn engine.runtimes.templates.google_adk_server:app \
    --host 0.0.0.0 --port "${PORT:-8080}"

The .gcloudignore at the repo root keeps the build context lean — without it the source tarball is 578 MB (from venvs + worktrees + node_modules); with it the upload is 22 MB.

Cloud Run defaults

The deploy script picks production-friendly defaults you can override via env:

Verify the deploy

The deploy is bearer-gated at the agent layer. Use the same AGENT_AUTH_TOKEN you put in .env (now stored in Secret Manager):

URL=$(gcloud run services describe microlearning-ebook-agent \
  --region us-central1 --format='value(status.url)')
TOKEN=$(grep '^AGENT_AUTH_TOKEN=' microlearning-ebook-agent/.env | cut -d= -f2)

# /health is open by design (Cloud Run liveness probe)
curl $URL/health
# {"status":"healthy","agent_name":"microlearning-ebook-agent","version":"0.1.0"}

# /invoke is gated
curl -X POST $URL/invoke \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":"What is your job?"}'
# {"output":"My job is to turn any topic the user supplies into a polished
#           microlearning ebook a learner can complete in 20-40 minutes.",
#  "session_id":"...","metadata":null}

# Without the token → 401
curl -X POST $URL/invoke -d '{"input":"x"}' -H "Content-Type: application/json"
# {"detail":"Missing bearer token"}

Production checklist

AWS ECS Fargate — end-to-end (verified)

The GCP walkthrough above is mirrored here for AWS ECS Fargate, the full-governance AWS target (sidecar + cost/tracing). This path is verified against live AWS: a feature-rich agent — NVIDIA Llama-3.1-8B, a pgvector knowledge base, Redis-backed memory, and a web-search tool — deploys, serves, answers a multi-turn chat, and tears down with zero orphaned resources.

The agent

# agent.yaml
name: nvidia-support-agent
version: 0.1.0
framework: langgraph

model:
  primary: nvidia/meta/llama-3.1-8b-instruct   # called directly from AWS
  temperature: 0.3
  max_tokens: 1024

prompts:
  system: prompts/support-system               # registry-resolved at build

knowledge_bases:
  - ref: kb/validation-docs                     # → auto-provisions RDS pgvector
memory:
  backend: redis                                # → auto-provisions ElastiCache
  stores: [session-buffer]
tools:
  - ref: tools/web_search                       # first-party tool

deploy:
  cloud: aws
  runtime: ecs-fargate
  region: us-east-1
  scaling: { min: 1, max: 1, target_cpu: 70 }
  resources:
    cpu: "512"        # Fargate task CPU units — see note below
    memory: "1024"    # Fargate task memory, MiB
  env_vars:
    # BYO network the agent + its data stores join (existing infra):
    AWS_ACCOUNT_ID: "<account-id>"
    AWS_REGION: us-east-1
    AWS_VPC_SUBNETS: "subnet-aaaa,subnet-bbbb"
    AWS_SECURITY_GROUPS: "sg-agent"
    AWS_ECS_CLUSTER: agentbreeder-validation
    AWS_EXECUTION_ROLE_ARN: "arn:aws:iam::<account-id>:role/<exec-role>"
    AWS_TASK_ROLE_ARN: "arn:aws:iam::<account-id>:role/<task-role>"
    NVIDIA_API_KEY: "<nvapi-...>"               # injected at deploy
    LOG_LEVEL: info

Prerequisites

# 1. AWS credentials (default chain — env, ~/.aws/credentials, or instance profile)
aws sts get-caller-identity

# 2. A running local Docker daemon — the deployer builds + pushes the image
docker info >/dev/null    # must succeed

# 3. NVIDIA_API_KEY (or your model provider's key) available to the deploy

Plus the BYO AWS infra referenced in env_vars:

Run the deploy

cd nvidia-support-agent
agentbreeder deploy agent.yaml --target ecs-fargate

The deploy runs the standard 8-stage pipeline and prints the live endpoint:

╭────────────────────────────── Deployed ──────────────────────────────╮
│ Deploy successful!                                                    │
│   Agent:    nvidia-support-agent                                      │
│   Version:  0.1.0                                                     │
│   Endpoint: http://13.220.147.220:8080                               │
╰───────────────────────────────────────────────────────────────────────╯

The endpoint is the public IP of the running task's ENI (ECS Fargate has no stable DNS without an ALB, so the deployer reads the ENI's public IP and returns http://<public-ip>:8080). For a stable hostname + TLS, front the service with an Application Load Balancer.

What gets deployed (all related assets)

Each data store is tagged AgentBreeder=true so teardown can remove exactly what the deploy created and never touch your VPC, cluster, or roles.

Verify + chat

URL=http://13.220.147.220:8080

# /health is open (ECS health probe)
curl $URL/health
# {"status":"healthy","agent_name":"nvidia-support-agent","version":"0.1.0"}

# Chat — input is a message object; the response carries the model + tokens
curl -X POST $URL/invoke -H 'Content-Type: application/json' \
  -d '{"input":{"message":"Hi! What can you help me with?"}}'
# {"output":{"messages":[{"content":"What can I assist you with today?",
#   "response_metadata":{"model_name":"meta/llama-3.1-8b-instruct", ...}}]},
#  "thread_id":"6662..."}

# Multi-turn — pass the returned thread_id to use the Redis-backed memory
curl -X POST $URL/invoke -H 'Content-Type: application/json' \
  -d '{"input":{"message":"and what was my last question?"},"thread_id":"6662..."}'

Teardown (no orphans, no leaks)

Teardown is two complementary moves — compute/registry, then the auto-provisioned data tier:

# 1. Remove the ECS service, task definitions, and ECR repository
agentbreeder teardown --cloud aws --region us-east-1 --agent nvidia-support-agent

# 2. Remove the auto-provisioned data backends recorded in .agentbreeder/infra-state.json
#    (RDS + ElastiCache + their dedicated SGs, subnet groups, and the DB-password
#    secret) — ephemeral stores are destroyed fully, with no final snapshot to bill.
agentbreeder teardown nvidia-support-agent

Both are tag-gated: teardown refuses to delete anything not carrying AgentBreeder=true, so a drifted state file can never widen the blast radius to your own VPC or cluster.

Troubleshooting

Other deploy targets

The same agent.yaml deploys to other clouds with one-line changes:

# Cloud Run (default for GCP)
deploy:
  cloud: gcp
  runtime: cloud-run

# AWS ECS Fargate
deploy:
  cloud: aws
  runtime: ecs-fargate
  region: us-east-1

# AWS App Runner (zero-config alternative)
deploy:
  cloud: aws
  runtime: app-runner

# Azure Container Apps
deploy:
  cloud: azure
  runtime: container-apps

# Kubernetes (any conformant cluster)
deploy:
  cloud: kubernetes
  runtime: deployment

# Claude Managed Agents (Anthropic-hosted)
deploy:
  cloud: claude-managed

agentbreeder deploy reads the cloud + runtime fields and dispatches to the matching deployer in engine/deployers/. Each deployer has the same contract (build → push → provision → register), so the rest of the lifecycle is identical across targets.

See Architecture → Deploy Pipeline for the full flow.

Prerequisites per target (as of 2026-05-18)

Status reminder (v2.6.0): Local, AWS ECS Fargate, GCP Cloud Run, and Azure Container Apps deploy with full governance parity (sidecar + secret mirroring). Greenfield provisioning (creating the VPC/cluster/IAM from scratch) ships through the Studio deploy wizard today; the CLI --provision flag is on the roadmap, so CLI deploys currently require existing infra (plus auto-provisioned data backends). AWS App Runner is single-container — it deploys without a sidecar and rejects guardrails: / secrets: at validation. Kubernetes and Claude-managed are in flight (Kubernetes needs an existing cluster). This page is the canonical home of the per-target prerequisites; for the at-a-glance feature matrix see the deploy-target status table.

AWS ECS Fargate (--target ecs-fargate)

Full governance (sidecar + cost/tracing). For a fresh account, greenfield provisioning creates the ECS footprint from scratch via the Studio wizard (see the Greenfield mode AWS tab above; CLI --provision is on the roadmap). To deploy into existing infra from the CLI:

• AWS account ID and access credentials (Secrets Manager–backed AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY or an instance profile).
• VPC with at least two subnets across different AZs (private subnets recommended).
• Security group permitting the agent's listening port from your front-end / load balancer.
• ECS task execution IAM role with AmazonECSTaskExecutionRolePolicy.
• (Optional) ECR repository for image storage; AgentBreeder will use a public registry if none is configured.
• Region matches your deploy.region in agent.yaml.
• Secrets: AWS auto-mirror is on the roadmap — pre-create entries in AWS Secrets Manager and reference them by name in deploy.secrets:.

AWS App Runner (--target app-runner)

Single-container target. App Runner deploys without a sidecar, so it rejects guardrails: and secrets: at validate-infra. Use it for simple, zero-governance services; pick ECS Fargate when you need the sidecar.

• AWS account + credentials (same as ECS Fargate above).
• App Runner-permitted IAM role (AWSAppRunnerServicePolicyForECRAccess if pulling from ECR).
• Region selected in agent.yaml must support App Runner.
• No VPC required if using public access; for VPC connector mode, an existing VPC connector resource.

Azure Container Apps (--target container-apps)

Full governance (sidecar + cost/tracing) and secret auto-mirror to Azure Key Vault. For a fresh subscription, greenfield provisioning creates the Container Apps footprint from scratch via the Studio wizard (see the Greenfield mode Azure tab above; CLI --provision is on the roadmap). To deploy into existing infra from the CLI:

• Azure subscription ID and service-principal credentials (AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID).
• Resource group, pre-created — AgentBreeder will not create it for you.
• Container Apps Environment within that resource group.
• Container Apps-permitted role assignment for the service principal.
• (Optional) managed identity if the agent needs cross-resource access.

Kubernetes (--target kubernetes, EKS/GKE/AKS/self-hosted) — in flight

• Existing cluster (no provisioning) with kubectl access from your dev or CI environment.
• ~/.kube/config or KUBECONFIG pointing to the cluster.
• Namespace pre-created (default: agentbreeder).
• RBAC: a service account with permission to create Deployments, Services, ConfigMaps, and Secrets in that namespace.
• (Optional) an ingress controller and DNS records if you want external access.

Claude Managed Agents (--target claude-managed) — in flight

• Anthropic API key with managed-agents access enabled on your account.
• No infrastructure to provision — Anthropic hosts the runtime.
• Region and network constraints are dictated by Anthropic, not AgentBreeder.

Deploying from Studio

Studio's deploy wizard (Studio → Deploys → New deploy, route /deploy-wizard) is the graphical home of greenfield provisioning — and it handles existing accounts too. It is a 5-step flow:

1. Agent — pick a registered agent. The wizard auto-detects whether the agent requires approval (access.require_approval: true).
2. Target — choose cloud (AWS · ECS Fargate, GCP · Cloud Run, Azure · Container Apps) and region. A per-region cost estimate is shown inline (static client-side table, ±10%).
3. Infra — this is where you choose your starting point:
   • Bring your own infrastructure — enter your existing account fields (mode=simple or full from the contract above) and click Validate infrastructure. The wizard calls POST /api/v1/deployments/validate-infra (read-only) and shows a per-resource ✅/❌ checklist. You can't advance until validation passes.
   • Provision for me (greenfield, BETA) — a ResourcePreviewTree lists every resource AgentBreeder will create with a per-line and total monthly cost estimate. You must tick "I understand this creates cloud resources billable to my account" before advancing.
4. Config — env vars, secret references, scaling (min / max / target CPU %), and DB tier (shown only when the agent declares memory:).
5. Live deploy — submits POST /api/v1/deployments (with infra_mode set to byo or provision) and opens an SSE stream (GET /api/v1/deployments/{job_id}/stream) with six phase indicators: provisioning → building → pushing → deploying → health_checking → registering. On a greenfield run the provisioning phase streams each resource (VPC → subnets → NAT → cluster → IAM → RDS/ALB) as it is created.

What greenfield provisioning creates is exactly the per-cloud footprint in the Greenfield mode tables above — all tagged AgentBreeder=true so teardown can safely target only what it made.

If a greenfield deploy fails mid-provision, the wizard exposes a Roll back action that calls POST /api/v1/deployments/{job_id}/destroy-partial, which runs the provisioner's destroy() against whatever was recorded in the job's InfraState — no orphaned VPC, NAT, or RDS left billing.

Drafts auto-save to localStorage every 250ms (refresh-safe). Agents with access.require_approval: true route through the /approvals queue; the wizard polls until an admin approves, then switches to the SSE stream.

Related

• How-To → Deploy to GCP Cloud Run — the recipe-style version of this page
• Authentication — the auth model end-to-end (management API JWT + agent runtime bearer)
• CLI Reference → agentbreeder deploy — flags + alternatives
• Local Development — get to a working local build before you deploy