Multi-Agentic BFT

Byzantine fault-tolerant coordination for multi-agent AI systems.

Multi-Agentic BFT is a Python library for coordinating three or more agents on a shared task when some agents may be unreliable, adversarial, low-confidence, or inconsistent. It implements leader election, quorum checks, solution/refinement rounds, and alpha/beta commit rules so a coordinator can reach a defensible result instead of blindly trusting one model or worker.

The project is motivated by AI security workflows where autonomous agents make high-impact decisions. In that setting, reliability requires quorum voting, traceable decisions, failure handling, and explicit behavior under disagreement.

What It Demonstrates

• Byzantine fault-tolerant quorum voting for multi-agent decisions
• Leader election and round-based solution/refinement phases
• Commit certificates for accepted consensus values
• Local mock agents and HTTP-backed remote workers
• OpenRouter-backed example clusters for LLM agent experiments
• Session tracing for debugging consensus behavior
• Production guardrails that block mock agents in production mode
• Stdlib-only runtime core

Protocol Shape

session_cfg + agent roster
        |
        v
roster validation
        |
        v
leader election
        |
        v
solution round
        |
        v
refinement round(s)
        |
        v
alpha/beta quorum commit
        |
        v
AegeanResult + optional commit certificate

Quick Start

python -m pip install -e ".[dev]"
python -m pytest tests -q

Run a local in-process consensus example:

python examples/consensus_entry.py

Run a local HTTP worker cluster:

python examples/simple_cluster.py

examples/simple_cluster.py can use OpenRouter-backed workers. Set OPENROUTER_API_KEY and optionally OPENROUTER_MODEL.

Minimal Usage

from aegean import AegeanConfig, EventBus, run_aegean_session
from aegean.mocks import ScriptedAegeanAgent

experts = ["a1", "a2", "a3"]

agents = {
    "a1": ScriptedAegeanAgent(soln="same", refm="same"),
    "a2": ScriptedAegeanAgent(soln="same", refm="same"),
    "a3": ScriptedAegeanAgent(soln="same", refm="same"),
}

session_cfg = {
    "session_id": "run-001",
    "pattern": "aegean",
    "experts": experts,
    "task": {
        "id": "t1",
        "description": "Question or decision for all agents.",
        "context": {},
    },
}

result = run_aegean_session(
    session_cfg,
    agents,
    config=AegeanConfig(max_rounds=5, alpha=2, beta=2),
    event_bus=EventBus(),
)

print(result.consensus_reached)
print(result.consensus_value)
print(result.commit_certificate)

HTTP Workers

The same coordinator can use remote workers:

from aegean import http_agents_from_endpoints

agents = http_agents_from_endpoints(
    {
        "worker-a": "10.0.0.11:8080",
        "worker-b": "10.0.0.12:8080",
        "worker-c": "https://10.0.0.13/custom",
    },
    execute_path="/execute",
    timeout_s=60.0,
)

Each worker implements:

POST /execute
body: {"task": <dict>, "agent_id": "<id>"}
response: {"ok": true, "value": {"output": ...}}

Failure Modes Tested

• No quorum reached
• Agent disagreement across solution/refinement rounds
• Invalid rosters and duplicate expert IDs
• Worker errors and non-OK responses
• Session cancellation
• Production mode rejecting mock workers

Why This Is Non-Trivial

Most agent demos assume a single model response is good enough. This project treats agent output as untrusted distributed-system state and applies quorum, election, and commit logic to make multi-agent decisions auditable and fault tolerant.

More Documentation

• DETAILED_GUIDE.md - full protocol notes
• examples/README.md - runnable local and HTTP examples
• checklist.md and original_plan.md - implementation planning notes