agent.yaml Reference

The agent.yaml file is the canonical configuration for an AgentBreeder agent. It defines everything needed to build, deploy, and govern an agent.

Minimal Example

name: my-agent
version: 1.0.0
team: engineering
owner: dev@company.com
framework: langgraph

model:
  primary: claude-sonnet-4

deploy:
  cloud: local

Complete Example

spec_version: v1

name: customer-support-agent
version: 1.0.0
description: "Handles tier-1 customer support tickets"
team: customer-success
owner: alice@company.com
tags: [support, zendesk, production]

framework: langgraph

model:
  primary: claude-sonnet-4
  fallback: gpt-4o
  gateway: litellm
  temperature: 0.7
  max_tokens: 4096

tools:
  - ref: tools/zendesk-mcp
  - ref: tools/order-lookup
  - name: search
    type: function
    description: "Search knowledge base"
    schema: {}

knowledge_bases:
  - ref: kb/product-docs
  - ref: kb/return-policy

prompts:
  system: prompts/support-system-v3

guardrails:
  - pii_detection
  - hallucination_check
  - content_filter
  - name: custom_check
    endpoint: https://guardrails.company.com/check

subagents:
  - ref: agents/billing-agent
    name: billing
    description: "Handles billing queries"

mcp_servers:
  - ref: mcp/zendesk
    transport: sse

deploy:
  cloud: gcp             # local | gcp | aws | azure | kubernetes | claude-managed
  runtime: cloud-run
  region: us-central1
  scaling:
    min: 1
    max: 10
    target_cpu: 70
  resources:
    cpu: "1"
    memory: "2Gi"
  env_vars:
    LOG_LEVEL: info
    ENVIRONMENT: production
  secrets:
    - ZENDESK_API_KEY
    - OPENAI_API_KEY

access:
  visibility: team
  allowed_callers:
    - team:engineering
    - team:customer-success
  require_approval: false

Field Reference

Top-Level Fields

Field	Type	Required	Description
`spec_version`	string	No	Schema version. Currently `v1`.
`name`	string	Yes	Agent name. Slug-friendly: lowercase alphanumeric and hyphens, 2–63 characters. Must start and end with alphanumeric.
`version`	string	Yes	Semantic version (`X.Y.Z`).
`description`	string	No	Short description, max 500 characters.
`team`	string	Yes	Owning team name.
`owner`	string	Yes	Email of the responsible engineer.
`tags`	string[]	No	Tags for discovery and search.
`framework`	string	Yes	Agent framework. See Framework values.

`framework`

One of:

Value	Framework	Runtime
`langgraph`	LangGraph	✅ Implemented
`openai_agents`	OpenAI Agents SDK	✅ Implemented
`crewai`	CrewAI	✅ Implemented
`claude_sdk`	Anthropic Claude SDK	✅ Implemented
`google_adk`	Google Agent Development Kit	✅ Implemented
`custom`	Any Python/TS agent	✅ Implemented

Framework-Specific Configuration

Each framework supports optional configuration under a top-level key matching the framework name. These keys are only read by the corresponding runtime.

`claude_sdk` — Anthropic Claude SDK

claude_sdk:
  thinking:
    type: adaptive          # "adaptive" (default) or "enabled"
    effort: high            # "low" | "medium" | "high" (default: "high")
  prompt_caching: true      # Enable prompt caching for long system prompts (default: false)

Field	Type	Default	Description
`thinking.type`	string	`"adaptive"`	Thinking mode. `"adaptive"` activates thinking when beneficial; `"enabled"` always activates.
`thinking.effort`	string	`"high"`	Thinking compute budget. Maps to `output_config.effort` in the API.
`prompt_caching`	boolean	`false`	Cache the system prompt via Anthropic's prompt caching API. Reduces latency and cost when the system prompt is reused across many requests. Minimum length thresholds: 8 192 chars for Sonnet models, 16 384 chars for others.

Environment variables injected by the runtime:

Variable	Description
`AGENT_MODEL`	Claude model ID (e.g., `claude-sonnet-4-6`)
`AGENT_MAX_TOKENS`	Max tokens for responses (default: `4096`)
`AGENT_SYSTEM_PROMPT`	System prompt injected at startup
`AGENT_TOOLS_JSON`	JSON array of tool definitions
`AGENT_THINKING_CONFIG`	JSON object with thinking configuration
`AGENT_PROMPT_CACHING`	`"true"` when prompt caching is enabled

`crewai` — CrewAI

crewai:
  # No additional configuration required.
  # AGENT_MODEL and AGENT_TEMPERATURE are injected automatically
  # from the top-level model: block.

The CrewAI runtime automatically injects AGENT_MODEL and AGENT_TEMPERATURE from the top-level model: block into every agent in the crew. Your crew.py does not need to read these environment variables — the runtime sets them on each agent.llm object at startup.

Environment variables injected by the runtime:

Variable	Description
`AGENT_MODEL`	LLM model name (propagated to each crew agent's LLM)
`AGENT_TEMPERATURE`	Sampling temperature (propagated to each crew agent's LLM)
`AGENT_TOOLS_JSON`	JSON array of tool definitions from the registry

The crew module must export either a crew attribute (a Crew instance) or a flow attribute (a Flow instance). Both sync and async (akickoff) crew execution are supported.

`google_adk` — Google Agent Development Kit

google_adk:
  session_backend: memory       # "memory" (default) | "database" | "vertex_ai"
  session_db_url: ""            # Required when session_backend is "database"
  memory_service: memory        # "memory" (default) | "vertex_ai_bank" | "vertex_ai_rag"
  artifact_service: memory      # "memory" (default) | "gcs"
  gcs_bucket: ""                # Required when artifact_service is "gcs"

Field	Type	Default	Description
`session_backend`	string	`"memory"`	Session storage backend. `"database"` requires `DATABASE_URL`. `"vertex_ai"` uses Vertex AI session service and requires `GOOGLE_CLOUD_PROJECT`.
`session_db_url`	string	—	PostgreSQL URL for database session storage. Falls back to `DATABASE_URL` env var.
`memory_service`	string	`"memory"`	Memory persistence service. `"vertex_ai_bank"` and `"vertex_ai_rag"` require `GOOGLE_CLOUD_PROJECT`.
`artifact_service`	string	`"memory"`	Artifact storage service. `"gcs"` requires a GCS bucket name.
`gcs_bucket`	string	—	GCS bucket name for artifact storage. Falls back to `GCS_ARTIFACT_BUCKET` env var.

Environment variables injected by the runtime:

Variable	Description
`AGENT_MODEL`	Gemini model ID (applied to `agent.model` at startup)
`AGENT_TEMPERATURE`	Sampling temperature (applied via `generate_content_config`)
`AGENT_MAX_TOKENS`	Max output tokens (applied via `generate_content_config`)
`AGENTBREEDER_ADK_CONFIG`	JSON blob of the `google_adk:` config block
`GOOGLE_CLOUD_PROJECT`	GCP project for Vertex AI services
`GOOGLE_CLOUD_LOCATION`	GCP region (default: `us-central1`)

The agent module must export one of: root_agent, agent, or app (a google.adk.agents.Agent instance). Alternatively, a root_agent.yaml file (ADK config-based agents) is supported as a fallback.

Streaming — `/stream` SSE Endpoint

All deployed agents expose a /stream endpoint alongside /invoke. The endpoint streams execution progress as Server-Sent Events.

Request: same body as /invoke

Response: text/event-stream

Framework	SSE events
Claude SDK	`data: {"text": "..."}` — one event per streamed text chunk
CrewAI	`event: step` with `{"description": "...", "result": "..."}` for each crew step; `event: result` with the final output
Google ADK	`data: {"text": "...", "is_final": false\|true}` — one event per ADK event

All streams terminate with data: [DONE].

Example (curl):

curl -N -X POST https://<agent-endpoint>/stream \
  -H "Content-Type: application/json" \
  -d '{"input": "Summarize this quarter'\''s results"}'

`model`

Model configuration for the agent's LLM.

Field	Type	Required	Description
`primary`	string	Yes	Primary model. Registry reference or `provider/model-id`.
`fallback`	string	No	Fallback model if primary is unavailable.
`gateway`	string	No	Model gateway (e.g., `litellm`). Defaults to org setting.
`temperature`	number	No	Sampling temperature, 0–2.
`max_tokens`	integer	No	Maximum tokens per response.

Gateway values:

Gateway	Description
`litellm`	Route through LiteLLM proxy
`ollama`	Route to local Ollama instance
(unset)	Direct provider call via the provider abstraction layer

The provider abstraction layer (engine/providers/) supports OpenAI and Ollama natively, with automatic fallback chains when fallback is specified.

Examples:

model:
  primary: claude-sonnet-4

model:
  primary: claude-sonnet-4
  fallback: gpt-4o
  gateway: litellm
  temperature: 0.7
  max_tokens: 4096

# Local development with Ollama
model:
  primary: ollama/llama3
  gateway: ollama

`tools`

List of tools and MCP servers available to the agent.

Each tool is either a registry reference or an inline definition:

tools:
  # Registry reference (recommended)
  - ref: tools/zendesk-mcp

  # Inline definition
  - name: search
    type: function
    description: "Search knowledge base"
    schema: {}

Field	Type	Required	Description
`ref`	string	No	Registry reference path.
`name`	string	No	Tool name (for inline definitions).
`type`	string	No	Tool type. Currently only `function`.
`description`	string	No	Tool description.
`schema`	object	No	OpenAPI-compatible schema.

`subagents`

List of subagent references for A2A (agent-to-agent) communication. Each reference auto-generates a call_{name} tool during dependency resolution.

subagents:
  - ref: agents/billing-agent
    name: billing
    description: "Handles billing queries"
  - ref: agents/tech-support

Field	Type	Required	Description
`ref`	string	Yes	Registry reference path to the subagent.
`name`	string	No	Display name (defaults to slug from ref).
`description`	string	No	Description of the subagent's purpose.

`mcp_servers`

List of MCP server references to deploy as sidecars alongside the agent.

mcp_servers:
  - ref: mcp/zendesk
    transport: sse
  - ref: mcp/slack
    transport: stdio

Field	Type	Required	Default	Description
`ref`	string	Yes	—	Registry reference path to the MCP server.
`transport`	string	No	`stdio`	MCP transport type: `stdio`, `sse`, `streamable_http`.

`knowledge_bases`

List of knowledge base references.

knowledge_bases:
  - ref: kb/product-docs
  - ref: kb/return-policy

Field	Type	Required	Description
`ref`	string	Yes	Registry reference path.

`prompts`

Prompt configuration.

# Registry reference
prompts:
  system: prompts/support-system-v3

# Inline
prompts:
  system: "You are a helpful customer support agent..."

Field	Type	Required	Description
`system`	string	No	System prompt — registry reference or inline string.

`guardrails`

List of guardrails to enforce on agent outputs. Can be built-in names or custom endpoints.

guardrails:
  - pii_detection           # Built-in
  - hallucination_check     # Built-in
  - content_filter          # Built-in
  - name: custom_check      # Custom
    endpoint: https://guardrails.company.com/check

Built-in guardrails:

Name	Description
`pii_detection`	Strips PII from outputs
`hallucination_check`	Flags low-confidence responses
`content_filter`	Blocks harmful content

Custom guardrails:

Field	Type	Required	Description
`name`	string	Yes	Guardrail name.
`endpoint`	string	No	URL of the guardrail service.

`deploy`

Deployment configuration.

Field	Type	Required	Default	Description
`cloud`	string	Yes	—	Target platform: `local`, `aws`, `gcp`, `azure`, `kubernetes`, `claude-managed`.
`runtime`	string	No	Per cloud	Deployment runtime. See defaults below.
`region`	string	No	—	Cloud region (e.g., `us-east-1`). Not used for `claude-managed`.
`scaling`	object	No	See below	Auto-scaling configuration. Not used for `claude-managed`.
`resources`	object	No	See below	CPU and memory allocation. Not used for `claude-managed`.
`env_vars`	map	No	—	Non-secret environment variables.
`secrets`	string[]	No	—	Secret references (from cloud secret managers).

Supported runtimes by cloud:

Cloud	Default Runtime	Other Runtimes	Notes
`local`	`docker-compose`	—	Requires Docker
`aws`	`ecs-fargate`	`app-runner`	App Runner = no VPC/ALB required
`gcp`	`cloud-run`	—	Scales to zero by default
`azure`	`container-apps`	—
`kubernetes`	`deployment`	`eks`, `gke`, `aks`	Bring your own cluster
`claude-managed`	(n/a)	—	No container built; Anthropic manages the runtime

`deploy.scaling`

Field	Type	Default	Description
`min`	integer	`1`	Minimum instances (0 = scale to zero).
`max`	integer	`10`	Maximum instances.
`target_cpu`	integer	`70`	CPU % threshold to trigger scaling (1–100).

`deploy.resources`

Field	Type	Default	Description
`cpu`	string	`"0.5"`	vCPU units.
`memory`	string	`"1Gi"`	Memory allocation.

`access`

Access control configuration. Optional — defaults to team's policy.

Field	Type	Default	Description
`visibility`	string	`team`	One of: `public`, `team`, `private`.
`allowed_callers`	string[]	—	Restrict who can call this agent (e.g., `team:engineering`).
`require_approval`	boolean	`false`	If true, deploys require admin approval.

`claude_managed`

Optional block read only when deploy.cloud: claude-managed. No container is built — Anthropic manages the runtime.

claude_managed:
  environment:
    networking: unrestricted    # unrestricted | restricted
  tools:
    - type: agent_toolset_20260401   # full built-in toolset (default)

Field	Type	Default	Description
`environment.networking`	string	`unrestricted`	Network access for the managed environment.
`tools`	object[]	See default	Tool definitions passed to the Anthropic Agent API.

Mapping from agent.yaml to the Anthropic Agent API:

`agent.yaml` field	Anthropic API field
`model.primary`	`model`
`prompts.system`	`system`
`claude_managed.tools`	`tools`
`name`	`name`

CLI Deploy Targets

The --target flag on agentbreeder deploy maps to cloud + runtime combinations:

agentbreeder deploy --target local           # Docker Compose (local)
agentbreeder deploy --target cloud-run       # GCP Cloud Run
agentbreeder deploy --target ecs-fargate     # AWS ECS Fargate
agentbreeder deploy --target app-runner      # AWS App Runner (no VPC/ALB)
agentbreeder deploy --target container-apps  # Azure Container Apps
agentbreeder deploy --target claude-managed  # Anthropic Claude Managed Agents

Validation

Validate your config without deploying:

agentbreeder validate ./agent.yaml

The JSON Schema is at engine/schema/agent.schema.json.

Name Constraints

Lowercase alphanumeric and hyphens only
Must start and end with an alphanumeric character
Length: 2–63 characters
Pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$

Valid: my-agent, customer-support-v2, data-monitor Invalid: -my-agent, My_Agent, a

agent.yaml Reference

On this page