Repository navigation
v1.6.0 — Teaching Colony (first substrate-portable example)
What's new in v1.6.0
A six-agent Agent Colony that teaches the pattern, running identically on two substrates.
Until this release the pattern had no artefact showing it actually running on real agent infrastructure. v1.6.0 is the first. A six-agent Teaching Colony — Registry, Chronicler, Equilibrium, Sentinel, Librarian, Teacher — lives in examples/teaching_colony/ and runs on two substrates behind a common SubstrateContract ABC. The demonstration is the portability.
What this exercises for the first time in running code
- Principle 2 — Identity over implementation. The six Agent Mirrors are substrate-independent. The same YAML files are loaded by both adapters.
- Principle 4 — Longevity by design. The colony can be lifted from one substrate to the other without rewriting Mirrors, logic, or event memory.
- The Comprehension Contract (§7). Until now §7 was prose. v1.6.0 makes it fire: Librarian detects KB coverage crossing a threshold, proposes Teacher acquire
teach_agent_colony_pattern, the Structural Classifier fires with the §7.4 review regime formula (Novel action class → Peer Review short-circuit), Sentinel co-signs, Teacher's Mirror is updated with an append-only audit entry including pre/post state hashes. - Principle 7 — Accessibility through abstraction. The colony's purpose is to teach, using beekeeping as its running pedagogical example. The purpose realises the principle.
The substrate contract
Eight operations every substrate must implement. This is what L4 owes L1–L3:
class SubstrateContract(ABC):
def dispatch_agent(self, agent_id, input) -> dict
def read_mirror(self, agent_id) -> Mirror
def update_mirror(self, agent_id, changes, co_signer) -> AuditEntry
def record_event(self, event) -> None
def read_kb(self, query) -> list[Document]
def write_kb(self, topic, content, provenance) -> None
def co_sign(self, action_class, actor, co_signer) -> Signature
def classify_action(self, action, context) -> ClassificationTwo substrates
- Claude Code (
substrates/claude_code/) — orchestrates the colony via the Anthropic Python SDK. Full 8-operation implementation, working in mock mode offline, ready for real Claude API calls. 8 unit/lifecycle tests passing. - Managed Agents API (
substrates/managed_agents/) — scaffolding adapter with mock mode fully working. Live-mode operations are gated behindNotImplementedErrorpending v1.7+ completion. Ships withapi-research.md(first honest adequacy report of a real substrate against the Agent Colony contract) andgaps.md(honest v1.6.0 status).
Both substrates run the same 22-event lifecycle against the same colony definition and produce the same observable graduation.
How to run
cd examples/teaching_colony
python run.py --substrate=claude-code --mock
python run.py --substrate=managed-agents --mockBoth commands complete the lifecycle, produce a summary table, and leave a diffable event log plus Mirror updates in state/.
Test results
26 passed, 2 skipped, 4 xfailed
The 2 skips are the event-log-parity and Mirror-final-state-parity assertions, deliberately skipped in v1.6.0 with reasons pointing at gaps.md. The 4 xfails are Managed Agents live-mode operations gated for v1.7+.
Known gap
The Managed Agents substrate adapter ships with mock-mode fully working and live-mode operations gated. The mock update_mirror and write_kb are currently no-ops in the Managed Agents adapter, which is why the full event-sequence and Mirror final-state parity tests skip. Live-mode completion is targeted for v1.7+. See examples/teaching_colony/substrates/managed_agents/gaps.md for the honest adequacy report.
Status
The pattern remains practically untested at production scale — no full LLM-backed reference implementation at colony size exists yet. v1.6.0 is the first time the contract has been implemented twice and shown to work in mock mode. v2.0 remains the target for empirical threshold calibration and full production validation.
Cite as:
Oliver, D. (2026). The Agent Colony: A Pattern Language for Self-Governing AI Agent Ecosystems (v1.6.0). https://github.com/DavidROliverBA/agent-colony-pattern