Repository navigation
v1.8.0 — Teaching Colony runs on real Claude
What's new in v1.8.0
First release where the Teaching Colony actually runs on a real language model. v1.8.0 adds an interactive REPL and fills in the Claude Code adapter's live-mode dispatch path with real Anthropic API calls, prompt caching, and model tiering. A reader can now type ask what do you know about beekeeping at a colony prompt and receive a real Claude answer grounded in the seeded primer — not a canned mock string.
This is the first release of the Agent Colony pattern that costs money to use. The README section explains the envelope in detail: roughly $2-5 for a full 500,000-token session with the recommended Sonnet/Haiku model mix, after prompt caching kicks in.
Why v1.8 as its own increment
v1.6.0 shipped a 4,300-line artefact where the headline claim was false on the happy path (see v1.7.0 release notes). That review is still fresh. v1.8.0 ships the live-mode dispatch path on its own — and nothing else — so it can be verified end-to-end against a real model before v1.9 layers research walks on top. v2.0 will add the full command set, session persistence, and cost enforcement. Each increment gets its own commit-test-tag-release cycle.
What v1.8.0 adds
- Interactive REPL —
examples/teaching_colony/chat.py. asyncio-based. Commands:ask,help,quit. Forward-looking v1.9+ commands (research,status,cancel,knows,capabilities) route helpfully to "coming in v1.9+" messages rather than tracebacks. - Live-mode
dispatch_agentin the Claude Code substrate:- Prompt caching —
cache_control: ephemeralon the Mirror system prompt. Repeat dispatches of the same agent within 5 minutes pay ~10% of the system-prompt cost. The REPL's budget display shows cache-read tokens as a separate counter so you can see it work. - Model tiering — Sonnet for Teacher and Librarian (real pedagogical work); Haiku for Registry, Chronicler, Equilibrium, Sentinel (small structured decisions).
- Prose-vs-JSON prompt discipline — Teacher and Librarian get pedagogical prompts; the four supervisory agents get JSON-strict prompts with explicit schemas and a one-retry fallback for malformed responses.
- Prompt caching —
- Session budget —
examples/teaching_colony/colony/logic/budget.py.Budgetclass tracking all four Anthropic usage counters.TEACHING_COLONY_TOKEN_BUDGETenv var, default 500,000, safe fallback on invalid values. 80% warning, 100% hard stop for new dispatches. - Three new test modules — 36 new tests covering the Budget class (27), REPL smoke in mock mode (9), and gated live-Claude dispatch (3). The live tests require
ANTHROPIC_API_KEYand run withpytest -m live; they prove that prompt caching actually hits on the second dispatch (cache_read_input_tokens > 0).
Test results
72 passed, 3 deselected (live tests), 2 xfailed
Every v1.7.0 mock-mode test still passes. The 2 xfails are unchanged — live-mode Managed Agents dispatch_agent and update_mirror, still deferred until research-preview allowlist.
How to try it
cd examples/teaching_colony
pip install -r requirements.txt
# Offline, no cost, good for seeing the mechanics
python -m examples.teaching_colony.chat --mock
# Live mode — real Claude, real tokens, ~$0.15 for ~30 questions
export ANTHROPIC_API_KEY=...
python -m examples.teaching_colony.chat
# Tighter budget for cost discipline
TEACHING_COLONY_TOKEN_BUDGET=50000 python -m examples.teaching_colony.chatKnown gaps after v1.8.0
- No research walks yet.
research,status,cancel,knows,capabilitiesare all v1.9+. - No tool use.
fetch_url,extract_links,score_linksare v1.9+. - No background concurrency. Research walks will run concurrently in v1.9; v1.8 has one synchronous dispatch per
ask. - No capability graduation yet. v1.9 wires Librarian's coverage check to the existing §7 Comprehension Contract path.
- Retrieval is single-shot keyword match, not real RAG. Fine while the KB has one entry; replaced in v2.0 when the KB has dozens.
- REPL dispatches only to Teacher.
ask sentinel co-sign thiskind of syntax is v2.0. - Tokens display is post-dispatch, not streaming. A streaming token counter is v2.0 polish.
- Managed Agents live-mode
dispatch_agentandupdate_mirrorstill raise NotImplementedError (2 xfails, unchanged from v1.7.0).
Roadmap updated
The repo roadmap now reads:
| Version | Status | Focus |
|---|---|---|
| v1.8.0 | ✅ released 2026-04-14 | Live-mode dispatch, prompt caching, REPL foundation |
| v1.9.0 | planned | Research walks with hop budget, tool use, G3 graduation |
| v2.0.0 | planned | Full interactive Teaching Colony — reference implementation |
| v2.1+ | planned | Live-mode Managed Agents, Newcomer diagrams, peer feedback |
Cite as:
Oliver, D. (2026). The Agent Colony: A Pattern Language for Self-Governing AI Agent Ecosystems (v1.8.0). https://github.com/DavidROliverBA/agent-colony-pattern