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

Deployment manifest

The deployment manifest AgentBreeder validates and deploys, schema versions 1 and 2: fields, examples and validate. It is not the 2.x agent.yaml format.

Alpha preview. This manifest is not the 2.x agent.yaml (see Legacy 2.x). It has no framework, prompt, RAG or orchestration fields: your container supplies the agent's behaviour. To describe an agent instead, write an agent.yaml, which build turns into this manifest.

Fields

FieldContract
schema_versionRequired: 1 or 2. Operator enforce mode requires 2 to deploy
nameRequired lowercase DNS label, 1–63 characters
imageRequired image reference ending in @sha256: plus 64 lowercase hex characters, or a local-only sha256:<64 hex> image ID
targetlocal (default) or kubernetes (a local kind cluster only; see Kubernetes on kind)
portInteger 1–65535; default 8080
health_pathAbsolute HTTP path (letters, digits, /, _, -); default /health; no query string
secretsOptional map of uppercase environment names to secret://name references; no literal values. Locally, each value is read from a secret file and mounted read-only at /run/secrets/<name> with <ENV>_FILE set
model_accessOptional: {gateway, aliases, budget_usd?, rpm?}. The operator environment must grant the gateway, every alias and the limits, or the gate denies the deploy (no audit-mode override). With a gateway master key, deploy mints a LiteLLM virtual key for each container generation, limited to the aliases and the fallbacks the environment grants for them, and revokes it on remove. agentbreeder build writes this block
mcp_accessOptional, needs model_access: [{ref: mcp/<name>@X.Y.Z, tools: [...]}]. The environment must grant every tool to the agent (MCP_TOOL_NOT_GRANTED). Deploy mints a relay token per container generation. Refused with runtime_enforcement: mcp_http (MCP_RELAY_UNSUPPORTED); see MCP tools
guardrailsOptional, needs model_access: up to 10 agent guardrail names the environment offers (GUARDRAIL_UNDEFINED otherwise). Deploy attaches them to the deployment's gateway key; see Guardrails
identityv2, required: provider (operator connection name), ref (provider-specific immutable ID), environment, optional expect_owner. A reference only; AgentBreeder never creates identities
requires.rolesv2: list of {authority, resource, role_id} immutable IDs that must already be granted
requires.groupsv2: list of {authority, group_id} stable IDs
requires.attributesv2: map of namespace/name to an exact required value
capabilitiesv2: tools: [{mcp: https://…, actions: [...]}] and approval_required. A deploy-time ceiling; enforced per call only when the operator turns on runtime enforcement
policy.restrictionsv2: operator-approved restriction bundle IDs. They can only restrict

Input must be a single UTF-8 YAML mapping of at most 64 KiB. Unknown fields, duplicate keys, aliases/anchors and wrong types are rejected.

Nothing in the manifest can grant a permission, select the baseline policy, choose the enforcement mode or create an environment. Those belong to the operator configuration.

Examples

schema_version: 1
name: support-agent
image: registry.example.com/support@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
target: local
port: 8080
health_path: /health
schema_version: 2
name: refund-agent
image: registry.example.com/refund@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
target: local
identity:
  provider: corp
  ref: 4f1c2b7e-0000-4000-8000-000000000001
  environment: prod
  expect_owner: alice@example.com
requires:
  roles:
    - {authority: tenant-id, resource: payments-api-id, role_id: refunds-role-id}
  groups:
    - {authority: tenant-id, group_id: finance-group-id}
  attributes:
    acme-governance/data_classification: confidential
policy:
  restrictions: [pci]

Validate

.venv/bin/agentbreeder validate agent.yaml          # exit 0 valid, 2 invalid
.venv/bin/agentbreeder validate agent.yaml --json   # normalized output

Validation doesn't deploy anything or check that the image or secrets exist.

Canonical reference: docs/manifest.md and its JSON Schema.

On this page