A ClaimReceived note lands on the board.
The intake service writes one signed record with a thirty-minute lease. Every desk in the Spaces sees it within a gossip round.
write(ClaimReceived, lease 30m) · replicated to every peerHere at Bad Monkey, we put our agents to work.. in cubicles. Explore the floor: each numbered area is a language or framework AgentSpaces supports, around the shared space they all work in.
The spaceThe shared space in the middle of the floor. Every desk writes typed notes into it, takes the work it can do, and reads what others finished. No server sits behind it: each peer keeps its own copy.
Brought to you by Bad Monkey, whose cofounders have spent the past 30 years leading advancements in telecom, event processing systems, ontology implementations, and lightweight enterprise software development.
As Bell Labs alumni, we reviewed key advancements in protocol and signaling technology, from early P2P frameworks like Jini and JXTA to modern distributed systems. AgentSpaces resolves their historical limitations by combining them together with the recent advancements in P2P protocols; resulting in a modern, developer-friendly architecture.
A peer is one process running the library, whether it be a microservice process, a Python script, or even an agent in the browser. All peers have a secure Ed25519 identity, can join one or more groups, and register the spaces they take part in. Peers can relay for others, traversing networks, with end-to-end encryption between the originator and its group. This enables AgentSpaces to have a robust P2P fabric, with many secure groups, safeguarding appropriately.
A space is a replicated tuple space, where entries get a TTL, and foundational APIs for working with records. Capabilities get layered on top, enabling peers to advertise if they can do more: build quorums, vote, calculate aggregates, provide strong consistency, and even use the P2P network for learning! Read the architecture guide to learn more about the types of systems AgentSpaces enables.
Each peer issues signed cards that say what it offers, and gossip carries every card to the peers of its group. A peer finds a card in its own cache, and a card that nobody renews ages out. The figure plays nine steps on two groups; press a step to jump to it.
An agent, the goals it pursues, and the entries it takes and writes.
A data system that a connector peer serves to its group.
A model the group can route requests to, and the peers that serve it.
An app that joins the fleet, and how people reach it.
Every card also carries id, issuer, group, issued and ttl, and its issuer signs it. A peer finds cards with discovery.find(kind, predicate) over its own cache. The cards in the figure carry the fields these four show, and the step that uses a kind lights its card.
The office metaphor helps us understand how these agents can work together in groups.
| in the Spaces | in the code | what it means |
|---|---|---|
| the Spaces, the office | group | A peer group with a self-certifying identity. Membership heals itself; join order does not matter. |
| a cubicle, a desk | peer | One process, and the agents at it. Its key is its identity, so it re-registers nothing when it moves networks. |
| the board, the tray | space | A replicated tuple space. Every peer keeps a copy and reads it locally. |
| a sticky note, a work order | entry | A typed record, signed by its writer, with a lease. Matched by what it is rather than by a queue address. |
| taking a note off the board | @SpaceTake | An exclusive take under a lease. The return value completes it, atomically. |
| reading over a shoulder | @SpaceNotify | React to every matching entry without consuming it; a non-void return is the next entry. |
| a timecard, clocking in | lease | How long anything lives. Renewal is clocking in again; silence lets it lapse. |
| going home sick mid-task | lease lapses | The note reappears for a colleague. Nobody wrote the retry. |
| the badge | Ed25519 key | Per-peer identity; a per-agent badge is a subordinate key with a certificate. |
| badge deactivation | revocation | One signed revocation, fleet-wide within a gossip round. |
| hallway talk, the rumour mill | gossip | SWIM membership, rumour for speed, anti-entropy for completeness. |
| the committee, the minutes | @Ballot · @OnDecision | One signed ballot per voter, a quorum, and a tally anyone can recount from the record. |
| the one cashier | @OrderedTake | Takes committed through a Raft log. Exactly once, in one order. |
| bidding for a shift | @BidFunction | A price per entry on an AUCTION space; the lowest bid takes the work, with no auctioneer. |
| the résumé on the name plate | AgentCard | What the agent consumes and produces, signed and leased. The live fleet is the directory. |
| the filing cabinet | AssetCard | A data system that joins as a peer and advertises what it holds. |
| the front desk | A2A gateway | Outside agents come in through the reception; MCP stays the toolbox at each desk. |
| walking between cubicles | transport | Pluggable transports including TLS, mTLS, DTLS, TCP, UDP, WebRTC, HTTP, WSS, WSSE, QUIC, and more! |
| the manager | none | There is none. That is the design. |
An insurance claim arrives on the board at nine. Analysts race for it, repair estimates go to the lowest bid, a panel votes on the approval and the payment runs exactly once. At two in the afternoon a worker leaves mid-task, and nobody notices because nobody needs to.
The intake service writes one signed record with a thirty-minute lease. Every desk in the Spaces sees it within a gossip round.
write(ClaimReceived, lease 30m) · replicated to every peerDocument, fraud and policy analysts each read the claim without consuming it and write what they learned as the next notes. Nobody wired a graph between them.
@SpaceNotify on ClaimReceived · each returns a FindingThree estimators bid. The local, cheaper model's desk offers the lowest price and takes the note. The premium model stays idle until a hard case needs it.
AUCTION space · @BidFunction · lowest bid takes the entryThree reviewers, one signed ballot each. A person on the console casts the fourth. The tally closes at a quorum and one reaction fires, once.
@Ballot · QUORUM · @OnDecisionThree clerks race for the payment note. The ordered log commits exactly one claim; the other two see the loss and stand down.
@OrderedTake over the Raft-ordered logAnalyst two is killed holding a claim. Its timecard stops renewing. The Spaces keep working.
TAKE lease, no renewal · the claim is still on the boardTen minutes later the lease lapses and the claim is visible again. Analyst three takes it. No retry queue, no orphan reaper, no heartbeat service exists.
lease lapses · REAPPEARED · @SpaceTake on another peerWho wrote each note, who held each take, who voted how and who paid is replayable from signed records. Compliance evidence came out of doing the work.
readAllIssued · hybrid-logical-clock orderEvery step above ships in the open-source core and runs in the examples: the kill-tolerant worker in example 11, the auction in example 04, the quorum vote in example 05, the exactly-once desk in example 12, and all of them at once in Party Bus.
Agents stay ordinary code in the framework you already use. Assemble your agents however makes sense for you, across languages, frameworks, even transports.
Agentic AI cost is found in: surrounding systems we buy, build, and sustain; answers we paid for once, and then re-compute rather than re-use; using expensive models where a cheaper model would work; and moving the same bytes again and again. Every lever below ships in the open-source core.
No broker, directory, scheduler, cache, lock service or workflow engine to build, host or staff. Every peer holds a replica of the spaces it uses, so as the fleet grows, only the desks grow.
An answer kept on the board under a lease serves every desk that reads it until the lease lapses, and each desk reads its own replica. The bigger the Spaces, the more questions overlap.
FleetChatModel sends each model call to a peer that holds the provider's credentials, so a caller needs no key and no provider library. A server that dies mid-call lets its lease lapse, and another serves the request. In the guide.
Desks bid for each task on an auction space: the model's price per thousand tokens times an estimate of the prompt, and infinity for a task the model does not handle well. Routine work goes to the cheap model, and the premium model works only when the task needs it. In the guide.
With usage on, each response's tokens are counted per model and per agent. With a metrics space, every peer publishes its running total, the console shows the fleet's usage, and a push-sum aggregate sums a figure fleet-wide with no collector. For exact billing, keep retained audit records. In the guide.
A relay forwards up to a daily byte budget per group, and can refuse content-swarm pieces on a metered link. A holder has an upload budget per day, a metered fetcher a download budget, and a pushed delta a budget of its own. A content store's card states its capacity and its price per GiB-month. In the guide.
The space is the index: each holder writes a small leased record of the pieces it has, and a reader finds its sources with a template read. In-process, a member that held nothing of an artifact received no content frames, and fifty idle members with the swarm on sent 5.43 frames each per tick, against 5.4 without it.
A fetcher serves the others from its first verified piece. When seven peers fetched 1 GiB at once, the publisher served 26% of the bytes over tcp, 27% over tls, and 24% over dtls. On one host this spreads the upload; it does not finish sooner than a single copy.
A value that changes is a tree of hashed nodes, so a reader fetches only the nodes it lacks. One key changed in a 10,000-entry map of 2.2 MB shipped 4,239 bytes, and a one-byte edit of a 64 MiB file shipped a median of 3,323 bytes. More below.
An entry carries up to 64 KiB inline. A model checkpoint, a recording, a dataset, or a table that many agents change travels on the content swarm instead. The space replicates small signed records about the bytes, and the bytes move only between the peers that need them, from every holder at once.
PDT (persistent data trees) keeps a value that changes, such as a map, a vector, a file, a text, or a DataScript database, as a tree of small nodes, each named by the hash of its bytes. A ref, one signed and leased entry, points at the current root.
An update copies the path from the root to the change and shares every other node. Change one key and one path ships, not the whole value. In the guide.
A delta of 32 KiB or less rides the ref's head on gossip, so no reader has to ask. A larger delta can be pushed down the gossip tree. Two writers editing one text merge with no conflict. In the guide.
A reader can read a range of a large file and check each 16 KiB of it as it arrives, before the rest of the file exists locally. In the guide.
A content store holds a group's bytes on request, proves it holds them when challenged, and repairs from another store after a crash. A blind store holds and serves sealed bytes it cannot read. In the guide.
Every piece and every node is checked against its hash before use. A bad copy strikes its sender, and the fetch completes from another holder. In every run of the 0.6.0 performance record, every reader ended with the whole value.
The content swarm runs in Java, Clojure, Groovy, Python, and TypeScript, and the Spring AI, LangChain4j, and Micronaut hosts offer it to models as tools. PDT is coming to Rust, and more of it to Ruby, soon!
From our automated test suite, we measure a local set of tests over TCP, and again using DTLS.
| benefit | what we measured | binding |
|---|---|---|
| Faster reads after the writer leaves | Five readers fetched 64 MiB from two content stores in 803 ms, against 1,604 ms for the flat swarm from one seeder. The stores served every byte. | tcp; on dtls, 2,111 ms against 4,542 ms |
| Faster cold fetch of a tree | Six readers fetched a 1 GiB tree from its writer in 12.8 s, against 21.6 s for the flat swarm; the writer served 92% of the bytes. At 64 MiB: 3.75 s against 5.59 s. | 1 GiB on tcp; 64 MiB on dtls |
| Smaller transfers | One key of a 10,000-entry map (2.2 MB): 4,239 bytes. One byte of a 64 MiB file: a median of 3,323 bytes, against 76,885 when the edited chunk ships whole. Each of ten insertions into a vector of a million elements (6.5 MB): 3,559 to 4,880 bytes. | tcp and dtls; the file edit on tcp |
| Real-time edit sharing | Two replicas made 1,000 concurrent edits to one text: 28.6 bytes per edit, and the slowest member read the merge in 77.5 ms. A one-key change to a 2.2 MB map reached three readers on the ref's head, 4,764 bytes each, with no fetch. | tcp (the merge in 54.6 ms on dtls); the map on tcp and dtls |
| Verified windows | A 2 MiB window from the middle of a 64 MiB file moved 1.055 times the window. | tcp and dtls |
| Availability | After its writer left, a late reader fetched a 64 MiB table from two stores alone in 235 ms, and both stores passed their challenges. A store restarted with 25 nodes lost found the gap in one 122-byte exchange and was whole again 122 ms later. | tcp |
| Reliability | A cold fetch of a 32 MiB table completed after a holder was killed mid-fetch. In the tests, a fetch also survives its seeder's death and resumes after a restart with only the missing pieces. | tcp; the tests in-process |
Read more in the developer guide: the content swarm, values that change, a database on a ref, and a store for the fleet.
Built means it is in the tree with its tests green. Planned means the design is written and the work is scheduled. Proposed means a design document exists and the decisions in it are open.
A map, vector, blob, or text that many peers change lives as a tree of hashed nodes, so a change ships only its delta, two writers merge, and a late reader catches up. A blob's range verifies as it arrives. Java, Clojure, Python, TypeScript, Ruby, and Groovy. In the guide.
A DataScript database on a ref that every member reads, with Python, TypeScript, and Ruby readers, and content stores that hold a group's bytes after their writer leaves, prove they hold them, and repair each other after a crash. In the guide.
A model, a recording, or a dataset of any size is published once as a signed manifest and fetched from every holder at once, rarest piece first, verified piece by piece, resuming after a restart. A space entry above 4 MiB becomes an artifact on its own. Java, Clojure, Python, TypeScript, and Groovy, and the Spring AI, LangChain4j, and Micronaut hosts as model tools. In the guide.
A frame to a member nobody can dial crosses several relays on a pinned path, so two sites behind their own NATs talk through their own relays, and the origin learns when a hop cannot carry it. In the guide.
The Spring AI host moves to the 2.1 line with every optional feature, and a card action gains a confirm step for the tools that should ask before they act.
Decentralized model averaging with learners in TypeScript and Python, more exchange modes, and a console view of the rounds.
A canvas over a YAML blueprint for the data-driven workflows of the workflow guide, and a goal-driven planner that composes a fleet's cards into plans, with a plain-language rule composer for the people who run it.
Quarkus and Vert.x hosts over a shared facilities module, Kotlin faces, and a coding-harness fleet that puts coding agents on the same spaces.
Add an annotation, join an AgentSpace. AgentSpaces is open source, more integrations, libraries, and languages getting added routinely.
@SpaceAgent(description = "Ships orders from the shared space")
public class Fulfiller {
@SpaceTake(lease = "10m") // crash => order reappears
public Shipment ship(Order order) {
return new Shipment(order.orderId(), order.item(), "fulfiller");
}
@BidFunction // AUCTION spaces only
public double bid(Order order) {
return estimatedTokens(order) * modelCostPerToken();
}
}
<dependency>
<groupId>ai.badmonkey.agentspaces</groupId>
<artifactId>agentspaces-spring-boot-starter</artifactId>
<version>0.6.0</version>
</dependency>
<!-- or import agentspaces-dependencies 0.6.0 as a BOM and drop the version -->
# a Python peer takes the same typed work off the same space
from agentspaces.space import entry
from agentspaces.agents import Binder, agent, space_take
@entry("ai.badmonkey.agentspaces.examples.Order#v1")
@dataclass
class Order:
orderId: str
item: str
@agent("py-fulfiller", description="Ships orders")
class Fulfiller:
@space_take("work", lease="10m") # take, call, complete with the result
def ship(self, order: Order) -> Shipment:
return Shipment(order.orderId, order.item, "py-worker")
Binder(peer).bind(Fulfiller()) # the same loops the Java binder runs