GitHub - RazvanMaftei9/agentfab: A distributed AI platform enabling multi-agent orchestration

A distributed platform where specialized AI agents collaborate through task graphs, persistent knowledge, and bounded review loops. Define agents in YAML with their own model, tools, and knowledge. agentfab decomposes requests into a DAG, schedules agents in parallel, runs review loops with hard caps, persists state through a durable control plane, and sandboxes shell commands at the OS level.

For a full breakdown and demos, see: https://razvanmaftei.me/article?slug=agentfab-stateful-multi-agent-orchestration

Quick Start

make build
agentfab init
agentfab run

Type your project idea at the prompt. agentfab decomposes it into a task graph, dispatches specialist agents, and writes artifacts under the data directory.

Fabrics

agentfab uses fabrics made up of a Conductor plus whatever specialist agents you configure. The Conductor is always present for decomposition and orchestration. Every other agent is defined in YAML, per project.

agentfab init creates a default fabric with conductor, architect, designer, and developer. Replace them or add your own.

Custom Agents

Compile Markdown descriptions into YAML:

mkdir agents
# write agents/security-auditor.md, agents/api-designer.md, etc.
agentfab agent compile --input ./agents --output ./agents
agentfab run

Or write YAML directly:

name: "security-auditor"
purpose: "Audit code for vulnerabilities and compliance"
capabilities: ["security_analysis", "compliance_check"]
model: "anthropic/claude-sonnet-4-5-20250929"
escalation_target: "architect"
tools:
  - name: semgrep
    command: "semgrep --config auto $ARGS"
    mode: live
verify:
  command: "cd $SCRATCH_DIR && semgrep --config auto --error . 2>&1"
  max_retries: 2

Runtime Modes

Local mode

All agents run in one process with in-memory transport. This is the fastest dev loop and the default for editing YAML, prompts, and tools.

External-node mode

agentfab run --external-nodes

The Conductor, the control-plane service, and one or more node hosts run as separate processes. They can live on separate machines. This is the deployment shape agentfab targets for VMs, containers, and Kubernetes clusters.

What you get:

• mTLS everywhere. All gRPC traffic uses workload certificates issued by the configured identity provider. Local development uses a built-in provider; production uses a mounted external provider (SPIFFE, corporate CA, or similar).
• Authenticated node enrollment. Node hosts present an enrollment token plus measured claims (bundle digest, profile digests, binary digest) at registration. The control-plane API validates attestation; the node does not self-authorize.
• Durable control plane. A Conductor leader lease, per-task leases, and request and task records persist through a file backend or etcd. Restarting the Conductor does not lose in-flight state.
• Control-plane discovery. Instance endpoints resolve through the control plane's registry. Node hosts update it as they bring up hosted instances.
• Recovery without duplicate execution. When a node host dies, stale heartbeats mark its records unavailable and task leases release. The scheduler redispatches affected tasks to another healthy instance, and the task lease prevents two instances from running the same task.
• Signed, version-matched fabrics. Bundle and per-profile digests are enforced at admission. A node cannot join with a different agent set than the active fabric, and signed bundles can be required through trusted operator keys.

Fast local path (no extra config required):

# auto-bootstraps a local control-plane service and one local node host
agentfab run --external-nodes

# spin up more local node hosts under the same command
agentfab run --external-nodes --bootstrap-nodes 3

For the manual production-like setup (separate control-plane, Conductor, and node host processes, optional etcd backend, enrollment tokens, signed bundles), see Runtime Modes.

CLI

Key run flags: --debug, --external-nodes, --bootstrap-nodes N, --skip-verify, --data-dir <dir>, --listen <addr>, --control-plane-address <addr>.

Providers

agentfab uses Eino adapters:

Each agent can use a different provider.

Requirements

Go 1.24+.

Docs

• Architecture
• Runtime Modes
• Orchestration Internals
• Storage Architecture
• Identity Architecture
• Production Identity Deployment
• Roadmap
• Glossary

License

MIT