Two plain classes become a two-peer fleet: a kill-tolerant worker and an auditor that reacts to every result. Nothing here deploys a broker, a registry, or a scheduler; the coordination fabric is a library inside your application.

1. Add the starter

The source lives at github.com/badmonkeyai/AgentSpaces, and the release artifacts are on Maven Central under the group ai.badmonkey.agentspaces, version 0.4.0 (central.sonatype.com). Maven and Gradle resolve Maven Central by default, so no repository configuration is needed. One dependency brings in the starter, the fabric and the annotation binder:

The bill of materials, agentspaces-dependencies, manages the version of the core AgentSpaces modules (the fabric, the transports, the starter, the console, the A2A gateway, the Embabel extension, and the test support) and of Jackson, Caffeine, Nimbus JOSE+JWT, and BouncyCastle; the bridge projects for Spring AI, Micronaut, and LangChain4j are not in it and carry their own version. Import it once and leave the version off every core AgentSpaces dependency, whether the starter or individual modules (a plain-Java application depends on agentspaces-agent, which brings the fabric with it):

Under Gradle the same BOM is a platform dependency. Kotlin DSL:

Groovy DSL:

A project that inherits from spring-boot-starter-parent or applies the Spring Boot Gradle plugin still imports this BOM, because Spring Boot's dependency management does not know the AgentSpaces artifacts; without it, write 0.4.0 on each dependency. No snapshot repository is published: to build against unreleased sources, run mvn install -DskipTests in a clone and resolve from the local repository (mavenLocal() under Gradle).

2. Describe the fleet, once

The starter reads one YAML block: an identity keystore, a group every member derives the same self-certifying id from, and the spaces the group shares. Start a second JVM with the same block, its own advertise address, and a seed address, and you have a fleet.

3. Write the agents

The worker takes orders under a lease and returns shipments; the auditor reacts to every shipment and returns a receipt. Both are complete as shown.

4. Put work in

What you now have: the order replicates to every peer, one fulfiller takes it under the default LEASE_RACE strategy (a partition can briefly let two fulfillers work the same order), the shipment and receipt appear as signed entries, and if you kill the working JVM mid-task the lease lapses and the order reappears for another. examples/example-11-quickstart is the plain-Java form of this pair (two in-process TCP peers, an AgentBinder, no Spring); integration-tests/spring-boot-it boots a smaller application through the starter instead: one @SpaceTake researcher over a tasks space and a findings space, alone and as a two-application fleet over TCP.

Choose who decides the next step, then choose how that step is claimed. AgentSpaces supplies typed entries, leases, discovery, identity, and replication. Your application can coordinate through those entries directly, let an Embabel planner compose typed actions, or let a Spring AI model choose fleet tools. A worker can itself use Spring AI, regardless of how its task was created.

The same process may host several roles. Splitting them into peers changes deployment and failure boundaries; it does not require rewriting the request and result types. Keep those types in a shared domain artifact, name your spaces explicitly, and carry a request id through every stage.

An agent is an ordinary object with annotated methods, and the binder is what turns the annotations into running behavior. The annotation model is the top of the stack and the whole API most applications need: fourteen annotations cover identity, work, choreography, routing, fan-in, economics, and access at Layer 3, and voting, settled estimates, exactly-once work, typed clients, and served capabilities at Layer 4. Each maps to protocol behavior the layers below carry for you. This chapter covers the facade and the binder, the identity annotation, and the conventions every annotation shares. Chapter 2 covers work: take, notify, bid, and the space handle. Chapter 3 covers decisions and fleet sensing. Chapter 4 covers exactly-once work and fan-in.

They go on ordinary objects. There is no base class to extend, no interface to implement, and no container of ours to run in: the binder reflects over an instance you hand it, wires whatever it finds, and leaves the rest of the class alone. Constructors, other Spring beans, JPA repositories, and your own fields all stay untouched. That matters for how you organize a fleet, so each annotation below says plainly where it belongs and what else is allowed to sit beside it.

Two objects bind. AgentBinder is the hand-built form and serves one group: it is built from the peer identity, the GroupId, the group's discovery service (or null to publish no cards), and a clock. Register what it may bind to, then bind: space(name, space) for each space, vote(space, capability) for a vote capability, aggregate(pushSum), ordered(space, coordinator), client(type, instance) for a typed client, and bind(instance) or bind(instance, name), which names the agent and lets one class be several agents. The AgentSpaces facade sits over several groups. spaces.group(name) returns a GroupContext that holds the group's spaces (space(name)), its discovery service (discovery()), its typed capability clients (capability(VoteClient.class)), and the registrations the Layer 4 annotations need: provide(capability), vote(space, capability), ordered(space, coordinator). spaces.bind(instance) binds the object into every registered group whose spaces cover the spaces its annotations name, narrowed to the groups the annotations name, and returns one Bound per group; group.bind(instance) binds into one. Under the Spring starter the facade is a bean and the post-processor calls bind for every enrolled bean; the Micronaut enroller and the LangChain4j FleetRuntime.bind do the same.

Binding runs in one order whichever object does it. @SpaceRef and @CapabilityRef fields are injected first, then bid functions wire, then one pass over the public methods starts each method's take loop, subscription, join, or reduce (in the order reflection returns the methods, which the binder does not fix), and last the AgentCard publishes, built from the identity annotation plus the bound method signatures. The card names the agent, its description and goals, one action per bound method (what it consumes, what it produces, the method's description), its space bindings, and under subordinate keys the agent's public key and certificate. It is TTL-leased and republished on the card cadence (agentspaces.card-refresh-millis) wherever a host calls refreshCards(): the Spring starter, the Micronaut lifecycle, and the LangChain4j runtime do, and a hand-built binder or facade republishes only when its caller does. A peer that dies stops republishing, so its card ages out of every cache. One card per group bound: an object bound into two groups publishes two. The Bound handle answers agentId(), card(), and isRunning(), and close() interrupts the loops and closes the subscriptions. The binder still lists a closed binding, so its card keeps being republished until binder.unbind(agentId) (which also closes it) or the binder's own close(), and then lapses at its TTL.

@AgentSpec declares an agent's identity on any class, framework or not. Under Spring, prefer the @SpaceAgent stereotype: it is both a @Component and an @AgentSpec, so component scanning and fleet enrollment are one drop. Binding publishes an AgentCard built from the identity plus the bound method signatures, so other peers can discover what this agent consumes and produces with no extra code. Micronaut has a stereotype of the same name, ai.badmonkey.agentspaces.micronaut.SpaceAgent: a bean-defining annotation (a singleton unless the class says otherwise) that is also an @AgentSpec, so the enroller binds the bean at startup; it carries the same three attributes.

• Space inference. Every space attribute is optional. For @SpaceTake, @SpaceNotify, and @SpaceRef, empty resolves to the group's sole registered space. Vote annotations infer the sole registered vote space; @OrderedTake infers the sole coordinated space. Name the space whenever that choice is ambiguous.
• Group selection. Every binding annotation takes an optional group, by application-facing name or GroupId value. A binder for a different group treats the member as not its own and skips it, so one bean can bind methods into several groups at once; the facade's bind(...) binds the bean into every registered group whose spaces satisfy its bindings, narrowed to the groups its annotations name, and publishes one card per group bound. The facade refuses an unjoined group by name for @SpaceTake, @SpaceNotify, @BidFunction, @SpaceRef, @SpaceJoin, @Propose, and @OnEstimate; a @Ballot, @OnDecision, @OrderedTake, or @SpaceReduce naming one is skipped, so check the name when a ballot, an ordered take, or a reduce never binds.
• Durations. Every duration accepts Spring-style simple strings ("10m", "500ms", "30s", "2h", "1d") and ISO-8601 ("PT10M").
• Method shape. Bound methods must be public and take exactly one parameter: the entry, for the vote annotations the Proposal (@Ballot) and the Decision (@OnDecision), for @OnEstimate the PushSumAggregate.Estimate, and for @SpaceJoin the Joined bag of one key's parts. The one exception is @SpaceReduce, which takes two parameters: the key's accumulator (null on the first step) and one element. @BidFunction returns double, @Ballot the option as a String (null abstains), and @Propose the question as a String (null asks nothing); the others return the next entry, a Contribution to an aggregate epoch, a Motion that opens a vote, or void. A method may also return Tagged.of(entry, tags) to write the entry with tags: the binder unwraps it before any other return handling, a same-space take result goes through complete(taken, entry, lease, tags) atomically with the completion, and the card declares the wrapped type.
• Tag filters. @SpaceTake, @SpaceNotify, and @OrderedTake accept tags = {"key=value", "key"}: each filter requires the tag to equal the value, or to be present. The filters compile onto the method's template, so the space judges them after the type comparison and before it decodes the payload. A malformed filter is refused at bind time, naming the method.
• Names. An agent's name comes from @AgentSpec (or the class); bind(agent, name) overrides it, so several instances of one class can be several agents: a council of seats, one class.
• Cards for free. Consumed and produced types are collected from the signatures and published on the agent's card, TTL-leased and refreshed on the card cadence by the host (the starter, the Micronaut lifecycle, and the LangChain4j runtime do; a hand-built binder waits for refreshCards()).
• Where the annotation may sit. The binder reads each binding annotation from the method itself, then from the same-signature method of each superclass, then of each interface, the first declaration winning, and @AgentSpec the same way. So a java.lang.reflect.Proxy over an annotated interface, an anonymous subclass of an annotated abstract class (named by @AgentSpec(name = ...) or bind(agent, name), since an anonymous class has no simple name and the binder throws when it must derive one), a LangChain4j AiServices proxy whose interface carries @SpaceTake, and a Clojure reify of a generated interface all bind as workers.
• Nothing is reserved. The binder reads the annotations and ignores everything else on the class. Other frameworks' annotations, other interfaces, other methods and fields all keep working, which is why an Embabel @Action becomes a fleet worker by adding one annotation rather than by being rewritten.

Choosing between them

Three questions settle almost every case. Should exactly one agent handle this entry? If yes, @SpaceTake; if every interested agent should see it, @SpaceNotify. Are the candidate workers interchangeable? If not, put the space on AUCTION and add a @BidFunction, and let the cheapest one take it. Does one trigger produce more than one entry, or entries elsewhere? Then add @SpaceRef and write them yourself rather than contorting a return value. Is the cue a vote's proposal or its decision, or must an entry be completed at most once fleet-wide rather than once per lease? Then it is @Ballot, @OnDecision, or @OrderedTake, and the space needs its capability registered. Does the cue decide only the question of a vote? Then @Propose. Does it decide the options or the quorum? Then return a Motion. Does one stage wait for several entries of different types about the same case? Then it is @SpaceJoin, a method taking Joined, and its mode says whether each key fires once per joiner, once per lease, or once fleet-wide. Does one cue produce several entries? Return Entries and list them in produces. Should only some entries of the type reach the method? Filter them with where. Is the cue an entry that lapsed? Then @SpaceNotify(on = EXPIRED). Does a stage wait for several entries of one kind? Then a @Part with atLeast or countedBy, or a join settle period. Is the cue a fleet estimate that has stopped moving? Then @OnEstimate.

The two failure models are the thing to hold on to, because they decide where risky work belongs. @SpaceTake retries forever by default: a crash, a kill, or a thrown exception all lapse the lease and the entry comes back. @SpaceNotify does not retry at all: a reaction that throws is logged and gone. A @SpaceJoin in LOCAL mode follows the notify model and in LEASED or ORDERED mode the take model, because the ticket it fires from is a leased take. Put work that must eventually happen behind a take; put reactions that are nice to have behind a notify.

A binding is a runtime resource. Plain Java constructs the object and calls bind; Spring enrolls initialized beans. Space and capability fields are injected during binding, before worker loops start. Keep constructor work independent of those fields. Public inherited methods are visible to the binder; private annotated methods are not worker entry points.

Keep completion and side effects separate in your reasoning

When a take returns an ordinary entry into the same space, the binder calls complete(taken, result, resultLease). With a different resultSpace, it completes the input first and then writes the output separately. A crash between those calls can lose the output; the input has already been completed. Prefer the same-space handoff for critical stages, or implement application-level reconciliation for cross-space steps.

Ordered claims make replicas agree on winners and completion; they cannot make a database write, payment API call, or email part of that commit. A worker can perform an external effect and fail before recording completion. Use the business request id as an idempotency key at the external service. Use TakeContext.current().orElseThrow().entryId() when the key should follow this particular space entry through reassignment.

TakeContext exists around both take annotations only; notify and ballot handlers have none. renew() extends the active claim. The context is thread-local: custom executor hops must propagate and clear it. Returning a Future or Flux does not make the binder await it; finish the work and return a domain result from the annotated method.

The Layer 4 annotations are @Ballot, @OnDecision, @Propose, and @OnEstimate (chapter 3), @OrderedTake and @SpaceJoin and @SpaceReduce in ORDERED mode (chapter 4), and @CapabilityRef and @ProvidesCapability, with the Contribution and Motion return values beside them; the signatures in those chapters are the checked-in 0.4.0 ones. Each binds a behavior to a capability the peer must already hold, so assembly comes first: the table says what each behavior needs registered before the agent is bound, and what to verify once it is. There is no @Contribute and no learning annotation: aggregation uses the Contribution return value, and gossip learning is driven through the capability API (gossip learning).

The Layer 3 annotations: the four most applications need and nothing else. @SpaceTake claims work under a lease, @SpaceNotify reacts to what appears, @BidFunction prices work on an AUCTION space, and @SpaceRef hands a method a space when a return value is not enough. All four follow the shape chapter 1 set out: the parameter is the cue, the return is the next entry, and the binder carries the discipline.

Turns a method into a leased take loop. The parameter type is the template; a normal return completes the take and, for an ordinary result in the same space, writes the result atomically; a thrown exception skips completion so the lease lapses and the task reappears for another worker. The failure path is the happy path with nothing added.

Reach for @SpaceTake whenever work is a queue of units that exactly one worker should do: research requests, document conversions, booking orders, anything you would otherwise put on a job queue. Scale is horizontal and needs no configuration. Start a second process with the same class and the same queue drains twice as fast, because both are racing for the same entries. The lease is the whole failure story: kill a scout mid-search and its TAKE lease lapses, the request reappears, and a sibling picks it up.

Route by field. where narrows the take to entries whose fields hold given values. Each filter reads "field op value", where op is =, !=, <, <=, >, or >=, or "field in a,b,c" for a list. When the field's string form and the value both parse as decimals the comparison is numeric, so 3.0 equals 3; otherwise it follows string order, and a null field matches only !=. The binder compiles the filters onto the method's template the way it compiles tags, so the space judges them before this worker claims anything: a task addressed to another shop is never leased here and stays in the space for the worker it names. The binder checks every filter at bind time against the parameter type and refuses one that names a missing component, or one it cannot parse, naming the method. Example 18 deploys one shop class per region, and each takes only its own tasks.

Sealed returns. A method may declare a sealed interface as its return type. The binder writes whichever permitted subclass the method returns, and the card lists every permitted subclass as produced, so a planner reading the card sees both branches of a decision the method makes per entry. Example 18's registrar returns one of two records: a registered claim that cues every specialist, or a rejection that the ledger closes.

One take may also return several entries at once. The binder completes the take once and then writes each element of an Entries return as if the method had returned it alone; the fork, under @SpaceNotify, covers that return and the produces attribute that tells the card what is inside it.

Invoked for every matching entry written to the space, without consuming it, and a non-void return value is written back as the next entry in the flow. React to X, produce Y; Y is some other agent's cue. The binder carries the discipline so the method body never has to: delivery is deduplicated per entry (within a bounded in-memory dedup window for this subscription), the reaction runs on its own virtual thread so slow work never holds the fabric's delivery thread, and a null return writes nothing.

Reach for @SpaceNotify when the trigger is "something appeared" rather than "there is work to claim". Nothing is consumed, so every interested agent sees the same entry, which is exactly what you want for fan-out, for derived records, and for side effects like audit and notification. Returning a value is the compact form of a pipeline: an agent that returns Y from an X has declared one edge of a flow, and the next agent's @SpaceNotify on Y is the next edge. Nobody wires the graph; it exists because of what each agent consumes and produces.

The example above shows both halves of the common shape: react with @SpaceNotify, then write through @SpaceRef handles when one reaction needs to produce many entries, or entries in other spaces, rather than the single entry a return value can express.

Route by field. where takes the same filters as @SpaceTake, "field op value" or "field in a,b,c" with the same comparison rules, compiled onto the subscription's template, so the method sees only the entries that pass and a != filter lets everything but one value through. It also breaks the loop the note above warns of when the reaction cannot change the type: filter on a field the reaction never produces. The binder checks every filter at bind time against the parameter type and refuses one that names a missing component, or one it cannot parse, naming the method.

The fork. A reaction that produces several entries can return them together as Entries, built with Entries.of(Object...) or Entries.of(List), and the binder dispatches each element in order exactly as if the method had returned it alone: a plain entry, a Tagged entry, a Motion, or a Contribution. The binder refuses a nested Entries and a null element. From a @SpaceTake or @OrderedTake it completes the take once, before the first element. The card cannot see inside the collection, so the annotation's produces lists the element types; @SpaceTake, @OrderedTake, and @SpaceJoin carry the same attribute. Example 18's quote desk forks one assessment into a request that says how many quotes to expect and one task per shop, which the shops above route on.

The deadline. on names the event kinds the method reacts to, WRITTEN by default. With on = SpaceEvent.Kind.EXPIRED a leased entry becomes a timer: write a reminder with the lease you are willing to wait, and when it lapses the reaction fires with the entry that expired. Any set of kinds is allowed and the binder delivers each entry once per kind, so {WRITTEN, EXPIRED} sees the write and the lapse as two deliveries; REAPPEARED is a dead worker's signal and COMPLETED says the work finished elsewhere. The binder refuses an empty set at bind time as a method that reacts to no event kind. Example 18's underwriter writes the reminder as it opens the vote, and an escalator reacts to its lapse.

On an AUCTION space, every take carries a bid and the lowest bid takes the entry. The bid is a plain method over the entry, so cost models are ordinary code: denominate in dollars, tokens, or queue depth, and let FinOps tune it.

This is the shape worth studying, because it answers the organizing question directly: the bid function, the worker, and the space handle live in the same object. That is deliberate. A bid is a statement about what this particular agent would charge, so it needs the same state the work needs: the model it would call, the queue it is already sitting on, the region it runs in. Splitting them apart would mean keeping two things in sync for no gain.

Reach for AUCTION when workers are not interchangeable and you want the fleet to sort that out without a router. Several planners bid on every day of a trip; the one whose day it should be bids lowest and takes the day, and nothing anywhere contains a rule saying who plans what. Change a bid function and you have re-tuned the whole allocation. The same shape does cost-aware model routing (cheap capacity sweeps easy work, the expensive model takes the hard entries), locality routing, and load shedding by bidding your own queue depth.

Injects a Space into a field at bind time, for mid-method writes such as progress markers and side outputs. Under Spring, @Scheduled plus a @SpaceRef field is the idiomatic periodic agent; AgentSpaces ships no scheduler of its own. What arrives is the registered space itself or, when the fleet runs with agentspaces.identity.agent-keys=subordinate, this agent's view of it, so everything the agent writes, takes, or completes through the field is signed with the agent's own certified key and attributed to the agent itself rather than only to its host peer (agent certificates). The field's type and your code do not change either way.

Use it whenever one invocation has to produce more than the single entry a return value can express: progress markers mid-task, fan-out like the dispatcher's, side outputs into a different space, or reads that inform the work (the dining planner reads what the scouts found before it writes a schedule). The field is a fully-featured Space with every verb of the Space API.

It is also the answer to "how do I get a space into code that is not a bound method". A @Scheduled method, an HTTP controller method, a message-listener callback: annotate the field, and as long as the enclosing bean is enrolled, the handle is there. AgentSpaces ships no scheduler, no HTTP layer, and no inbox of its own precisely because your framework already has them.

The Layer 4 annotations for the vote and the aggregate, and the two that reach any capability. @Ballot casts, @OnDecision reacts once when a vote closes, @Propose opens one, @OnEstimate fires when a fleet-wide estimate settles, @CapabilityRef injects a typed client, and @ProvidesCapability serves a capability of your own. Each binds a behavior to a capability the peer must already hold, which is why Layer 4 assembly comes first; chapter 12 covers the services themselves.

The first of the Layer 4 annotations, and the shape the others follow: the method's parameter is the cue and its return value is what the binder does with it. Here the cue is the vote's own Proposal entry and the return is the option this agent backs; the binder casts through the group's vote capability, using the bound agent's identity with subordinate keys, and deduplicates proposals within this binding, and a null return abstains. Because the cue is the proposal record, the ballot can never be refused as "unknown proposal"; the two-entry race every hand-written panelist had to defend against does not exist.

One vote space usually carries several decisions, so prefix narrows a method to the proposals whose id starts with it: the Party Bus keys them advisory: and next:. Under agent-keys=subordinate the ballot is the agent's own attested record, so several agents on one peer are several voters wherever the authorizer counts per agent (security).

The pair of @Ballot. The method takes the Decision and runs once per proposal per subscription, the first time this replica's tally meets the quorum; a non-null return is written as the next entry in the flow, like @SpaceNotify. Underneath, the binder watches ballots and proposals in the vote space and recomputes the decision on each, so a replica that learns of a vote late still fires once, on its first qualifying ballot. This replaces the decision() poll loop that every consumer of the vote used to write.

The opening side of the vote, for a lead whose options, quorum, and lease are fixed and whose cue decides only the question. The method takes the cue and returns the question as a String; null asks nothing, and the method may return a Motion instead when one cue needs a shape of its own (the Motion return). The proposal id is the prefix plus the cue's key: the key fields read from the cue and joined by :, or the value of the cue tag that keyTag names. One of the two is required unless the method returns a Motion carrying its own id. @Ballot and @OnDecision filter on the same prefix, so the three annotations describe one vote across the classes that open it, judge it, and record it. This replaces the VoteCapability field, the proposed set, and the read-before-propose guard that every lead used to carry.

The binder owns the rest. It subscribes to the cue as @SpaceNotify does, under a leased subscription renewed at half-lease, with the same bounded per-entry dedup. It derives the proposal id from the cue and invokes the method once per proposal id per bound agent, so several cues that map to one id (every channel's assessment of one wave) ask one question. It opens the proposal once per replica, as the bound agent, and skips a motion whose proposal is already visible on the vote space. It declares an action of kind propose on the agent's card, which nobody can invoke remotely. The key rule is the one Template.where and @SpaceJoin use (Keys): a record component or a getX, isX, or plain x() accessor, resolved at bind time so a missing field fails fast naming the type.

The read side of the Contribution return, and the aggregate's counterpart to @OnDecision. The method takes a PushSumAggregate.Estimate, a record of the epoch id, the operator, the value, and the protocol ticks this replica has run since it learned of the epoch, and fires once per epoch, the first time this replica's estimate has stayed within tolerance (relative, of the larger of one and the last value) for settleTicks settle steps; settleTicks = 0 fires on the first estimate present. A settle step is one gossip round this replica took part in after it first heard the epoch, or the epoch going quiet. Rounds run about once a second under a driven peer whatever the 250 ms tick (PushSumAggregate.ROUND_PERIOD is one second), so settleTicks = 40 is about forty seconds. A non-null return is written as the next entry in the flow, or opens a Motion, as any bound method's return does. The capability evaluates the rule inside its own tick(), so no thread polls, and the listener runs on a virtual thread so a slow reaction never holds the peer tick. This replaces the awaitEstimate loop that every supervisor used to carry.

The sibling of @SpaceRef for Layer 4: a field of a typed client type (VoteClient, AggregateClient, SemanticClient, or anything registered with binder.client(type, instance)) is injected at bind time from the group's typed clients. Constructor injection still works and is still fine; this is for when the agent should not have to be handed its capabilities by whoever constructs it.

The vote has the same kind of return value: a Motion, the vote-side sibling of Contribution. Motion.of(id, question, options, quorum, lease) names the sole registered vote space and Motion.in(space, ...) a particular one, and any bound method may return it. The binder opens it as the bound agent, once per proposal id per replica, and skips a motion whose proposal is already visible; for a take, it completes the taken entry first, so a failed open never makes a finished task reappear. This is the dynamic form of opening, for a lead whose options or quorum come from the cue; when only the question does, @Propose says the same thing as one annotation. Plain code opens the same idempotent way through VoteClient.propose(Motion). A method that declares a Motion or Contribution return type fails at bind time when its capability is missing, naming the registration, so the gap shows before the first value comes back; a declared Motion return also puts VoteCapability.Proposal on the card as what the action produces.

Marks a CapabilityProvider implementation as a service the fleet should advertise. Bound through the facade, it is registered on the group's CapabilityRuntime, which starts it, signs and publishes its CapabilityAdvertisement, and keeps that advertisement fresh on every card refresh, the same TTL-leased freshness every other card gets. Consumers reach it through a typed client (capability services).

You need this only when your peer is the one serving a capability. Most peers consume capabilities instead, which needs no annotation at all; see the capability services. And with the starter you rarely write this either: agentspaces.capabilities.* already registers the aggregate, vote, semantic-discovery and key-wrap providers for you. Write the bean when you want a capability the starter leaves off (the ordered log, which needs a member set the starter cannot guess), when you want to configure one differently (a gossip learner with a real training step), or when you are publishing a capability of your own.

Three annotations for the promises a lease race cannot make on its own. @OrderedTake completes an entry at most once fleet-wide, through the ordered log. @SpaceJoin fires once per key when every part of a case has arrived, with a mode that says once per joiner, once per lease, or once fleet-wide, and @Part describes each part. @SpaceReduce folds a stream of entries per key into an accumulator that is itself an entry. The ordered forms need the coordinator of the ordered log registered on the group.

@SpaceTake's contract (take, act, complete-or-lapse) with the take routed through the space's ordered-log coordinator instead of the space's own claim race, so the log's commit order decides every take identically on every member and each entry is completed at most once, fleet-wide. The binder owns the loop the coordinator asks of a caller: a take lost to a leader election is simply resubmitted on the next poll. This closes what the space chapter used to call "the one place the annotations cannot reach".

The join of a fan-out, as one method. The method takes a Joined bag and returns the next entry, and the binder invokes it once per key when every required @Part of that key is present in the space. A part names its entry type (value) and, where the defaults do not fit, the space it lives in, the key field or the keyTag that carries the case's key, tags filters that narrow it the way tags narrows a @SpaceTake, and optional when the join should fire without it. The join's own space is where its tickets live in the fleet-wide modes and the default space for its parts; its key is the field every part carries unless a part says otherwise.

How many times one key fires is the mode:

The binder owns what a hand-written join owns. It subscribes to each part, seeds its per-key state from the space on bind so parts that landed earlier still count, and seeds again for any key it meets for the first time, so a key it forgot is picked up from what the space still holds. When a key completes it re-reads the parts by key and hands the method the newest entry of each type. It forgets a key whose parts stop arriving after within, and keeps at most maxOpen keys open, evicting the least recently touched beyond that. The Joined bag answers key(); get(type) for the newest part of a type, which throws when the part is absent; find(type) for an optional part; all(type) for every matching entry, newest first; has(type); and entry(type) when the issuer, tags, or lease of a part matter. The method returns like every other binding: the next entry, a Tagged entry, a Contribution, or null.

The gather. A part may need more than one entry of its type before the key is complete. @Part(atLeast = n) waits for n of them. @Part(countedBy = "SimpleTypeName.field") reads the count from an int field of another part of the same key, whenever that part lands, before or after the entries it counts, so a fork can declare how many it emitted and the gather waits for exactly that many. @SpaceJoin(settle = "300ms") ends a gather of an unknown number: the key fires once it has been quiet that long and every minimum holds. A join with a single part is allowed when that part gathers or the join sets settle, even with atLeast = 1. The method reads what the key collected with Joined.all(type). Example 18's gatherer waits for as many quotes as the quote desk's request declared and keeps the lowest.

Each element of parts is a @Part: the entry type a key needs, where that type's key is read from, and how many of it the key needs. A part's key comes from a field (the join's key by default, or the part's own) or from a tag (keyTag), which is how a type that does not carry the key as a component, an ontology instance for one, still joins. Tag and field filters narrow the part the way tags and where narrow a @SpaceTake.

A fold over an unbounded stream of entries per key, whose state is itself an entry. The method takes the key's current accumulator, null on the first step, and one element, and returns the new accumulator. The binder takes the element under a lease, invokes the method, and completes the element with the new accumulator as the result in the same space: one atomic step, so an element is never folded twice. It then retires the previous accumulator. A JoinTicket per key, taken before a drain and completed after it, serializes the steps of one key; a reducer whose ticket is not the key's oldest live one backs off. Under ORDERED the ordered log decides which ticket holds the key; under LEASED the older-ticket check is exact within one process and best effort across replicas, so only ORDERED guarantees that two reducers never fold one key at once. The accumulator is rewritten under accumulatorLease on every step, so that lease is the key's idle timeout: a quiet key lapses, and the lapse is an EXPIRED event a @SpaceNotify(on = EXPIRED) on the accumulator type can treat as "the session closed". This is the third form of reduce: the gather folds a bounded set per key once, the aggregate folds a number across the fleet, and this folds a stream per key with a value that is always current, exact, durable, and readable as an entry by any peer or client.

The PetClinic scheduler used to keep its slot book in two AtomicIntegers, which a restart reset and a second scheduler duplicated; the flagship's test now runs two schedulers through a restart and books every visit once. The return is the accumulator, a Tagged accumulator (its tags merge beneath the binder's), or an Entries fork holding exactly one accumulator and any side outputs, which the binder writes after the atomic step the way a fork's elements are written; null consumes the element and leaves the accumulator as it was. The key is a field of the element (key) or one of its tags (keyTag); with neither, every element folds into one accumulator, which serializes them all through one ticket. The accumulator lives beside its elements, since the atomic completion needs one space; a stage that wants it elsewhere reacts to it and writes a copy.

The starter (agentspaces-spring-boot-starter) wires the peer from properties and enrolls annotated beans through an ordinary bean post-processor. It deliberately declares no Spring dependency of its own; it compiles against provided-scope stubs and binds to the Spring your application already runs.

With only seeds configured, the starter dials the list and expands names that resolve to several addresses. Add ai.badmonkey.agentspaces:agentspaces-bootstrap-spring-boot-autoconfigure:0.4.0 beside the starter, and the agentspaces.bootstrap.* keys build each group's chain from the locators. A group's own bootstrap block overrides the fleet-wide block, key by key, and the full key list is in the agentspaces-bootstrap README.

Every step is a bean the application may define, and each default yields to yours. The core starter collects the BeaconLocator, Transport, PeerNodeCustomizer, and PeerNodeConfigurer beans, and the bootstrap module adds a DnsResolver and a BootstrapChainFactory:

One property sets the whole posture. agentspaces.security.profile picks the transports and channel mode a fleet forms over (the default, mtls, means a fleet comes up over TLS with attested channels and no further configuration), and it also picks who answers the one question every privileged operation asks: authorizer.permits(peer, operation, scope).

Under dev-local and mtls the answerer is membership-rooted, one authorizer per group over the group's admitted members, narrowed by the optional grants lists; a grant never outlives admission. Under mtls-oidc and zero-trust it is your identity provider: each peer carries its JWT inside its own signed self-advertisement, the token's agentspaces_peer claim binds it to one PeerID, and scopes of the form aspace:<operation>[:<scope>] decide. A token is valid in every group a node joins, so each group's authorizer also requires the peer to be a current member of that group and refuses a peer or agent the group has revoked; the scopes decide only after those two checks pass. Incomplete OIDC configuration fails at startup rather than at the first refusal. The agentspaces-auth-oidc module supplies that answerer: its OidcAuthorizer validates each peer's bearer JWT against the issuer's JWKS and is the Authorizer the MTLS_OIDC and ZERO_TRUST profiles install.

The starter threads the authorizer into the key-wrap provider, spaces admitted by authorizer, the vote tally, and the DirectiveGates bean workers use to obey the console. Pass the Authorizer bean, or Authorizers.forGroup(name), to a RaftLog, DataQueryClient, or ConnectorRuntime you wire yourself.

After initialization, any bean declaring an agent identity or carrying bound methods enrolls automatically: @SpaceRef and @CapabilityRef fields inject first, then bid functions wire, worker loops start, subscriptions register, and one card publishes per group the bean bound into. Group selection is by space coverage, narrowed by any group attribute the annotations carry: a bean binds into each configured group whose spaces cover the spaces it names, and a bean naming a space no group registers fails at startup, which is when a configuration mistake should show. A @ProvidesCapability bean registers on the group's capability runtime the same way. A SchemaRegistry bean, when you declare one, is applied to every space the starter builds and to every card it publishes, so records and cards name each type the same way (the schema registry section shows NamespaceSchemaRegistry). Plain beans pass through untouched.

The facade bean is there when you outgrow the annotations: AgentSpaces navigates groups and spaces Embabel-style, with the typed verbs of the Space API as terminal operations.

The embabel-agentspaces extension activates only when Embabel is on the classpath, and it works in both directions: your Embabel agents become discoverable to the fleet, and the fleet's discovered skills become actions for your planner.

Every Embabel @Agent bean's metadata, its description, its @AchievesGoal statements, and its @Action input and output types, becomes a published AgentCard automatically. Worker loops still come from @SpaceTake on the action, so an Embabel action joins the fleet with one added annotation:

The remote-actions bridge turns eligible foreign AgentCard actions into typed, invocable actions when their input and output classes resolve locally and their task space can be selected. Invoking one is choreography, never RPC: the bridge writes the input entry where the remote workers take that type from, then awaits a result entry that correlates with the request (by default, equal values on every record component name the input and result share, the convention a Finding carrying its ResearchTask's topic already follows). A remote worker that crashes mid-step lets its lease lapse; whoever finishes, the awaited result still arrives. An invocation nobody serves times out empty with the entry still leased in the space. Since v0.1.13 a card declares its actions, each pairing what one bound method consumes with what it produces and carrying that method's description, so the bridge offers exactly those pairs instead of every consumed-by-produced combination, and falls back to the cross product only for older cards. RemoteAction.declared() exposes the declared action.

For the GOAP planner, EmbabelRemoteActions generates a class annotated @Agent with one real typed @Action method per remote action (card goals become @AchievesGoal), because the planner conditions on method signatures. The proven consequence: an agent whose local actions cannot chain to a goal type finds no plan alone, and finds and executes the multi-hop plan through remote specialists the moment the fleet's cards are bridged in. Cards are TTL-leased, so the planner's action space tracks the live fleet.

Deployment keeps itself current. With agentspaces.embabel.auto-deploy on (the default) a deployer watches the bridge's registry on a virtual thread and redeploys a freshly generated agent whenever the set of actions changes: the first time cards arrive, when a new card brings a new capability, and when an expired card takes one away. A card refresh that changes nothing but the issue time does not redeploy. Embabel's platform exposes no undeploy in the API this module reaches, so an action that disappears is absent from the next generated agent while the previous generation stays registered until the platform restarts; invoking one of its vanished actions times out and throws, which the planner treats as the action failing.

Add ai.badmonkey.agentspaces:embabel-agentspaces:0.4.0 (a module of the core repository) alongside the AgentSpaces starter and your Embabel application dependencies. The extension reads Embabel annotations reflectively; it does not install an Embabel platform. Automatic deployment requires the application’s AgentPlatform bean.

The metadata path and the execution path have different jobs. @Agent, @Action, and @AchievesGoal describe capabilities; they do not start tuple-space workers. Add a one-argument @SpaceTake or @SpaceNotify method for execution. An Embabel action taking OperationContext as a second argument cannot also be a bound space method: move the reusable work behind an injected service and expose a single-domain-argument adapter.

Embabel metadata excludes infrastructure parameters in com.embabel.*, primitives, and String from domain schemas. Use records or domain classes at the fleet boundary. A multi-input planner action may describe several domain types, but the remote bridge generates one-input actions; adapt such work to one request record rather than expecting it to ship an Embabel execution context.

Outbound cards publish into every configured group. A bean with @AgentSpec or its @SpaceAgent stereotype uses the core binder’s card instead of receiving a second Embabel-derived card. The default inbound bridge uses the first configured group and excludes this peer’s cards; local actions remain the local planner’s responsibility. For another group or custom routing, replace the EmbabelRemoteActions bean.

Declare both spaces in that group on the caller and workers. Set agentspaces.embabel.auto-deploy=false for manual deployment through bridge.deployTo(platform); remote-actions-enabled=false disables the default inbound bridge while outbound card publication remains available. This lets a worker-only application advertise capabilities without importing the fleet into a planner.

The card is an advertisement of a capability rather than a private endpoint. A tool or planner action named after an agent writes a typed entry that any eligible worker may serve. Use a distinct request type or space admission when work must be restricted; selecting a card by name alone does not pin the executor.

agentspaces-springai is a separate library, in its own repository at github.com/badmonkeyai/agentspaces-springai, built on the published AgentSpaces artifacts. Spring AI gives an application a portable way to call models; the fleet gives a set of processes a shared, leased, signed, replicated space. The library plugs the second into the first through Spring AI's own extension points (tools, advisors, chat memory, ChatModel, EmbeddingModel, observations, and MCP), so an application stays ordinary Spring AI code while its agents coordinate across machines.

It needs no Embabel. The Embabel extension integrates at the level of a planned agent and its actions; this one integrates at the level of a model call and its tools. An application can use either or both. It needs Java 21, Spring Boot 4.1, Spring AI 2.0, and the Spring Boot starter beside it:

The library is on Maven Central with the core. It releases from its own repository on its own cadence, so it carries its version explicitly; the BOM of the quick start manages the starter's.

Nine feature families, configured under agentspaces.springai. Most use an enabled switch; discovery tools and capability tools have individual switches, and embeddings use embedder.type. Fleet tools and the take-lease advisor are on by default. Everything that widens what a model can reach, or sends prompts across the fleet, is off until you turn it on. The spaces a feature uses must be declared under agentspaces.groups[].spaces like any other; a missing one fails at startup with the YAML that adds it, so the space has the group's admission, encryption, and block exchange from the start.

A worker is a @SpaceAgent bean with an injected ChatClient.Builder and a @SpaceTake method, exactly as @SpaceTake describes it. The space distributes the work, the model does it. What the library adds is the lease discipline an agentic loop needs: TakeLeaseAdvisor runs inside Spring AI's tool loop, after the ToolCallingAdvisor, and renews the in-flight take lease once per model round-trip (and on an interval while a streamed round-trip runs). A worker making progress keeps its claim however long its loop takes; a worker process that crashes stops renewing, and its task reappears when the take lease expires. Leases can therefore be short, which makes recovery fast.

With memory.enabled, the worker's conversation lives in a replicated space too. SpaceChatMemoryRepository is a Spring AI ChatMemoryRepository that writes each save as the conversation's next leased snapshot and retires the older ones, so an abandoned conversation leaves the space on its own and a snapshot over 64 KiB travels content-addressed. FleetChatMemoryAdvisor keys the conversation by the in-flight take's entry id by default (conversation-id: take; agent and explicit are the alternatives), so a task that reappears after a crash resumes on another peer with the conversation it had.

Every AgentCard in the group declares the actions its bound methods consume and produce (the binder). FleetTools turns each into a Spring AI ToolCallback: the tool's input schema is the action's consumed type, its description is the method's, and its name is the prefix, the agent, and the input type (fleet_summarizer_Brief). Calling the tool writes the input as a leased task entry and awaits the correlated result, the same choreography the remote-actions bridge of the Embabel chapter performs. The provider resolves the set for each request, with a snapshot cache (default tools.cache-ttl=1s), so arrivals and expiries become visible after that cache refresh; a FleetToolsChangedEvent announces each change.

Which cards become tools is a deployment decision: include-agents and exclude-agents lists, require-attested to admit only agents signing with a certified key of their own (agent certificates), or a FleetToolFilter bean for a rule of your own. ToolNamingStrategy is the other replaceable default. A tool call waits tools.timeout for its result; on expiry it returns an explanation to the model (on-timeout: result) or throws (throw).

Three more tools let the model look around rather than act. FleetDiscoveryTools offers find_fleet_agents, list_fleet_assets, and fetch_fleet_data over the discovery and connector layers of discovery and the connector SDK, each switched on separately because each widens what the model can reach. And vector-store.enabled serves the application's own Spring AI VectorStore as a fleet data asset through the connector SDK, so any agent in the fleet queries the shared knowledge base with leased, pull-once results: an identical question inside the freshness window reads the answer from the space instead of searching again.

FleetChatModel is a Spring AI ChatModel whose provider is the fleet. Each round-trip becomes a ModelRequest entry in the model space; a ModelServer on a peer that holds the credentials takes it, stamps the attempt, calls its provider, and completes the take with the response, so the answer and the request's removal land together. The caller needs no API key and no provider dependency. A server that dies mid-call lets its lease lapse and another serves the request with the next attempt number; the response metadata carries agentspaces.servedBy and agentspaces.attempt. Requests route by model name, or by price when the model space runs AUCTION and each server bids its prices.<model>. A streamed request writes the provider's deltas as short-leased chunk entries, assembled in order on the caller; cancelling the Flux writes a ModelCancel that stops the server; and stream.on-restart says whether a stream whose server died fails or restarts on another.

The design leans on Spring AI 2.0's split between the model and the tool loop. ChatModel.call performs one round-trip and never runs tools, so a server never executes anything on a caller's behalf: tool calls come back in the assistant message and the caller's own ToolCallingAdvisor runs them, with the caller's own tools. Media travels content-addressed over the group's block exchange, like any entry over the inline limit. Four interfaces with one default bean each cover what a deployment might want to change: ModelCatalog (which models this server offers), ModelRequestRouter (by model or by price, or by tenant, region, or load), StreamChunkingPolicy (latency against entry count), and StreamRestartPolicy.

Embeddings. Semantic discovery (capability services) ranks with a pluggable Embedder, and the shipped one is lexical. embedder.type: spring-ai replaces it with SpringAiEmbedder over the application's EmbeddingModel: vectors are L2-normalized, cached by the text's content hash so a card is embedded once, and the embedder's identity (spring-ai:<model>) is advertised on the capability, so peers query only peers that rank alike and a fleet never averages two models' notions of similarity.

Usage. With usage.enabled, FleetUsageObservationHandler reads token counts from Spring AI's gen_ai observations and hands them to a UsageSink. The default, FleetUsage, keeps this peer's counts per model and per agent. When usage.metrics-space names a space, it also writes each call there as a leased ModelUsage entry for audit and, on every publish-interval, this peer's running total per model as a ModelUsageTotal under a lease of three intervals (ten seconds at least), so any peer reads fleetTotal(model), the sum of the newest total from each peer, with no collector. Without a metrics space the sink keeps local counts only and fleetTotal is empty. UsagePanel puts the figures on the fleet console (the fleet console). Replace the sink to export to a billing or FinOps system.

MCP export. MCP clients such as Claude Desktop or an IDE agent sit outside the fleet's trust boundary, so nothing is exposed until mcp.include-agents names the agents that may be. Export also needs the FleetTools bean (tools.enabled, the default) and a synchronous MCP server bean (McpSyncServer). FleetMcpToolSync then publishes those agents' tools through Spring AI's MCP server, and on every FleetToolsChangedEvent adds and removes tools and sends notifications/tools/list_changed, so connected clients refresh as cards arrive and lapse. mcp.discovery-tools exports the three discovery tools too, and mcp.capability-tools exports the enabled capability tools.

Nothing in the library is needed for a model to take part in the fleet's coordination; the annotations already do it, and the patterns module shows three shapes, each on its own small fleet over TCP with scripted models so it runs offline. Judges: a panel of @Ballot agents whose vote comes from Spring AI's FactCheckingEvaluator over each judge's own model, and a lead whose @OnDecision records the verdict when the quorum closes; every ballot is a signed entry, so which judge, on which peer, voted how is auditable from the space. Priced by tokens: model workers on an AUCTION space whose @BidFunction is the model's price per thousand tokens times an estimate of the prompt, bidding infinity for tasks harder than the model handles well, so routine work goes to the cheap model and hard work to the premium one with no router. Extraction ensemble: extractors on different models react to every document with @SpaceNotify and write a candidate carrying a confidence, voters back the most confident with @Ballot, and a filer's @OnDecision files the winner with the tally as provenance.

All under agentspaces.springai. group names the group the library works in (default: the first configured).

Start with the smallest role that does the job. Enable features on the peers that own them, and declare every feature space in the selected group. The integration does not need Embabel; an Embabel application can use these same workers or a Spring AI model service alongside its planner.

Inside a take, the default conversation key follows the entry across workers. In a controller or scheduler there is no take context; take and agent modes cannot invent one. Pass an explicit conversation id, or provide a ConversationIdResolver bean keyed to your application’s session.

The task’s write lease bounds how long uncompleted work remains useful. Its take lease bounds how long another worker waits after a claim stops renewing. The caller’s timeout bounds how long it waits for an answer. Set all three for the workflow rather than copying one duration everywhere.

TakeLeaseAdvisor renews before each synchronous model round-trip. A blocking call or tool operation that exceeds the lease can still lose its claim. During streaming, the advisor schedules renewals until the stream terminates, even if no new token arrives; it is not a hung-stream detector. Set provider/stream deadlines, and keep take-lease.stream-renew-interval shorter than the take lease. A manually constructed client must receive the advisors explicitly.

Model streaming has its own recovery contract. The default fail policy raises FleetStreamRestartedException with partial text. restart signals a new attempt and replays from its beginning: downstream consumers must reset the partial answer instead of appending the new attempt as if it were a continuation. Cancelling this model-client stream sends ModelCancel; a fleet tool timeout has no equivalent cancellation guarantee.

For model servers, protect model and conversation spaces with the group’s admission and content-key policy. The caller verifies response/chunk issuers against MODEL_SERVE for the model; use membership grants or the OIDC model-serve scopes for the selected security profile. Fleet tool filters and MCP allowlists complement these permissions; they do not replace them.

Auto-configuration backs off for these application beans. A custom RemoteActions bean also supplies explicit task routes, result routes, and correlation to Spring AI tools. Fleet-wide usage totals need usage.metrics-space; without it the default sink still keeps local counts. Each peer republishes its running total under a lease of three publish intervals (ten seconds at least), so a peer that stops publishing drops out of the fleet total; use retained, deduplicated audit records or a dedicated accounting sink when exact billing matters.

The checked-in examples use scripted models and run without provider credentials. Use them to test coordination first, then add a live provider as a separate integration check. The Spring AI repository includes context tests for configuration and TCP flow tests for tools, crash recovery, streaming, routing, retrieval, usage, and MCP.

agentspaces-micronaut is a separate library, in its own repository at github.com/badmonkeyai/agentspaces-micronaut, built on the published AgentSpaces artifacts. It does for a Micronaut microservice what the Spring Boot starter does for a Spring Boot application, and then takes the step the shape of a microservice invites: a service is both an agent and a data source, so its annotated beans publish AgentCards, its data and its HTTP presence publish AssetCards, and other services resolve it through @Client with the fleet as the registry. It needs Micronaut 5.2, which runs on JDK 25; the library itself is Java 21 bytecode.

The library, its processor, and the LangChain4j and MCP bridges (agentspaces-micronaut-langchain4j, agentspaces-micronaut-mcp) are on Maven Central with the core and carry their version explicitly, since they release from their own repository.

The fabric is configured by the same agentspaces.* properties as the Spring Boot starter, with the same names and defaults: the security profile, transports and TLS, groups founded or joined, spaces with admission, content keys, capabilities, the console, the A2A gateway. One YAML fragment configures a peer under either framework. Durations take ISO-8601 (PT5M) or the short form (5m, 250ms). What the library adds lives under agentspaces.micronaut.

A Micronaut service is a natural fleet member because it already has the three things a peer needs: beans that do work, data it owns, and an address other services call. The library turns each into a card, and the cards are what the rest of the fleet, in any framework or language, sees. The shapes below compose; a real service is usually two or three of them at once.

Two things make these cheap. The configuration is the starter’s property set, byte for byte, so a team that runs the Spring starter already knows how to configure a Micronaut peer, and a YAML fragment moves between the two. And every feature is a bean behind a @Requires on its property, so a service enables the shapes it plays and pays for nothing else: a pure data service never starts the registry or the bridges, and a pure gateway never enrolls an agent.

Micronaut singletons are lazy, so nothing waits for a bean to be created. On StartupEvent the library finds every bean definition carrying @AgentSpec (directly, or through a stereotype such as @SpaceAgent, which is a bean-defining annotation and an @AgentSpec at once) or @ProvidesCapability, instantiates it, and binds it through the facade: worker loops start, bids wire, and the AgentCard publishes into every joined group whose spaces satisfy the bean's annotations. The annotations are unchanged. A bean naming a space no group registers fails at startup with the bean, the spaces, and the configured groups.

One implementation, two front doors: HTTP clients POST to the controller, fleet agents write a PriceRequest into the task space, and the service's AgentCard lists price as an action any agent invokes through RemoteActions (remote actions), Spring AI tools included. The agent is a plain bean on purpose. A Micronaut AOP interceptor binding (@Retryable, @Cacheable, @Transactional, a custom @Around) generates a subclass whose overriding methods carry none of the fleet annotations, and the binder reads the runtime class; such a bean fails at startup saying so. HTTP concerns like @ExecuteOn, which is not AOP, belong on the controller that delegates to the agent.

A bean whose only fleet annotations are on methods, such as a plain @Singleton with a @SpaceNotify method, enrolls when the application compiles with agentspaces-micronaut-processor on the annotation-processor path. The processor maps each core method annotation, by name, to a marker that is @Executable(processOnStartup = true), the way Micronaut's own @Scheduled works, and to @ReflectiveAccess; Micronaut then hands every such method to the library before StartupEvent, and the bean is enrolled once. Without the processor, give such a bean @SpaceAgent.

Every AssetProvider bean is served through the connector SDK (the connector SDK) on the data space, agentspaces.micronaut.assets.space (default data, registered under the group like any other). The peer runs one connector runtime over all of its providers, because two runtimes on one space would race for the same query, so a query goes to the provider that described the asset, cards publish and refresh on the card cadence, and the profile's authorizer is asked CONNECTOR_SERVE before anything is advertised. TableAssetProvider serves an in-memory table; a provider over a Micronaut DataSource is the shape of a real connector.

With service-asset.enabled, the embedded server itself publishes an AssetCard once it has bound: asset micronaut.application.name, the server's URI (or external-uri behind an ingress), shape http, freshness live, and under access the scheme, the instance id, and whether it answers queries. service-asset.query: get with allowed-paths lets a fleet agent that has no network path to the service GET an allowed path through the space and receive one row (status, content-type, body); it is off by default, bounded by a timeout and a body cap, and authorized like every other connector query. ServiceAssetCustomizer beans adjust the card. Give the service card and any table asset different names.

agentspaces.micronaut.registry.enabled adds a Micronaut DiscoveryClient over the group's ad-cache. A service id resolves to every peer whose AssetCard advertises an http asset of that name, from issuers the authorizer permits CONNECTOR_SERVE; Micronaut's composite discovery client includes it, so @Client("orders") load-balances across the peers that serve orders with no URL configured anywhere, and a card that lapses (its TTL passes without a refresh) drops its instance. Registration is the card itself: there is nothing else to register.

With micronaut-management on the classpath the peer reports itself: a readiness HealthIndicator named agentspaces whose details are the fleet summary (peer, profile, groups with member counts and spaces, local and remote agent cards, asset cards, enrolled agents, the connector and its counters); an InfoSource under agentspaces; and the /agentspaces endpoint, sensitive by default, which adds every card the peer sees. It reads and never writes, since command-and-control is the console's job. With Micrometer, gauges agentspaces.members, agentspaces.cards.agents.local, agentspaces.cards.agents.remote, and agentspaces.cards.assets per group, and agentspaces.agents.enrolled.

agentspaces.console.enabled serves the fleet console on agentspaces.console.port with the application's ConsoleViewCustomizer, ConsoleCommand, and ConsolePanel beans, and agentspaces.a2a.enabled serves the A2A gateway with agentspaces-a2a on the classpath. Both are built by the Spring starter's own build methods and keep its rules: the console serves on the loopback interface, and the A2A gateway refuses to bind a routable address without a token or an OIDC gate.

agentspaces-micronaut-langchain4j plugs the fleet into LangChain4j's own extension points, the way the Spring AI library does for Spring AI, and the three ways to use it correspond to the three places a model can sit: inside a worker, inside an orchestrator, and on the fleet itself. They combine; example 17 (agentspaces-micronaut/examples/micronaut-ai-fleet) runs all three on three peers.

The simplest use needs nothing from the bridge but its lease discipline. A @SpaceAgent injects the peer's ChatModel (or an @AiService) and calls it inside @SpaceTake: the space distributes the work, the model does it, and the result completes the take. The bridge's TakeLeaseListener is a ChatModelListener that renews the in-flight take on every model request and response, and on an interval in between, so the lease can be short. A worker making progress keeps its claim however long its loop takes; a worker that dies stops renewing, and its task reappears when the lease expires. Listener beans reach OpenAI models automatically; the bridge attaches them to Ollama and Anthropic builders, and any other provider needs one BeanCreatedEventListener line on its builder.

With memory.enabled, the worker's conversation lives in a replicated space too. SpaceChatMemoryStore keeps each conversation as its latest leased snapshot and retires the older ones, and FleetChatMemoryProvider keys it by the in-flight take by default (conversation-id: take; agent and explicit are the alternatives), so a task that reappears after a crash resumes on another peer with the conversation it had. The snapshot is the shared wire record, so a conversation a Spring AI worker started resumes on a Micronaut worker and vice versa. A service picks the fleet memory with @AiService("fleet"), or every service gets it with memory.auto-apply: true.

An orchestrator is an ordinary @AiService. The bridge gives it the fleet: FleetToolProvider is a LangChain4j ToolProvider that, on every service invocation, returns the fleet's current foreign AgentCards as tools (fleet_<agent>_<InputType>, a JSON schema from the input record, the card's description and goals as the tool's description), so the tool set is live by construction: a worker that joins is a tool on the next request, and one that leaves is gone when its card lapses. A tool call writes the input into the agent's take space and awaits the result there, so a worker invoked as a tool completes in its take space. micronaut-langchain4j never looks a ToolProvider up on its own, so the bridge applies it to every @AiService as the service is built (tools.auto-apply, on by default); to choose per service, set it off and name FleetAiServiceCustomizer in @AiService(customizer = ...). @AgenticService agents receive the provider by themselves, since the agentic factory looks one up by agent name or default.

Which cards become tools is a deployment decision: agentspaces.micronaut.tools.include-agents and exclude-agents, require-attested to admit only agents signing with a certified key of their own (agent certificates), or a FleetToolFilter bean for a rule of your own; ToolNamingStrategy is the other replaceable default. A tool call waits tools.timeout for its result and then returns an explanation to the model (on-timeout: result) or an error (throw); tools.max caps the tools offered per request for large fleets, most recently seen first. Three more tools let the model look around rather than act: find_fleet_agents, list_fleet_assets, and fetch_fleet_data (discovery-tools.agents, .assets, .data), over the discovery and connector layers of discovery and the connector SDK, each switched on separately because each widens what the model can reach.

The third use removes credentials from most peers. model-server.enabled on a peer that holds a provider key serves its ChatModel beans to the fleet: requests are taken from the model space by the models the peer serves (named by each bean's default model name; models narrows the list, model-beans maps a name to a bean) or by price under AUCTION, with the take lease renewed while the provider runs, streaming in chunks, and an attempt counter a restarted request carries. model-client.enabled on a peer with no key gives it FleetChatModel and FleetStreamingChatModel, which @AiService resolves without configuration when the peer has no provider module: one request and one response per round-trip through the space, tool calls returned to the caller and executed with the caller's own tools, a response trusted only from an issuer the authorizer permits MODEL_SERVE for the model. Streams reorder chunks, fill gaps with a read-through, and follow a server's death by stream.on-restart: fail (the default) ends with FleetStreamRestartedException carrying the partial text, restart replays the new attempt from its beginning.

The wire records are the Spring AI module's, in the shared agentspaces-model-wire artifact, and the space names an entry type by its class, so a Micronaut LangChain4j peer and a Spring Boot Spring AI peer serve each other's model calls on one fleet: a Micronaut orchestrator can run on a Spring peer's models and a Spring worker on a Micronaut peer's. embedder.type: langchain4j ranks semantic discovery with the peer's EmbeddingModel (normalized, cached, identity langchain4j:<model> on the capability advertisement so peers rank alike), and usage.enabled records every response's token usage per model and agent, sums it across the fleet from each peer's running total in the metrics space (usage.metrics-space), and adds a console panel that, on a mixed fleet, shows both frameworks' usage as one.

MCP gives a client a tool list and a transport; the fleet gives a set of processes a shared, leased, signed space. agentspaces-micronaut-mcp connects the two at the fleet's edge, and the two directions are two different services.

A gateway peer runs micronaut-mcp's server (micronaut.mcp.server.transport, STDIO or HTTP) and mcp.export.enabled. The bridge publishes the fleet's tools, the same catalogue the LangChain4j provider uses, on that server and keeps them in step with the cards: a tool is added when a card appears and removed when it lapses. Over STDIO the server notifies clients of changes when micronaut.mcp.server.tools.list-changed is on; over HTTP micronaut-mcp 2.1 is stateless, and clients see the change on their next tools/list. A call from the client writes the task into the fleet and returns the worker's result, so Claude Desktop, an IDE agent, or any MCP client drives agents anywhere on the fleet, in any framework, through one endpoint, much as the A2A gateway serves A2A clients.

The export has its own include-agents and exclude-agents, separate from the in-process catalogue's, because an MCP client sits outside the fleet's trust boundary: a tool the orchestrator may call is not automatically one the outside world may. Authentication on the HTTP transport is Micronaut Security's, on the gateway's own routes. The bridge also makes the server advertise the tools capability even when it has no tools of its own at startup, since the SDK refuses to add tools to a server built without it and the fleet's tools arrive later, as cards do.

The reverse shape brings an MCP server the fleet does not own, a search service, a ticketing system, a vendor's tools, into the fleet without giving every peer a connection to it. An importing peer configures micronaut-mcp's LangChain4j client (micronaut.mcp.client.*) and sets mcp.import.enabled; the bridge publishes one AgentCard per client, agent mcp-<name>, one take action per tool, consuming McpToolCall(server, tool, argumentsJson, callId) and producing McpToolResult. A worker loop takes calls for that server from the import space, runs them through the client, and completes the take with the result. Every other peer, Spring, Micronaut, Python, or TypeScript, sees an ordinary agent and invokes it the ordinary way: through RemoteActions, as a LangChain4j or Spring AI tool, or by writing the entry. Tools are re-listed on each card refresh, so a server that adds tools gains actions, and a server that is not up at startup is retried.

Start with the smallest role that does the job. Enable features on the peers that own them, and declare every feature space under the group. The roles compose on one peer, and a fleet mixes them with Spring Boot peers configured the same way.

A task's write lease bounds how long uncompleted work stays useful; its take lease bounds how long another worker waits after a claim stops renewing; the caller's timeout (tools.timeout, model-client.timeout, a RemoteAction.invoke argument) bounds how long it waits for an answer. Set the three for the workflow rather than copying one duration everywhere. TakeLeaseListener renews around each model round-trip and on take-lease.stream-renew-interval while a streamed one runs; keep that interval shorter than the take lease, and keep provider deadlines on the model calls themselves, since the listener is not a hung-call detector.

Most decisions a deployment might want to change are an interface with a default the library registers behind @Requires(missingBeans = ...) or as a @Secondary; define a bean of the interface and the library uses yours. The AiServiceCustomizer row is the exception: an application names it per service.

The library tests its features with ApplicationContext.run(Map) contexts: they prove that the fabric, the registry, management, the console, the A2A gateway, the fleet tools, the model service, the capability tools, and the MCP export stay off until their property is set or switch off with it, that an application Embedder replaces the default, and that the per-service customizer opts one service in. Flow tests across two peers over TCP on free ports cover the paths that cross the fleet; the examples' tests boot two or three peers in one JVM with scripted models. Write the same for your service: a context test for the role it plays, and a two-context test for the path that crosses the fleet. The symptoms below are the ones the library's own build met.

The library reuses the Spring starter's wiring without Spring. The published agentspaces-spring-boot-autoconfigure jar carries no Spring classes (it compiles against provided-scope stubs), and its properties POJO, Authorizers, DirectiveGates, and build methods have no Spring type in their signatures, so the JVM loads them and ignores the Spring annotations it cannot resolve. A Micronaut @Factory binds the agentspaces subtree of the environment into that POJO (a Jackson conversion: kebab-case keys to setters, lists of maps to groups and spaces) and calls those methods, so the transport, TLS, group, space, key-ring, and capability wiring lives in one place for both frameworks. Every bean yields to an application-supplied one of the same type. The suite runs with no Spring on the classpath and pins that assumption, so a core release that puts a Spring type in a reused signature fails the library's build before it can reach an application.

Two platform notes. Micronaut 5 is on Jackson 3 and the core on Jackson 2.21.7; both coexist, with jackson-annotations 2.22 for Micronaut. Transport is TCP, TLS, and DTLS (the agentspaces.transport.dtls.* block works unchanged): agentspaces-transport-quic pins Netty 4.1 and Micronaut manages 4.2, so QUIC is not available under Micronaut.

agentspaces-langchain4j is a separate project, in its own repository at github.com/badmonkeyai/agentspaces-langchain4j, built on the published AgentSpaces artifacts. It gives a LangChain4j application on any JVM host, a command-line agent, an embedded service, a batch job, or a service on a framework this guide has no chapter for, the same fleet features Spring AI and Micronaut get, with no application framework on the classpath. Two artifacts: agentspaces-runtime, a peer in plain Java from the same agentspaces.* configuration the starter reads, with the framework-neutral tool catalogue; and agentspaces-langchain4j, the fleet on LangChain4j's extension points. The Micronaut bridge is wiring over them. Java 21; LangChain4j 1.20 and 1.22 are both verified.

A peer from one file. PropertiesLoader reads the agentspaces section of a YAML document (or a nested map, or flat dotted keys) into the starter's properties, and FleetRuntime builds the peer from them with the starter's own build methods, which carry no Spring type and run with no Spring present: identity, node, transports by security profile, groups, spaces, capabilities. It then ticks the node, starts each FleetParticipant, and refreshes cards on the card cadence; close() stops it all in reverse. bind(agent) binds the annotated objects, and context(group) gives the FleetContext a feature works in.

The facade. LangChain4jFleet builds only what its settings enable, so a one-line facade never widens the fleet's reach by accident. tools() is a LangChain4j ToolProvider over the live catalogue (fleet_<agent>_<InputType>, a JSON Schema from the input record, a call that writes the input into the agent's take space and awaits the result); DiscoveryTools.all() adds find_fleet_agents, list_fleet_assets, and fetch_fleet_data. listeners() carries the take-lease listener, which renews the in-flight @SpaceTake on every model round-trip, and the usage listener; pass them to a provider model's builder or wrap a model with listening(model). TakePropagation.wrap(...) and .executor(...) carry the take to another thread, so a renewal from a future or a parallel step still lands. Memory.on() puts chat memory in a replicated space, where a conversation a Spring AI or Micronaut worker started resumes. ModelClient.of("model") makes chatModel() and streamingChatModel() route calls through the space to the peers that serve them, and ModelServer.on() with modelServer(ModelCatalog.of("model", chatModel, streamingModel)) serves this peer's models, on the shared wire records (agentspaces-model-wire), so the three hosts serve each other. FleetRuntime.builder(...).embedder(LangChain4jFleet.embedder(embeddingModel, "name")) puts a real embedding model behind semantic discovery.

The service is the worker. An AiServices interface may carry the fleet annotations beside its LangChain4j ones: a @SpaceTake method that is also a @UserMessage template takes the entry, asks the model, and completes with the answer; a @Ballot method asks the model for the option. The binder reads the annotations through the proxy's interface, so runtime.bind(AiServices.create(Reviewer.class, model)) is the whole of it. Capability tools. .capabilityTools(FleetCapabilityTools.Settings.all()) adds six tools over the group's vote and aggregate capabilities, propose_vote, cast_ballot, read_tally, read_decision, contribute, and read_estimate, so a model can open or join a council and contribute to an epoch; the settings choose the families, the ballot lease, and the settle timeout, and a tool answers with a plain error when the capability is not provided. The Spring AI starter and the Micronaut bridge expose the same tools under their own settings.

The settings are records with defaults, built in code or bound from the tools and langchain4j sections of the same YAML with the Micronaut library's key names (ToolSettings.from(map), LangChain4jSettings.from(map)), so one file configures a peer under any host. The replaceable decisions are interfaces with defaults: FleetToolFilter, ToolNamingStrategy, ConversationIdResolver, ModelCatalog, ModelRequestRouter, StreamChunkingPolicy, StreamRestartPolicy, UsageSink.

agentspaces-model-wire is one small artifact with no dependencies that holds the entry types the model service, chat memory, and usage write, so that the three hosts serve each other. ModelRequest, ModelResponse, ModelChunk, ModelCancel, and ModelAttempt, with the Wire* parts they carry (messages, tool calls and tool responses, tool definitions, options, generations, usage, media), are written by FleetChatModel and ModelServer in agentspaces-springai and in agentspaces-langchain4j, which the Micronaut bridge wires. ConversationSnapshot is chat memory in a space, written by SpaceChatMemoryRepository (Spring AI) and SpaceChatMemoryStore (LangChain4j). ModelUsage is fleet-wide token usage on both. The space names an entry type by its class, so two peers read each other's model calls only when they use the same classes, and that is what the artifact is for: a Micronaut service with no key calls a model a Spring Boot peer serves, a conversation one framework's worker started resumes on the other's after a crash, and a mixed fleet's console sums usage as one. The package stays ai.badmonkey.agentspaces.springai.model.wire, where the records were born, because renaming it would change the schema name on the wire. WireGoldenTest pins the canonical CBOR bytes of every record in wire-golden.properties, shipped inside the jar, so each consumer's suite reads the same vectors. The three libraries bring it in transitively; add it directly only to read or write the records from code of your own.

One layer down from the annotations sits the interface they compile to: a typed, leased tuple space. Entries are plain records; every entry is signed by its writer and expires unless renewed; every peer holds a replica that keeps answering through partitions.

Before the verbs, the practical question: where does a Space come from? There are four sources, and they return the same object; a space is a space however you reached it.

take is destructive and exclusive under the space's conflict strategy; the taker holds a TAKE lease and must complete before it lapses, or the entry reappears. complete with a result validates and prepares the result record before committing the completion, so a task can never end up completed but resultless. Reads run against the local replica and never block on the network.

readAllIssued returns each match as an Issued<T>(T entry, AgentId issuer, Attestation attestation), where the issuer is authenticated by the entry record's signature and the attestation says how: PEER_ASSERTED when the hosting peer's key signed and vouched for the name, AGENT_ATTESTED when the agent's own peer-certified key signed (agent certificates). Any reader that makes a trust decision per entry (a vote tally, an audit reader, a result consumer) uses this rather than a field the entry declares about itself. SpaceEvent carries the same authenticated issuer.

readAllEntries returns each match as a Space.Entry<T> view over its record: value(), entryId(), the authenticated issuer() and its attestation(), the tags() the writer gave, the lease() in force, and the issued() stamp. The four-argument complete(taken, result, lease, tags) writes a tagged result atomically with the completion, which is how a Tagged return from a same-space take lands. A SpaceEvent carries the same view as details(), with tags() as a shortcut; the library's spaces fill it for WRITTEN and REAPPEARED, and for any other kind while they still hold the record, and an event built without the record carries null there and empty tags. Events fire at every replica: a notify subscription, and every annotation built on one, runs on each peer that holds the space and the agent, so what must happen once across the group is a take, a fleet-wide join or reduce, a vote (idempotent per proposal id), or an idempotent write.

notify events arrive at least once with entry deduplication available to you via the event's entry id; listeners must return promptly (the @SpaceNotify binder does both disciplines for you, which is why it is the recommended interface). Event kinds are WRITTEN, TAKEN, COMPLETED, EXPIRED (a write lease lapsed and the entry vanished) and REAPPEARED (a TAKE lease lapsed and the entry came back).

ReplicatedSpace adds a consistency hint on read and readAll. The default, ConsistencyHint.LOCAL, matches the replica as it stands; FRESH triggers exactly one anti-entropy pull toward one random member before matching locally, the cheap "make sure I am current" a late joiner or an operator console wants, without changing the local-first default for everyone else.

Matching is by type plus field predicates plus tag conditions. The matchers (ai.badmonkey.agentspaces.api.space.Matchers): eq, ne, gt, gte, lt, lte, in(values...), contains(fragment) for character sequences, isNull, notNull, and predicate(fn) as the escape hatch. Fields resolve through record components; on a non-record type the usual getX/isX accessors are read instead. An unknown field name throws at where(...) time, listing the fields the type does have.

whereTag(key, matcher) and hasTag(key) condition the entry record's tags. The matcher receives the value stored under the key, or null when the record carries no such tag, so eq, in, and contains fail on an absent key and isNull() selects untagged entries. Both spaces judge tag conditions after the type comparison and before they decode the payload, on every verb and on subscription delivery, so a keyless relay or a tag shard can select by tag without ever opening the record. Tag values stay visible metadata under content encryption; choose neutral tag values where that matters.

Lease.of(Duration) is the only constructor you need. A write returns an EntryHandle with renew(extension) and cancel(); cancellation is issuer-signed, so nobody else can withdraw your entry. Everything shares the one failure idiom: state you stop renewing goes away, and nothing needs a cleanup job.

The first two are strategies the space itself decides in its claim lattice, chosen when the space is built. The third is not a space setting at all; see the note below the table.

A space fixes one strategy for all its entries; use several spaces the way you would use several queues (tasks-bulk, tasks-auction, commits).

Taking through the ordered log

ORDERED takes go through the ordered-log capability, a coordinator registered on the group rather than a space setting. The ordered log covers the quorum, the registration, and what the log guarantees; @OrderedTake is the worker as one annotation.

A space advertises how it admits writers, independently of how the group admits members. Reads stay open to the group in every mode.

• GROUP (the default) admits every admitted member of the group.
• ALLOWLIST admits a fixed set of agents. A local caller outside the list gets a SpaceAdmissionException; an inbound record or claim from an unlisted agent is dropped and reported as misbehavior.
• CREDENTIAL admits whoever holds a live credential from the issuer. A credential is an ordinary leased SpaceCredential entry the issuer writes into the space itself, so nothing new appears on the wire: the issuer's node grants with space.grant(agent, scopes, validity) and revokes with space.revoke(agent), which is just a signed cancellation. A transition whose credential has not merged yet is dropped without a strike, because the evidence can legitimately arrive after the write it authorizes.
• AUTHORIZER hands the decision to the profile's Authorizer, scoped by the space name, which is how an identity provider's scopes (aspace:space-write:tasks) end up deciding.

Each transition is judged once as it arrives, after its signature verifies. A refused local call throws; a refused remote delta is dropped, and strikes its sender only when the rule says the refusal cannot be a late credential. The judged identity is the acting agent under ALLOWLIST and CREDENTIAL: when several agents of one peer share a replica through views (space.as(identity), agent certificates), each view is admitted or refused on its own agent's standing, so an ALLOWLIST or CREDENTIAL space can admit one agent of a peer and refuse its sibling, except that every agent of a CREDENTIAL space's issuer peer is always admitted. AUTHORIZER asks the authorizer about the acting agent's peer, so every agent of one peer gets the same answer. A record whose spaceId names another space is dropped before any of this, however validly signed.

The starter builds spaces from YAML; plain Java builds them directly. LocalSpace is the single-process form (same API, ideal for tests); ReplicatedSpace attaches to a joined group's runtime.

A space publishes its own advertisement the moment it is created, carrying its strategy, admission, replication mode, and schema hints, when built with .advertise(publisher). It is published once, at construction, and lapses from caches at its advertisementTtl (15 minutes by default) unless the host calls refreshAdvertisement() on a cadence. With founderLease set, the space turns read-only when the founders' lease lapses rather than silently accepting writes nobody will keep. maxLease fixes the longest lease the tombstone sweep allows for: a replica drops completed, withdrawn, and lapsed entries once their lease expired more than twice that long ago. It does not reject a longer lease, and without it the replica uses the longest lease it has observed, up to 24 hours.

Every type a space writes is named on the wire by its schema registry, <fully.qualified.Name>#v1 by default, and the schema hints and the cards of bound agents carry the same names. NamespaceSchemaRegistry.of(Map.of("org.example.claims", "https://example.org/claims#")) names the classes of the mapped packages by an IRI namespace (https://example.org/claims#Claim) and leaves every other type, the reserved SpaceCredential, vote, ordered-log, and JoinTicket records included, on the default rule. Share one instance: give it to each space builder (.schemaRegistry(schemas)) and to the binder or facade (spaces.schemaRegistry(schemas), or a SchemaRegistry bean under the starter), so the names the spaces write and the names the cards advertise agree. The facade's setting is the default for every group registered afterward; a group's own schemaRegistry(...) and the binder's schemas(...) refuse a registry once that group has bound its first agent. Remote actions resolve a card's names through the registry's classFor. For an IRI under a mapped namespace that no registration produced, classFor tries a class of the mapped package, loaded without initialization, so a peer needs the class on its classpath but no prior registration; an IRI outside the mapped namespaces never loads a class.

Below the space sits the layer that answers "who can do what": signed, TTL-leased advertisements in a per-group cache that gossip keeps fresh. Chapter 12 covers the services built over the same fabric. A peer has to find its group before it can read any card, so the chapter opens with that first contact (which option to pick, bootstrap, the locators, and beacons) and then turns to the cards.

Every option below answers the same question, "whom does a newcomer dial first", and none of them admits anyone: whatever a locator returns is dialed through the ordinary stranger path, so the choice is about where the answer lives and who maintains it. The chain asks every configured locator at once and ranks their answers in the order you listed them, so you can combine two or three (a seed list for the first day, DNS for the fleet, a beacon document for partners) and let the cheapest one answer first. Start with the simplest option that fits the network you actually have, and add the next one when the seed list goes stale.

A peer that has just started has an empty view of its group and has to dial one member before the fabric can do anything else. A seed is an address a newcomer dials first, and a locator is one way of finding one. BeaconLocator.locate(BeaconRequest) answers with a BeaconHint, or with BeaconHint.none() when the locator has nothing. The request carries what the node knows: the group's name, its GroupId when the group was founded locally or is joined by id, the scheme a bare host:port takes, and every scheme the node can dial. The hint carries endpoints in priority order and, optionally, the group id the locator believes, the signed founding, parameters such as wire hints, a lifetime (BeaconHint.DEFAULT_TTL, five minutes, when the source states none), and the evidence a trace shows.

A BootstrapChain is the locator a group is joined with: an ordered list of locators that it asks all at once, each under its own deadline (timeout, three seconds by default). A locator that throws or times out contributes nothing and stops nothing. The chain merges the hints in order, so the first locator's addresses rank highest, and it removes duplicates, keeps the first founding it finds, accepts a group id claim only from the locators named in acceptGroupIdFrom (url by default on the builder; a chain composed from agentspaces.bootstrap.* defaults to url and document), expands names to addresses last, and gives the merged hint the shortest lifetime among the contributors. firstWins() asks one locator at a time and stops at the first that returns addresses. A locator's appliesTo(groupName) lets one chain element serve a single group.

A custom locator is one small class, and the chain composes it with the others:

A group is joined in one of three forms, and PeerNode.joinGroup has an overload for each that takes a BeaconLocator in place of a seed list: GroupAdvertisement for a group started from a text, SignedGroupAdvertisement for a peer that holds the signed founding, and GroupId with a timeout to join by id. The node asks the locator when it joins and again while its view of the group is empty, never faster than PeerNode.Builder.locateInterval(min, max) allows and at least once per max (30 seconds and 10 minutes by default); a locator's own LocatePolicy overrides that for its group. lastBootstrapTrace(groupId) returns one BootstrapChain.Trace per locator asked (name, milliseconds, endpoint count, evidence, error), lastBeaconHint(groupId) returns the last merged hint, and leaveGroup(groupId) releases one group and keeps the others.

The agentspaces-bootstrap project (ai.badmonkey.agentspaces:agentspaces-bootstrap:0.4.0) supplies the locators an enterprise network can answer, over a small DnsResolver interface, and depends on nothing beyond the AgentSpaces libraries and Jackson. Each locator below asks one directory.

A beacon is a peer that newcomers can find and dial first: an ordinary member with a stable address, usually playing RENDEZVOUS, with no special role on the wire. The beacon document is the signed JSON it serves at BeaconDocument.WELL_KNOWN, /.well-known/agentspaces/beacon.json. (The multicast beacon is the opt-in LAN datagram, a core feature that appears in a chain as MulticastLocator.) BeaconDocument, in agentspaces-bootstrap, is a record of the format version, the issuer's PeerId and key, the issue time, a time to live, the groups, and an Ed25519 signature over the canonical bytes. Each group entry carries its name, id, seeds, wire hints, multicast group, and free parameters, and it carries the signed founding when the group has one. BeaconDocument.signed(identity, issuedAt, ttl, groups) signs, parse(bytes) reads (unknown fields are ignored), verifies() checks the signature, signer() names the issuer, and toBytes() returns the exact signed JSON. The writer refuses a parameter named like a content key, a credential, or a membership hint, so a document never carries a secret.

The agentspaces-beacon project (ai.badmonkey.agentspaces:agentspaces-beacon:0.4.0) is a ready-made beacon and the classes to build your own:

Cards, the ad cache, and the ads stream

Everything discoverable is a typed, signed card in a per-group cache that gossip keeps fresh; a card whose issuer stops republishing simply ages out. The advertisement families are peers, groups, spaces (with their admission and replication modes), capabilities, AgentCards (with their space bindings), AssetCards, and revocations. The cache verifies every signature, bounds its own occupancy, and evicts by TTL; a peer volunteering as RENDEZVOUS holds four times as much. Query structurally, or by meaning through the semantic-discovery capability (its reference embedder needs no model at all):

Most fleets never call this. Work finds its worker because the worker is sitting on the space taking that type; the routing is the entry's type, and nobody looks anything up. Discovery earns its keep when you need to know who is out there rather than get one task done: a console drawing the room, a planner deciding whether a capability exists before committing to a plan (the Embabel bridge builds on exactly this), an operator asking which peers can still do a thing, or a dispatcher that wants to fail loudly when nobody is listening instead of writing an entry into a space where it will sit until its lease lapses.

Three kinds of card matter to an application. An AgentCard is built by the binder from the identity annotation and the bound method signatures: the agent's name, description, and goals, one declared action per bound method (the consumed type, the produced types, the method's description), its space bindings, and under subordinate keys its public key and certificate; remote actions, fleet tools, and planners read the actions. An AssetCard is published by a connector (the connector SDK, or an AssetProvider bean under Micronaut): the asset's name, shape, freshness, and access, for data queries and for the fleet as a service registry. A CapabilityAdvertisement is a service's card, signed and leased like the others (chapter 12). All of them travel on the ads stream, the group's advertisement gossip, which the Python and TypeScript clients read as ads: rumor spreads a new card fast and anti-entropy brings a late joiner up to date. Every card is leased. The binder republishes agent cards on agentspaces.card-refresh-millis (five minutes by default), the capability runtime republishes advertisements on the same cadence through refreshTick(), a space's advertisement lapses at its advertisementTtl unless the host refreshes it, and a card whose issuer stops republishing ages out of every cache at its TTL. Revocations travel on their own gossip streams, revocations for peers and credential-revocations for agent credentials, and the cache purges the cards of a revoked peer and of a revoked agent.

The semantic-discovery capability (aspace:cap/semantic-discovery) is an embedding index over the group's advertisements behind a pluggable Embedder, and it answers "who holds something like this?", a question by meaning, where find takes a structural predicate. query(text, limit) searches the local cache; remoteQuery(text, limit, timeout) escalates over the capability pipes to the peers that advertise the capability and merges what they rank. SemanticClient is the typed client, from group.capability(SemanticClient.class) or a @CapabilityRef field, and the Spring AI, Micronaut, and LangChain4j libraries expose the same query to a model as find_fleet_agents and list_fleet_assets. It is request/response and needs no clock and no model set-up.

Matching is only as good as the embedder. The shipped HashingEmbedder needs no model and is a lexical approximation: good enough to find an asset by description, and short of understanding. The Python and TypeScript clients compute its vectors to the bit, so the two sides rank alike. SpringAiEmbedder (embedder.type: spring-ai, Spring AI) wraps any Spring AI EmbeddingModel, and the Micronaut and LangChain4j libraries do the same for a LangChain4j EmbeddingModel (embedder.type: langchain4j, or LangChain4jFleet.embedder(model, name)). Vectors are L2-normalized and cached by the text's content hash, so a card is embedded once, and the embedder's identity (spring-ai:<model>, langchain4j:<model>) is advertised on the capability, so a query goes only to peers that rank alike and a fleet never averages two models' notions of similarity.

Layer 4 answers "what does the fleet think" and "what must happen exactly once": services built over the same fabric as the space, each a CapabilityProvider on the peer's CapabilityRuntime, advertised with a signed, leased CapabilityAdvertisement, and reached from an agent through an annotation or a typed client. Six ship: vote, aggregate, the ordered log, gossip learning, key wrap, and semantic discovery, which chapter 11 covers with the cards it ranks. This chapter is the model every service follows, then one section per service, then how to serve one of your own.

How a capability is usedCapabilityRuntimeCapabilityAdvertisement

Layer 4 is the part of the system people most often wire wrongly, because a capability is not one thing but three, and a given peer may play any subset of the roles.

• The provider is the object that implements CapabilityProvider and serves the capability on this peer. Under the starter, the shipped ones are registered for you from agentspaces.capabilities.*. Otherwise it is a @ProvidesCapability bean.
• The consumer is whatever calls it. Typed clients resolve off the group context, as spaces.group("g").capability(VoteClient.class), and need no annotation at all. Most application code is only ever this.
• The clock is what advances a continuous capability's own protocol: a push-sum exchange, a gossip-learning offer, a Raft election step. You do not supply it. A capability runtime registers its protocol tick with the group's peer tick when it is constructed, so a provider is driven because it is registered, the same way a replicated space converges because constructing it joins that same clock. Nothing to schedule, nothing to remember.

That last point is the one worth internalising, because it is what makes the annotations enough on their own. One clock runs the whole stack: membership probing, gossip, space anti-entropy, and capability protocols all advance on the peer's tick, at agentspaces.tick-millis (250 ms by default). Set that one property and you set the beat of that clock. Push-sum gossip rounds keep their own pace: under a driven peer they run about once a second whatever the tick (PushSumAggregate.ROUND_PERIOD is one second), so the aggregate's convergence follows its rounds.

// There is no driver to write. Registering the capability is the whole of it:
// under the starter this already happened, and under plain Java it happens
// the moment the runtime exists.
AgentSpaces.GroupContext group = spaces.group("orders-fleet");
group.capabilities().isDrivenByPeerTick();     // true

// A test that wants each tick to be an exact, countable step takes the clock
// back and drives it by hand -- the same escape hatch a TestClock is for.
group.capabilities()
        .detachFromPeerTick()
        .cadence(Duration.ofMillis(300));      // what you will really tick at

// one tick, deterministically (at 300 ms the aggregate gossips on every third tick)
group.capabilities().protocolTick();

Convergence takes a few dozen rounds, so the round period is what turns "converges in O(log N) rounds" into a wall-clock number. Under a driven peer the runtime tells the aggregate the tick period, and the aggregate gossips once per PushSumAggregate.ROUND_PERIOD (one second), which is every fourth tick at the default 250 ms, so a fleet settles in tens of seconds. Driven by hand on a node that is not ticking, a runtime that declares no cadence gossips on every protocolTick(), and one that declares a cadence gossips about once per second of it. Vote and semantic discovery are request/response and need no clock at all, which they declare through requiresTick(); the runtime drives them anyway, because the default tick() is a no-op and costs nothing. Key wrap also reports requiresTick() false but overrides tick() for auto-rotation and for following a holder's epoch announcements, so it rides the peer tick too.

Two clocks exist at this layer and they are deliberately different rates. The protocol clock above runs at the peer tick. The advertisement clock, refreshTick(), republishes leased capability advertisements and runs with the card refresh, on the order of minutes. A method named for one will not do the other.

The six capability services

• Vote (aspace:cap/vote): proposals and ballots as signed entries; the decision closes at quorum and any member recomputes the tally from the space. QUORUM mode is the canonical, auditable form, counting one ballot per eligible voter; the electorate is any authenticated issuer by default (the starter's choice too), narrowed to fresh AgentCards with VoteCapability.freshAgentCards(discovery) and by the authorizer; MAJORITY_GOSSIP is a cheap approximate temperature check by push-sum. The voter is derived from the entry's authenticated issuer, never from a field the ballot declares.
• Aggregate (aspace:cap/aggregate): push-sum gossip; every member converges on a fleet-wide figure with no collector. Six operators (SUM, AVG, COUNT, MIN, MAX, QUANTILE) over a supplied value or over a template's matching entries. aggregate.start("backlog", localValue), then estimate("backlog").
• Ordered log (aspace:cap/ordered-log): a small Raft among volunteers, with the leader lease published as an advertisement; backs ordered takes and any workflow needing a total order. Off by default, since it needs a fixed member set.
• Gossip learning (aspace:cap/gossip-learn): mergeable models exchanged pairwise converge to the fleet mean with no parameter server; content-addressed, with a mass-conserving offer-and-accept exchange. Suits learned bid policies. Off by default; enabling it wires the default weight-averaging learner.
• Semantic discovery (aspace:cap/semantic-discovery, chapter 11): an embedding index over the group's advertisements behind a pluggable Embedder. query(text, limit) searches locally, remoteQuery(text, limit, timeout) escalates; the shipped hashing embedder needs no model at all, and agentspaces-springai swaps in any Spring AI EmbeddingModel (semantic discovery).
• Key wrap (aspace:cap/key-wrap): distributes group content keys sealed per member, or per agent under requestAs (X25519 + HKDF + AES-256-GCM), so encrypted spaces onboard members without any shared secret in transit (security). A holder serves every epoch of its key ring: request returns the epoch-0 key, and the rotated epochs come through fetch, requestAs, or follow.

Typed capability clients

Consumers do not speak the capability's entries directly. A client type resolves off the group context, and the client finds the providers, speaks the protocol, and hands back ordinary values:

Register your own with spaces.clientFactory(new MyClient.Factory()), and serve your own capability with a @ProvidesCapability bean (custom capabilities).

An agent POJO has @SpaceRef for spaces; the equivalent for capabilities is @CapabilityRef, and for what agents do with a capability there are annotations of the same shape as @SpaceNotify: @Ballot and @OnDecision for the vote, @OrderedTake for the ordered log, a Contribution return for the aggregate (chapter 3 and chapter 4). Constructor injection of the capability object still works and is still fine when the caller has it in hand; the annotations are the idiomatic form because the discipline they encode (one ballot per proposal, one reaction per closed vote, the resubmit after an election) is what every hand-written consumer got wrong at least once.

Under Spring the typed clients resolve from the facade, as spaces.group("trip").capability(VoteClient.class), or arrive by @CapabilityRef; SemanticClient joins VoteClient and AggregateClient. Providing a capability through the facade (group.provide(vote)) is what makes the vote annotations on its space bindable; group.ordered(space, coordinator) does the same for @OrderedTake.

The vote capability (aspace:cap/vote) runs over a space. A Proposal is a signed entry carrying the proposal id, the question, the options, the quorum, and a lease; each Ballot is a signed entry naming the proposal and the option; and the decision closes when the tally meets the quorum. Any member recomputes the tally from the space, so a decision is auditable afterwards from the entries alone. Two modes: QUORUM is the canonical form and counts one ballot per eligible voter; MAJORITY_GOSSIP is a cheap approximate temperature check by push-sum, and the Python and TypeScript clients carry it too (cast_preference and leader in vote.py, castPreference and leader in vote.ts, over their push-sum aggregate). The electorate is any authenticated issuer by default (the starter's choice too), narrowed to fresh AgentCards with VoteCapability.freshAgentCards(discovery) and by the authorizer, and the voter is derived from the ballot's authenticated issuer, never from a field the ballot declares.

VoteClient is the typed client: propose(id, question, options, quorum, lease), or propose(Motion), which is idempotent per proposal id; castBallot(id, option, lease); tally(id); and decision(id), which answers once the quorum is met with the winner, the tally, and the granularity that closed it. The capability's own onDecision(proposals, listener, lease) returns a leased subscription. Inside an agent the same three steps are annotations: @Propose opens, @Ballot casts, and @OnDecision reacts once when the vote closes. Register the capability with group.provide(vote), which also advertises it, or group.vote(space, vote), which does not. Under the starter agentspaces.capabilities.vote builds one over votes-space, which must be listed under groups[].spaces for agents to bind to it.

Push-sum answers questions no single peer can answer: what is the fleet's average backlog, how many workers are live, what is the p95 of a number every peer holds a piece of. There is no collector and no metrics server; every member ends up holding the same estimate.

Two rules keep the estimate honest, both learned on the wire. A share goes only to a member that takes part: participants(rule) restricts the push, PushSumAggregate.advertisedIn(discovery) admits a member whose capability advertisement is live, and the capability runtime applies that rule to every aggregate it registers, so a bystander peer (a console, a client that has not started the capability) never swallows mass it would not mix back. And a Settle rule counts a step only when the step is a gossip round this node took part in after it first heard the epoch, or when the epoch has gone quiet, which completes the streak: halving leaves a node's own ratio untouched, so a node nobody pushes to is stable by construction and says nothing about the fleet; a node with no participant at all judges its own ticks, its value being the only estimate there is. Rounds run about once a second under a driven peer whatever the 250 ms tick, so a streak of forty steps lasts about forty seconds. The Python and TypeScript aggregates advertise and filter the same way.

That pair, sense with aggregate and decide with vote, is the whole of examples/example-05-quorum, and it is the canonical shape for autonomic behavior: the fleet notices its own condition and commits to a response that every member can audit afterwards from the vote space. When the supervisor should act once the figure has stopped moving instead of polling estimate, AggregateClient.awaitSettled(epoch, Settle.after(ticks, tolerance), timeout) blocks until the rule holds, and @OnEstimate reacts to the same rule as an annotation.

The ordered log (aspace:cap/ordered-log) is a small Raft among a fixed set of volunteers, with the leader lease published as an advertisement, so role=leader is discoverable. It backs the ORDERED claim path: signed take claims are submitted to the log as commands, its commit order arbitrates identically on every member, and the first valid committed claim per entry generation takes the entry, exactly once, in one total order. ORDERED is a coordinator registered on the group, and the space itself keeps the default strategy; OrderedTakes.over(...) wraps the log and the space as the coordinator that takes through it; reads, writes, and completions still go through the space as usual, and only take moves. A peer hosts one ordered log per group, so an ORDERED join or reduce lives on the space that has the coordinator. It is off by default, because it needs a member set the starter cannot guess; the starter's ordered-log switch refuses automatic assembly for that reason.

Exactly-once is one annotation now: @OrderedTake is @SpaceTake with the take routed through the space's ordered-log coordinator, so the loop, the resubmit after a leader election, and the complete-or-lapse are the binder's. What stays yours is the quorum: a fixed member set, one coordinator per space, built with OrderedTakes.over(...) and registered on the group. The exactly-once desk and the Party Bus booking clerks are the worked examples.

Reach for this only where a duplicate is genuinely unacceptable and you would otherwise reach for a distributed lock: charging a card, filing a return, allocating a serial number, sending a message a customer will see once. Everywhere else LEASE_RACE is cheaper and more available, and the duplicate work it can produce across a partition is the price of continuing to run at all.

This is the least obvious capability, so here it is end to end (and as a runnable fleet: examples/example-14-gossip-learning, three peers whose local weight vectors converge on the fleet mean on the peer tick alone, with a test that asserts it). The idea: every peer holds a parameter vector, peers pair off at random and average their vectors, and the fleet converges on the mean without a parameter server and without any raw data leaving any peer. Add a local update step that runs after each merge and you have federated training: train on what you have, average with a neighbour, repeat.

Two things have to be true for it to work, and both are your job: every participant registers the same model id with the same vector length, and the local update (if any) is supplied at construction. The third, something driving the exchange, is the runtime's job, and it is done for you as soon as the provider is registered.

Use it for anything where peers hold private data and want a shared model: learned bid policies (the fleet converges on what work actually costs), drift detectors, shared bandit statistics, federated fine-tuning signals. It is the natural partner of @BidFunction: a bid function is a plain method over numbers, and this is how those numbers learn.

The mechanism is randomized pairwise averaging, which contracts the spread geometrically, so a fleet lands within tolerance of the mean in O(log N) rounds. Each completed pairwise average preserves the fleet mean, so under pure averaging the answer does not drift. The caveats: a lost ACCEPT can move mass one-sidedly, a local update changes the mean by design, and a departing peer takes its share with it.

Key wrap (aspace:cap/key-wrap) hands a member the group content key without ever putting it on the wire in the clear: the holder serves the key under the profile's authorizer, and a joining member asks for it sealed to its own X25519 key (X25519, HKDF, AES-256-GCM). The holder serves every epoch of its key ring: request returns the epoch-0 key alone, fetch(holder, epochs, timeout) brings rotated epochs sealed to the peer, requestAs brings them sealed to an agent, and follow(ring, discovery) fetches on each tick whatever epoch the ring lacks. It is request/response and needs no driver, though it rides the peer tick for auto-rotation and for following a holder's epoch announcements. Under the starter, agentspaces.groups[].content-key is both what the capability serves and what seals every payload; content encryption and rotation covers the epochs, the key-rotator grant, and what rotation can and cannot do.

A capability of your own is a CapabilityProvider: capabilityType() names it, describe(group) builds its signed CapabilityAdvertisement, start() and tick() are interface defaults you override when the protocol needs a driver, and requiresTick() says whether it does. Mark the class @ProvidesCapability and register it, as a Spring bean, through spaces.bind(bean), or with group.provide(provider); the group's CapabilityRuntime then starts it, publishes its advertisement, refreshes it on every card refresh, and drives its tick() on the peer tick. Speak to peers over group.pipes(), the PIPE_DATA frames addressed to one member that the shipped services use, or through a space. Consumers reach it through a client type registered with spaces.clientFactory(new MyClient.Factory()) and resolved like any other, by group.capability(MyClient.class) or a @CapabilityRef field. The gossip learner above is the worked example of a provider with a tick; the echo capability under @ProvidesCapability is the smallest one.

The floor of the stack. Most applications configure it through the starter and never touch it; this is the API when you wire by hand or embed without Spring.

• Identity. An Ed25519 keypair; the PeerId is the hash of the public key, so identity survives every address and transport change, and every frame, card, entry, and state transition the peer emits is signed with it.
• Groups. A group's id comes from a founding text or from a signed founding. With a text, every member derives the same id from the same string and no signed document exists; joinGroup(GroupAdvertisement, ...) joins it. With a signed founding, the GroupId is the hash of a founder-signed document, and a newcomer who knows only the id can ask a seed for the document and verify the answer against the id before joining: joinGroup(GroupId, ...) does that, and joinGroup(SignedGroupAdvertisement, ...) serves a peer that already holds the document. A group started from a text has no signed founding to serve, so it cannot be joined by id (the attempt times out); only a group with a signed founding can. That is the founding, join, and founding-document trio of the starter, and discovery covers how a peer finds the seeds to ask.
• Membership. SWIM-style probing with leased membership: a silent member drops from the view on its own. Groups admit by policy: OPEN, INVITE (founder-signed credential presented at join), or POLICY (your validator SPI). Two gossip channels carry state, rumor for speed and anti-entropy for completeness, the latter paced by the group's own gossip period.
• Topology. Any member may volunteer as RENDEZVOUS (a bigger discovery cache newcomers ask first) or RELAY (forwards signed frames verbatim for NAT-restricted peers). Correctness never depends on either. On a LAN, the opt-in multicast beacon replaces seeds entirely.
• Transports. An in-JVM loopback for tests, TCP, TLS over TCP (the JDK's default protocol set; this binding does not pin a version), QUIC (RFC 9000), DTLS 1.2 (RFC 6347), WebSocket (RFC 6455, as ws and wss), and the HTTP exchange (http and https) ship; a peer advertises (transport, addr, priority) endpoints and dialers try them in ascending priority, skipping schemes no configured transport serves. Peer identity stays with the signed envelopes on every transport.
• QUIC. agentspaces-transport-quic carries the fabric's frames over QUIC (RFC 9000) through quiche and Netty's incubator codec, plugged in through the same Transport SPI as TCP: node.listen(new QuicTransport(identity), address). Built with the identity, it presents an ephemeral channel certificate the peer identity endorses, so the attested mode below works over it; the no-argument new QuicTransport() encrypts and attests nobody. The starter builds the identity form when agentspaces.transport.quic.enabled is true and the module is on the classpath (startup refuses an enabled block without the module); it is not available under Micronaut, which manages Netty 4.2 while the transport pins 4.1.
• DTLS. agentspaces-transport-dtls carries the frames over DTLS 1.2 on UDP, on BouncyCastle's DTLS, pure Java with no native library. A small recovery sublayer makes each association reliable and ordered, so nothing above the transport changes, and Connection ID (RFC 9146) keeps an association alive when a peer's address changes behind a NAT. It presents the same channel certificates as TLS and QUIC and attests in the same modes; DtlsTransport.unattested() (property attestation: none) encrypts for fleets that use no attestation. Turn it on with agentspaces.transport.dtls.enabled and a bind; a fleet that requires attestation may run on DTLS alone. Choose it where QUIC is unavailable (no quiche build for the platform, a validated-crypto policy) or blocked, and on lossy UDP-only links. Two things to know: DTLS 1.2 sends certificates in clear, so a passive observer learns which PeerIDs talk (use QUIC or TLS where that matters), and there is no congestion control beyond a fixed window. The bare udp binding in the same module runs the sublayer over plaintext UDP for closed test ranges and links already encrypted underneath; it registers only under dev-local or allow-plaintext.
• WebSocket and the HTTP exchange. agentspaces-transport-http (design: srad/agentspaces-js.md) is how a browser, a Node process, a Worker, or anything behind HTTP infrastructure becomes a member. ws carries one binary message per frame under the subprotocol aspace.1; wss is the same inside TLS 1.3 with the tls binding's identity modes, and it admits a dialer with no certificate (a browser) as unattested. http and https are the exchange for intermediaries that break WebSocket: POST /open, batched frames up under Aspace-Seq, a 25 s long-poll down under Aspace-Ack. One Netty port serves both the upgrade and the exchange. Browsers are admitted only from the listener's allowed-origins (empty refuses every browser; * is for demonstrations). On an unattested link both ends in session mode run SPEC §5.6 session attestation inside it, so frames travel tagged rather than signed after the hello; ws, http, and https never attest, so they register under any profile as tcp does and startup refuses them under require-attestation; only wss attests. The TypeScript client dials all four with the runtime's own WebSocket and fetch; Python keeps tcp and skips them.
• WebRTC. agentspaces-transport-webrtc and @agentspaces/webrtc carry the frames over a WebRTC data channel, so two browsers behind one seed, or a browser and a Java peer, talk directly and leave the seed out of the data path. Signalling travels through the fleet's own pipes (aspace:cap/rtc-signal): directly when the target is connected, inside a RELAY_FRAME through a relay member otherwise, which is the one relayed frame a node under require-attestation admits. Each side signs the DTLS fingerprint of a certificate it generated for the connection into its signal, so the channel attests the remote PeerID. The Java engine is libdatachannel (a native per platform); the TypeScript side is the browser's RTCPeerConnection or node-datachannel on Node. No ICE server is configured by default: only host and mDNS candidates gather until agentspaces.transport.webrtc.ice-servers names STUN or TURN. Every bound (offers per peer per minute, candidates per session, bytes per signal, the 15 s dial) is a property; nothing caps connections. A node never dials a webrtc endpoint from inside a send: frames to a member it cannot reach take the relay, and once more than agentspaces.transport.webrtc.offload.frames-per-minute (30) of them crossed a relay to or from that member in a sliding minute, the node dials the endpoint from its tick and sends directly from then on, so the relay carries none of the pair's frames; a dial that cannot complete falls back to the relay at the dial bound without losing a frame and is retried no sooner than retry-after (5 min). The TypeScript core counts the same way (peer.onRelayed) and @agentspaces/webrtc decides on install.
• Channel authentication. The envelope signature authenticates one hop, so when the transport has already authenticated the channel it is repeated work at roughly a thousand times the cost of serializing the frame. TLS, QUIC, and DTLS present a channel certificate the peer identity endorses, and a node that announces itself willing accepts unsigned frames from the peer that channel attests, the attested mode of the starter. Signed and attested nodes mix freely; forcing signed mode is the only downgrade an attacker can cause, and it costs nothing but speed.
• Enterprise CA mode. Point the TLS, QUIC, or DTLS binding at a trust store and peers attest only when their chain validates to your anchors, with revocation checked against cached CRLs or fetched live. Under require-attestation every inbound frame must arrive on a channel attested for its sender, which is what makes the CA's revocation an authoritative fleet-wide eject rather than advice.
• Revocation and rotation. A signed RevocationAdvertisement gossips like any other advertisement, with anti-entropy so late joiners converge, and a revoked identity is refused at dispatch ahead of every other check, evicted from membership, and its connection closed. Because a self-certifying identity cannot rotate its key in place, rotation is a revocation that names a successor; the successor joins and is authorized like any new peer. GroupRuntime.revoke(...) and rotate(...) issue, and the founder-rooted RevocationValidator is the seam an enterprise deployment replaces. Agents, agent keys, channel leaves, and join credentials are revocable too; see revocation.
• One clock. startTicking(period) is the whole scheduler. Membership probing, rumour and anti-entropy gossip, replicated-space convergence, and capability protocols all advance on that one tick, because each layer registers with it rather than bringing a timer: a space through gossip().reconcile(...), a capability runtime through GroupRuntime.onTick(...), which is also where you hang periodic work of your own. Work registered there runs on the tick thread, so it must be quick; work that throws is logged and cannot stop the tick or its siblings.
• Containment. Per-issuer rate limits and bounded strike counters, fed only by witnessed violations on fresh authenticated frames, quarantine a misbehaving peer. Replayed frames and unadmitted peers deliberately never strike, which is what keeps quarantine unweaponizable.

What an HTTP intermediary does to a link (ISSUE-Websocket §9.6). The rule: attestation survives anything that forwards TLS bytes unchanged and dies at anything that terminates TLS; a require-attestation fleet uses passthrough or stays off HTTP.

Agent keys and certificates, revocation of everything certified, and content encryption have their own chapter: Security.

Everything in AgentSpaces is signed, and most of what you decide about security is who holds which key, for how long, and who may take it away. This chapter covers peers and agents, the security levels from a laptop to a regulated fleet, where keys live, how agents get certificates, revoking anything that was certified, and content encryption. Each section names the cost of its guarantee. The normative text is SPEC §4.2, §5.6, §11, and §11a; TECH-SPEC §5 and §7 carry the wire detail.

• Peers are keys. A PeerId is the hash of an Ed25519 public key, so a peer is whoever holds that private key. No registry, no CA required. Every advertisement, record, claim, and state transition a peer emits carries its signature, and so does every frame, except on a link whose peer is attested (frames ride bare there) and under dev-local (a MAC under the session key after one signed hello).
• Agents are names on a peer. An AgentId is <peerId>/<localName>. By default the peer signs for its agents, and a reader trusts the peer's labelling: PEER_ASSERTED. Give an agent a key of its own, certified by its peer, and the agent signs its own records, claims, and transitions: AGENT_ATTESTED. Readers see which through Space.Issued.attestation().
• What each layer proves. A record signature proves who wrote an entry. A claim signature proves who took it. A state signature proves who renewed, cancelled, or completed it, so a forged completion cannot delete work. Channel attestation proves which peer is on the other end of a TLS or QUIC link. Content encryption decides who can read a payload.
• What none of them decide. A signature proves who acted, never that they were allowed to. Eligibility is the Authorizer's question (profiles and authorization), and admission is each space's (space admission).
• An attested agent acts only as itself. Once an agent signs with its own key, its peer can no longer act in its name: every renewal, cancellation, and completion of that agent's work must carry the agent's signature, or receivers refuse it.

Each rung adds a guarantee and a cost. Pick the lowest rung that covers your threats; mixing nodes of adjacent rungs in one fleet is supported, and a mixed fleet degrades to the lower rung's guarantee for traffic between them, except under require-attestation, which refuses nodes of lower rungs outright.