Stigmergy

The biology

Termites build complex mounds without blueprints. Ants find the shortest path to food without maps. No central coordinator tells each insect what to do. Instead, they coordinate through their environment — leaving chemical markers (pheromones) that other insects read and respond to.

This is stigmergy: indirect coordination through modifications to a shared environment. The environment IS the communication channel.

The software parallel

In Honeybee, agents coordinate through ACP’s shared state and events — the digital equivalent of pheromones.

# Agent A writes to shared state
state_set("auth_module", "complete")

# Agent B reads the environment, reacts
# (pushed via WebSocket — no polling)
event: { type: "state.changed", key: "auth_module", value: "complete" }
# Agent B wakes up and starts the dependent task

No message was “sent” from A to B. Agent A modified the environment. Agent B observed the change and reacted. The coordination emerged from the environment, not from direct communication.

Why stigmergy scales

Direct coordination (O(n^2))

If every agent must communicate with every other agent, the number of connections grows quadratically. Five agents need 10 channels. Ten agents need 45. Twenty need 190. This is why chat-based frameworks hit walls.

Stigmergic coordination (O(n))

Each agent only interacts with the shared environment. Adding a new agent doesn’t add new channels — it adds one more reader/writer to the existing state. The environment absorbs coordination complexity.

Direct:      A ←→ B ←→ C ←→ D     (6 connections for 4 agents)
Stigmergic:  A → [env] ← B        (4 connections for 4 agents)
             C → [env] ← D         (always N, not N*(N-1)/2)

Resilience

When an ant dies, its pheromone trail fades. Other ants find alternative paths. The colony doesn’t need to know an ant died — the environment handles it.

In ACP: when an agent fails or exhausts its context window, its claims auto-release (via heartbeat timeout). Other agents observe the unclaimed resources and pick up the work. No orchestrator intervention needed.

governance:
  heartbeat:
    dead_after_ms: 60000
    auto_release_claims: true

The agent dies. Its claims expire. The work appears unclaimed. Another agent claims it. The system self-heals.

Contrast with other approaches

Approach	Communication	Scaling	Failure handling
Direct orchestration (LangChain)	Central router, all messages through one point	Bottleneck at orchestrator	Orchestrator must detect and reroute
Message passing (CrewAI)	Direct agent-to-agent messages	O(n^2) channels	Sender must handle delivery failure
Explicit graphs (LangGraph)	Pre-defined edges between nodes	Rigid, hard to change at runtime	Graph must have error edges
Stigmergy (ACP)	Shared environment (state + events)	O(n), agents don’t know each other	Claims auto-release, work auto-redistributes

ACP as the environment

ACP’s primitives map directly to stigmergic concepts:

Stigmergy concept	ACP primitive	Example
Leave a pheromone	publish event	”I finished the auth module”
Read the environment	get_state / event subscription	”What modules are done?”
Claim a food source	claim resource	”I’m working on the payment module”
Trail evaporation	Heartbeat timeout + auto-release	Agent dies, claims expire
Environmental marker	set_state	”status: reviewing”
Nest quality signal	Governance metrics	Budget used, errors counted

The key insight: agents don’t need to know about each other. They only need to know about the environment. The protocol defines what markers exist and what they mean. The agents independently read and write. Coordination emerges.