AgentSpaces for Python

This part takes you from an empty directory to two Python processes sharing work. It uses a few words throughout, so here they are first:

• A peer is one running process that is a member of the fleet. It has its own Ed25519 key and signs everything it writes.
• A group is the set of peers that work together. Its id is derived from a founding text, so every peer that knows the text knows the group.
• A space is a named, replicated store inside a group. Every peer holds a copy.
• An entry is one typed value in a space, such as an order or a shipment.
• A lease is how long something lasts. An entry written with a 10 minute lease disappears after 10 minutes.
• A take claims one entry for one peer. If the peer finishes, it completes the take. If it crashes, the take's lease lapses and the entry comes back for another peer.
• An agent is a class whose methods react to entries. A capability is a fleet service an agent can use, such as a vote or an average.

The client is the package agentspaces-client. It needs Python 3.11 or newer and has one dependency, cryptography. It is not on PyPI yet, so install it from a clone:

The package installs one module tree, agentspaces. You will import from agentspaces.peer, agentspaces.identity, agentspaces.space, agentspaces.agents, and agentspaces.capabilities.

A Python peer dials out and never listens. So it needs a seed: a peer that listens and that other peers dial to join. The easiest seed is the Node service host from the TypeScript client, which reads a fleet file and needs no code.

This file founds the group shop from the text shop-v1, opens the space orders, and listens on port 7700. The dev-local profile signs every frame over plain loopback TCP: use it on a laptop, never on a shared network. Production fleets use mtls.

The Node host is not on npm yet either. Build it from a clone (Node 22 or newer), then start it from the directory that holds seed.yaml:

The first run creates a keys/ directory beside seed.yaml for the seed's identity. A JVM peer with a bind address works as a seed too; the developer guide starts one.

An entry is a dataclass marked with @entry. The decorator names the entry's wire schema, the name every language in the fleet uses for this type. The field names go on the wire as written.

• Keep the wire's field names, orderId here, even where Python style would say order_id. A Java record or a TypeScript class with the same schema reads the same fields.
• A reader ignores wire fields its dataclass does not declare, so a newer writer can add a field without breaking older readers.
• Use integers for numbers that cross languages. The TypeScript encoder refuses an unwrapped fraction.

An agent is a method. Its parameter is the entry it takes, and its return value is the next entry written into the space. Put the method on a class, mark the class with @agent and the method with @space_take, and bind an instance to a peer.

Here is what each piece does:

• Identity.generate() makes a fresh key. group_id_from_founding(b"shop-v1") derives the same group id the seed derived.
• peer.connect dials the seed and introduces this peer to the group.
• The binder reads the parameter annotation, Order, to know which entries to take. It takes one under a 30 second lease, calls ship, writes the returned Shipment, and completes the take.
• Space(peer, "orders") is the procedural handle on the space: write, read, read_all, take, and watch.
• renewing_subordinate gives the agent a key of its own, explained under Certified agents.

With the seed running, start the agent twice from two terminals:

The first instance only ships. The second also writes an order, prints the shipment, and exits. Either one can take the order, because both run the same agent.

Now try a crash. Add time.sleep(10) and a print at the top of ship, start both, and run kill -9 on the instance that prints. No code tells the other instance about the crash: the killed take's 30 second lease lapses, the order comes back, and the survivor ships it. Two fulfillers and a crash does the same thing in one program.

A take answers "who gets this entry". A bid lets agents compete for it. Add a @bid_function method for the same space: the binder asks it for a price before each take, and the lowest bidder gets the entry.

peer_a and peer_b are two peers connected as in the first agent. Peer A bids the length of the item's name and peer B always bids 5, so A gets the kite and the tent and B gets the bicycle. The seed needs no auction setting: each take carries its bid, and every peer settles on the claim with the lowest bid. The seed's fleet file must list the auction space beside orders.

• Key features below covers the rest of the decorators, joining a fleet without a fixed address, and what Python cannot do yet.
• The developer guide summarizes this client for Java readers. Its binder chapter explains each verb in depth.
• The architecture guide explains leases, claims, and replication.
• The TypeScript guide covers the Node host you used as a seed.

Python agents are ordinary classes. The decorators only attach metadata; Binder(peer).bind(obj) reads it and runs one loop per method. The entry type a method reacts to comes from its parameter annotation. A class without @agent is named after itself (Packer becomes packer).

The return value decides what gets written. None writes nothing. A list or tuple is a fork: each element is written on its own. Tagged(value, {"region": "eu"}) writes the value with tags, and a Motion opens a vote. This program forks one order into two entries, joins them back, and watches the result from a second peer:

• produces=[...] tells the card what a fork writes, since a list annotation cannot.
• where={"priority": gte(1)} filters with matchers from agentspaces.space (eq, ne, gt, gte, lt, lte, in_, contains, is_null, not_null, or any callable). filters=["priority>=3"] takes the same portable clause strings Java and TypeScript use.
• @space_notify(on=[...]) can also watch TAKEN, COMPLETED, EXPIRED (a write lease lapsed), and REAPPEARED (a take's lease lapsed).

A Python peer opens one connection to a seed, over TCP or TLS, and reaches every other member through it. The seed relays frames for members that cannot reach each other directly. So you always need one listening peer in Node or the JVM, and the Python side only needs an address or a way to find one.

For join_by_group_id, bootstrap, and join_invite, create the peer with Peer(identity, None); the call fills in the group. A seed that serves the wrong document is ignored, so a hostile seed can delay a join but cannot change the group. Joining by id works only for groups with a signed founding; a group founded from a plain text, as in this guide, is joined with group_id_from_founding and connect.

The peer recovers from a lost socket by itself. It re-dials every 5 seconds for 10 minutes, then introduces itself again and re-pulls what it had. A take in flight keeps waiting across the gap. Only your own peer.close() is final. The developer guide covers beacons and invite keys in depth.

By default the peer's key signs everything its agents write. Give an agent its own key instead, certified by the peer and renewed at half its lifetime, and the fleet records its work as that agent's:

• "PT24H" is the certificate's lifetime as an ISO 8601 duration.
• For a peer that keeps its identity across restarts, use Identity.load_or_create("./keys"). It reads and writes the same peer.key and peer.pub layout as Java.
• Identity.agent_keys(dir, peer_id, name) keeps an agent's key on disk the same way.
• When a certified agent takes an entry, the agent's key must sign the completion too. The fleet refuses the peer's key for it, as Java does.

The security chapter explains certificates and revocation.

The fleet services live in agentspaces.capabilities and run over one multiplexer, Pipes(peer). Each speaks the same protocol as its Java provider, so Python members and JVM members take part in the same vote, average, or query.

A vote. Proposals and ballots are entries in a space, and every peer tallies them by Java's rule. vote.propose opens one; decorated councillors answer it:

An average. Aggregate is push-sum gossip: each peer contributes a number and all of them converge on the fleet's average. await_settled returns it once it stops moving.

Push-sum shares go only to members this peer reaches directly. Behind a relaying seed that is the seed alone, so run the average where the Python peer dials the peers that contribute.

More services:

• Semantic(pipes) ranks agent cards against a text query (query), asks other members (remote_query), and answers their queries.
• actions(peer) lists the methods other agents' cards declare, and invoke(peer, action, value, result_type=...) calls one through its space.
• Content moves large artifacts between holders; see The content swarm.
• OrderedLog takes an entry through a Raft log so exactly one peer gets it; see What Python cannot do yet.

The capabilities chapter explains each service and when to use it.

The Python client is a full member for spaces, agents, and the capabilities above. A few pieces need a process that listens or keeps a Raft log, and those run only in Java (and partly in TypeScript). Here is each gap and what to do instead:

This is the ordered take from your own code. Three Node voters keep the payments log, the Python peers are its clients, and only the peer the log chose gets past if taken:

The voters come from ordered-logs in the seed's fleet file, one entry per log listing every voter's PeerID. The ordered take section explains when you need it.

A take method sometimes runs long, for example while it waits on a model. Code deep inside that call may need the take it runs under, to renew its lease. The binder puts the current take in a context variable, so you can reach it without passing a parameter:

TakeContext.current() (from agentspaces.space) returns the Taken: its value, its entry_id, and renew() to extend the lease. Outside a take it returns None. A procedural Space.take returns the same Taken, which you complete(result) yourself.

The first two examples come from the Jungle Gym, a set of programs that run the same steps in Java, TypeScript, Python, and Clojure. Its repository is not published yet. Each program there also imports a small helper, wait.py: its until(check, why) calls check until it returns something, and fails the program at a deadline.

This program starts two peers in one process, binds the fulfiller on both, and ships six orders. Then it makes peer B hold order o-7 and stops B before it completes. B's 3 second lease lapses, o-7 comes back, and peer A ships it.

What to notice:

• Both peers dial the seed. The seed only relays; it runs no agent.
• bind returns a Bound, and on_a.close() unbinds A's fulfiller so that only B can take o-7.
• No code tells A about the crash; B's lapsed lease returns the order.

Run it with the seed from Start a seed on port 7700. The program prints 6 orders shipped, each exactly once and then o-7 shipped by A after peer B stopped.

Entries are small. For a model checkpoint or a dataset, use the content swarm: an artifact is cut into pieces, its signed manifest goes into the content space, and peers fetch pieces from every holder at once, checking each piece before they store it.

Here peer A publishes 4 MiB, peer B fetches it, A stops, and peer C fetches it from B, the only holder left:

• MemoryStore keeps pieces in memory, which suits a test. Use FileStore(path) in a real peer: it survives a restart and republishes what it holds.
• publish takes bytes or a file path and returns the manifest. Its root is the artifact's content id.
• The seed holds no pieces. It carries each one between the Python peers as a relayed frame.
• Before the swarm starts, the full program sends each peer's first request to the seed, so that the peer learns the seed relays for it. The TypeScript client does this on joining; the Python client does not yet.

The content section covers piece sizes and escalation of large entries.

This example joins a fleet whose coordinator is Java. The Python worker takes research tasks, votes on the council's proposal, contributes its load to the push-sum average, answers semantic queries, and serves the remote action its card declares. It dials the Java coordinator directly, with no Node seed.

The entries use the Java records' schema names, such as ai.badmonkey.agentspaces.examples.fleet.ResearchFleet$ResearchTask#v1, so both sides read the same tasks and findings.

To run it, build the AgentSpaces repository (mvn install in agentspaces/): the library is on Maven Central, but the example modules are not published. Start the Java coordinator from that directory, then the worker from the agentspaces-python clone with the client installed:

The worker prints each task it completes, its ballot, the decision, and the settled average. The full program is demo_council_worker.py, and the client's tests show every capability without a socket.