This guide walks one business workflow, an insurance claims flow, from the first claim to the last ledger line, and shows how AgentSpaces expresses each step a workflow author already has a word for: sequence, map, fan-out, fork, publish and subscribe, join, gather, reduce, compose, filter, route, branch, decide, exactly once, aggregate, deadline, loop, compensation, the human step, the model step, and the planner. The developer guide explains each piece of AgentSpaces on its own; this guide shows the pieces working together on one example, and at every step it names the options you have and what each one costs.

Every snippet comes from code that the repository checks in and runs under the build gate, and the first line of every snippet names the file and the method it comes from. The main example is example 18, the claims flow, in the AgentSpaces repository under examples/example-18-agentic-workflow. Where the claims flow does not use an option, the guide shows that option from another checked-in example or test, and the snippet names that source instead.

The guide uses two vocabularies, and keeps them apart. The first is the claims flow's own: its records, which are plain Java records such as Claim and PricedClaim, and its agents, which are plain Java classes such as Registrar and Payer. The second is the AgentSpaces API: spaces, entries, leases, annotations, and the runtime that runs them. Chapter 0 defines both before any snippet uses them.

The developer guide's quick start has two classes, and they already form a two-stage workflow. The Fulfiller class takes an Order record and returns a Shipment record. The Auditor class reacts to every Shipment and returns a Receipt. Neither class names the other. The method signatures are the workflow: the parameter type says which record the method waits for, the return type says which record the method produces, and the space carries one record to the next method.

Every pattern in this guide ends the same way: a method returns a record, and the AgentSpaces runtime writes that record into a space as an entry. A stage never calls the next stage. It writes what it knows, and whichever stage consumes that record type picks the entry up, on whichever peer hosts that stage. That one rule is what lets the patterns compose without a workflow engine.

Example 18 is a claims department. A claimant files a claim against a policy. The department registers the claim, screens it for fraud, checks the policy is in force, estimates the damage, assembles those findings into one assessment, prices the assessment, asks three repair shops for quotes, puts the priced claim to a panel, pays the claims the panel approves, keeps a ledger of every outcome, and watches the fleet's average reserve. Three peers run it, and five spaces carry it. The first figure shows the flow as the records move between the spaces; the second shows the records themselves with their fields; the table after them lists every record the flow writes, and each chapter repeats the rows it uses.

These are the AgentSpaces terms the chapters use. The figure shows what they look like in example 18, and the table defines each one. Each chapter repeats a definition the first time it needs the term, so you can read the chapters out of order.

Where we are in the claims flow

Before any stage runs, example 18 decides what its records look like and which space each one lives in. This chapter is that decision. A workflow engine would hold a process definition and a history; the claims flow holds neither. The records that travel between its stages are the whole of its protocol, so the shape of those records is the design.

The records in play

What the design must do

Three rules shape every record in the flow, and every later chapter leans on them.

Every record carries the correlation id. The field claimId appears in every record above. A join keys on it to collect the findings of one claim, a fold groups by it, a compensating stage finds what to undo by it, and a test reads a case's outcome by it. A record without the case id is a record no later stage can connect to anything.

A reference is an id, never a nested object. Claim.policyId names the policy; it does not embed it. A stage that needs the policy reads the policy's own entry with a template on that id. The policy then lives in its own space, under its own lease, and a change to it does not invalidate every claim that mentions it.

One space per lane. The peer builds each space once, choosing its conflict strategy and its retention, and every stage inherits those choices by naming the space. In the snippet below, the assessment space uses the AUCTION strategy because the adjusters in chapter 6 bid for assessments; the other four use the default lease race.

Every stage in the flow runs under one of two contracts, and choosing between them is the first decision in every later chapter. The Registrar is a take: it claims a Claim entry under a lease, does its work, and completes the entry. If the registrar's method throws, or its peer dies, the lease lapses, the space offers the Claim entry again, and another registrar retries it. The FraudScreen is a reaction: every peer that hosts a FraudScreen delivers each RegisteredClaim entry to its copy of the method. If that method throws, the binder logs the exception and drops that delivery, and nothing retries it.

Where we are in the claims flow

Stage 1. A Claim entry sits in the intake space. The department must register it, exactly once, and the registration must survive the registrar crashing halfway through. Example 18 runs two registrars, on peer-a and peer-b, and its test makes the first registration any registrar attempts throw, on purpose.

The records in play

What the stage must do

Take one Claim, check the vocabulary's constraints, and write either a RegisteredClaim or a Rejected. Consume the Claim and write the outcome together, so a crash cannot leave a claim consumed with no outcome, or an outcome written with the claim still waiting.

How AgentSpaces does it

The annotation @SpaceTake tells the binder that register is a take. The binder reads the parameter type, Claim, and runs a loop on a virtual thread: it asks the intake space for one Claim entry nobody else holds, claims it under a three-second take lease, calls register with the record, and when the method returns, completes the Claim entry and writes the returned record into the same space under a one-hour write lease, in one commit. The hook is the example's own test device, a callback the test uses to throw once; it is not part of AgentSpaces. When the hook throws, register throws, the binder does not complete the entry, the three-second lease lapses, and the other registrar's loop takes the same Claim and registers it. The test counts one crash and five registrations.

The options

Option 1: write the result into the take space. Leave resultSpace empty, as the Registrar does. The binder then completes the Claim and writes the Registration in one commit, and the next stage takes or reacts from the same space. This is the default, and the guide prefers it wherever the next stage can live in the same lane.

Option 2: write the result into another space. Name a resultSpace. The binder completes the input bare and then writes the result as a second step. Choose it when the result belongs to a space with a different strategy or retention, and accept that a crash between the two steps loses the result; carry the input's id in the result so the next stage can spot the gap. The Party Bus watcher below does this because its reports live in a signals space with their own retention.

Option 3: renew the lease from inside the method. Ask for a short lease and call TakeContext.current().renew() while the work runs. Choose it when one call can take a hundred times longer than another, such as a model call, so that an honest slow call keeps its entry while a dead worker's entry still returns quickly. The test recorder below shows the call.

Option 4: make the effect safe to repeat and keep the lease short. This is your code, not an attribute. The registrar registers the same claim twice harmlessly because the Assembler keys on the claim id, so a three-second lease is safe. AgentSpaces cannot supply this discipline; the method must.

The options at a glance

In the Party Bus, a NewsWatcher takes a NewsSweep request from the research space and writes its SignalReport into the signals space, where a different retention applies. The binder completes the request first and then writes the report.

TakeContext.current() returns the take the current method runs under. Calling renew() extends its lease by the annotation's lease again. If the renewal throws, the lease already lapsed and another worker may hold the entry, so the method should stop.

Where we are in the claims flow

Stage 2 and stage 3a. A RegisteredClaim entry exists. Three specialists must each examine it and write their own finding: the FraudScreen a FraudFinding, the CoverageCheck a CoverageFinding, the DamageEstimator a damage finding. Later, once an assessment exists, the QuoteDesk must ask three repair shops for quotes, which means writing one request and three tasks from one assessment.

The records in play

In a stream library, map applies one function to every element. Here the elements are the entries of one record type in one space, and the function is a method you annotate. The CoverageCheck maps every RegisteredClaim to a CoverageFinding:

@SpaceNotify tells the binder that check is a reaction. The binder subscribes to the intake space for RegisteredClaim entries, and each time the peer's replica receives one, the binder calls check with the record on a virtual thread and writes the returned CoverageFinding into the same space under a one-hour lease. The binder also renews the subscription's lease for as long as the agent stays bound, and it delivers each entry to this agent once, even when gossip delivers the same entry twice.

Fan-out is the map above written three times for three record types. The FraudScreen, the CoverageCheck, and the DamageEstimator each declare RegisteredClaim as their parameter, so each of them reacts to every registered claim, and each returns its own finding. None of the three knows the other two exist, and the Registrar that writes the RegisteredClaim knows none of them. Example 18 binds the FraudScreen on peer-a, the CoverageCheck on peer-b, and the DamageEstimator on peer-c, and the replicas carry every registered claim to all three.

That is also publish and subscribe. The Registrar is the publisher, the RegisteredClaim record type is the topic, each specialist is a subscriber, and the space is the broker that is not there. The table at the end of this chapter maps every broker term onto this example.

The QuoteDesk reacts to one ClaimAssessment and must write four records: a QuoteRequest that tells the gatherer to expect three quotes, and three QuoteTasks, one per shop. A method has one return value, so it returns an Entries, which is the AgentSpaces class for "several entries from one return":

Four things happen when ask returns, and each one deserves its own sentence.

The binder writes each element on its own. The binder walks the four elements in order and writes each one into the intake space as a separate entry under the one-hour result lease, exactly as it would have written a single returned record. The three shop classes in chapter 6 then take the three QuoteTask entries one at a time, and the QuoteGatherer in chapter 4 reads the QuoteRequest.

An element may be any return kind the binder knows. Because the binder dispatches each element as if the method had returned it alone, an element may be a plain record, a Tagged record (a record plus the tags to write on its entry, chapter 12), a Motion (an instruction to open a vote, chapter 7), or a Contribution (a value for a fleet-wide aggregate, chapter 9). The binder refuses an Entries inside an Entries.

From a take, the binder completes the input before it writes the first element. If the forking method were a @SpaceTake, the binder would complete the taken entry once with no result, then write the elements. A take's one-commit guarantee covers one result, and a fork has several. The QuoteDesk is a reaction, so the binder completes nothing and only writes.

A fork is not atomic, so the flow tolerates a partial one. A peer can die after writing the second element and before the third, and no engine rolls that back. Two habits make a partial or repeated fork harmless. First, every forked record carries the case id: each QuoteTask and the QuoteRequest carry claimId. Second, the stage downstream discards duplicates by that id: the QuoteGatherer fires once per claimId, so a repeated fork yields one estimate.

The annotation tells the card what the fork produces. The binder publishes a card for every agent, listing the record types each method consumes and produces, by reading the method signature. A signature that says Entries names no record type, so the method lists its element types in produces. That changes no behaviour; it keeps the card honest.

A reaction that decides it has nothing to write returns null, and the binder writes nothing. The Escalator in chapter 10 does this when the panel has already decided. Use a null return when the decision needs a lookup; when the decision is a field value, use the where filter of chapter 6 instead, because the filter keeps the method from running at all.

The options

Option 1: map with a take. Annotate the method @SpaceTake and return the next record. One worker handles each entry, and a crash retries it. The Registrar in chapter 2 is this shape. Choose it when the output must exist once or the work can fail.

Option 2: map with a reaction. Annotate the method @SpaceNotify and return the next record, as the CoverageCheck does. Every peer that hosts the agent runs it. Choose it when you bind the agent once, or when a repeated output is harmless.

Option 3: fork through the return value. Return Entries.of(...) and list the element types in produces, as the QuoteDesk does. Choose it when one record starts several tasks and you know the elements when the method returns; the card then lists them.

Option 4: fork through explicit writes. Declare a @SpaceRef field, which asks the binder to inject a Space handle at bind time, and call space.write(record, lease) as many times as you need. The Party Bus Dispatcher below does this. Choose it when the elements go to several spaces or the method must read between writes; the card cannot list what you write by hand.

Option 5: map to nothing. Return null, and the binder writes nothing. The PetClinic Vet below and the Escalator of chapter 10 do this. Choose it when the decision needs a lookup; when the decision is a field value, prefer the where filter of chapter 6, which keeps the method from running.

Option 6: map over a backlog. A subscription only delivers entries that arrive after it starts, so a reaction bound late misses the backlog. A take sees every entry still in the space, so prefer a take for a backlog; when you must sweep from a reaction, call space.readAll(template, limit) through a @SpaceRef field.

The options at a glance

The Party Bus Dispatcher reacts to a TravelBrief, reads the Travelers record for the trip first, and then writes nine research requests by hand through @SpaceRef fields. @SpaceRef asks the binder to inject a Space handle into the field at bind time. This shape lets the method read between writes and write to several spaces; it costs the card, which cannot see the nine types.

In the PetClinic, both vets react to every Appointment, and each returns null for an appointment that names the other vet. A where = "vet=dr-song" filter would do the same without calling the method, but it would need one class per vet, since an annotation value is a constant.

A subscriber, in this guide, is an agent with a @SpaceNotify method. That method is the reaction; the type of its parameter is the cue type, the record it listens for; and the record it returns goes into a space under the result lease named on the annotation. Each peer holds its own replica of every space, and the peer that hosts the subscriber delivers matching entries to it from that replica. A broker would enforce the four rules below for you. Here they are yours, and each one follows from how the replica delivers.

1. A reaction runs on every peer that hosts the subscriber. If you bind the FraudScreen on three peers, each peer delivers each RegisteredClaim to its own copy, so three fraud findings appear per claim. That is what makes fan-out cheap, and it is a problem only when the reaction's effect must happen once. Three remedies, in order of preference: bind the subscriber on one peer, as example 18 binds the FraudScreen on peer-a alone; return a Motion, which opens a vote once per proposal id however many peers return it; or write a record that carries the case id and let the next stage discard duplicates by it, as the Assembler does. A reaction whose repeated effect is harmless needs none of these.

2. The binder drops a reaction that throws, and nothing retries it. A take holds a lease, so when its method throws the lease lapses and the entry comes back for another worker. A reaction holds nothing: the replica delivered the entry, nobody claimed it. When the method throws, the binder logs the exception and never delivers that entry to this subscriber again. If the work can fail and must still happen, write the stage as a @SpaceTake; if it may fail harmlessly, catch what you can and let the rest go.

3. A reaction must not write its own cue type. The subscriber sees every entry of its cue type in the replica, including the entries this same process wrote a moment ago. A reaction that listens for X and returns an X delivers to itself forever. Return a different type, as every reaction in example 18 does, or when the type cannot change, put a field on the record that the reaction never produces and filter on it with where (chapter 6).

4. The result lease is how long the publication stays. The CoverageFinding stays in the intake space for one hour and then every replica drops it. A subscriber that starts late can still read it with readAll while the hour lasts; after that nothing replays it. When a record must outlive the flow, write it into a space of its own under a long lease: the Ledger writes every ClaimClosed into the ledger space under a twenty-four-hour lease, and the short-lived lanes stay short-lived.

Where we are in the claims flow

Stage 3, stage 3a, and stage 7a. The three findings of one claim land in the intake space on three different peers, in any order, and the Assembler must wait for all three before it can write the ClaimAssessment. Later, three shops write three RepairQuotes per claim and the QuoteGatherer must wait for exactly three before choosing the lowest. Later still, payments land one at a time and the Exposure stage must keep each claimant's running total current after every payment.

The records in play

What the stage must do

Fire once per claim when the RegisteredClaim, the FraudFinding, the CoverageFinding, and the damage finding for that claim are all present, whatever order they arrived in and whichever peer wrote them, and write one ClaimAssessment. In relational terms this is an equi-join of four record types on the one key claimId.

How AgentSpaces does it

@SpaceJoin tells the binder that assemble is a join. The annotation lists the parts: four @Part declarations, each naming a record type the join waits for. key = "claimId" names the field every part carries, except the damage finding, which is an Instance record with no claimId field; for that part keyTag = "claimId" tells the binder to read the key from a tag on the entry, and tags = "rdf:type=..." tells it to consider only instances of the damage-finding class. The binder subscribes to all four record types in the intake space, keeps a table of which parts it has seen per claimId, and when a claim has all four, reads the four entries again, wraps them in a Joined bag, and calls assemble on a virtual thread. Joined.get(type) returns the newest part of a type; Joined.key() returns the claim id. The binder writes the returned ClaimAssessment into the assessment space.

The binder also seeds its table from the space when the agent binds, so parts that landed before the Assembler started still count, and it forgets a claim whose parts stop arriving after within, one hour by default.

The options: how many times one claim fires

Example 18 binds one Assembler on peer-a. If you bind an Assembler on every peer, each one sees every claim complete, and the question becomes how many times one claim may fire across the group. That is the join's mode, and it is the join's one real trade-off.

LOCAL, the default. The binder remembers the keys it fired in memory and writes nothing before the result. Each bound joiner fires each claim once, so bind one Assembler, as example 18 does, or let the next stage discard a duplicate by the claim id. A restarted joiner re-reads the space and may fire a claim again.

LEASED. When a claim completes, the binder writes a JoinTicket entry for it into the join's space, withdraws the younger of two tickets written in the same instant, and fires from a take of that ticket. Several joiners on several peers then share one ticket per claim, and the take's lease gives the firing a retry. Under a network partition two tickets may survive, which is the contract of the lease race; the test joiner below shows two joiners and a crash.

ORDERED. The binder takes the ticket through the ordered-log coordinator registered for the join's space, and the first ticket the log commits for a claim is the only one that fires, on whichever peer took it. This is once across the group, at the price of the log: a peer hosts one ordered log per group, so the OrderedAssembler below names the payments space, where example 18's log runs, as the join's space, and intake on each part.

The options at a glance

The OrderedAssembler names the payments space as the join's own space, because example 18's ordered log runs there, and names intake on every part, because the findings live there. The join's space is where its tickets go; its parts may live anywhere.

The test binds two of these joiners over one space. Both see each key complete, one ticket stands per key, and the joiner that takes it fires. When the firing throws, the ticket's take lease lapses and the other joiner takes it, which is the take retry applied to a join.

What the stage must do

Wait for the three RepairQuotes of one claim and then choose the lowest. The QuoteDesk in chapter 3 wrote a QuoteRequest saying how many quotes to expect, so the gatherer can wait for exactly that many.

How AgentSpaces does it

A gather is a join whose part may appear several times for one key. countedBy = "QuoteRequest.expected" tells the binder to read the number of RepairQuotes to wait for from the expected field of the QuoteRequest part of the same claim, whenever that request lands, before or after the quotes. When the quotes reach that count, the binder calls pick, and Joined.all(RepairQuote.class) returns every quote for the claim. The method body is the fold: it keeps the lowest. The binder writes the RepairEstimate into the ledger space.

The options: when is "enough"

Option 1: a count another record declares. countedBy = "QuoteRequest.expected", as the QuoteGatherer uses. Choose it when the stage that forked the work knows how many pieces it made, and have that stage write the count; the binder reads it whenever the counting record lands.

Option 2: a fixed count. atLeast = n on the part, as the test gatherer below uses. Choose it when the design fixes the number. A fourth quote after the join fired does not fire it again.

Option 3: quiet for a while. settle = "300ms" on the join with atLeast = 1 on the part, as the second test gatherer below uses. The binder fires once no new quote has arrived for the settle time. Choose it when nobody knows the count; a slow bidder extends the window, and a settle time shorter than the gap between two honest bids splits one gather into two.

Option 4: give up. within on the join, one hour by default. The binder forgets a claim whose parts stop arriving, and a later part starts the claim again. Set it on every gather as the deadline for a claim that will never complete.

The options at a glance

"Reduce" names three different things in a fleet, and AgentSpaces has a separate expression for each. The QuoteGatherer above is the first: a bounded set of records per key, folded once in the method body. The Exposure stage below is the second: an unbounded stream of records per key, folded one at a time into an accumulator that stays current. The ReserveSensor and Supervisor in chapter 9 are the third: one number per peer, averaged across the group.

What the Exposure stage must do

Keep one ClaimantExposure record per claimant, holding the total paid and the number of payments, and advance it each time a Payment lands, without ever counting a payment twice and without two peers losing each other's update.

@SpaceReduce tells the binder that expose is a fold. The first parameter type, ClaimantExposure, is the accumulator; the second, Payment, is the element; key = "claimant" names the element field that groups payments by claimant. For each payment the binder takes the Payment entry under a thirty-second lease, reads the claimant's current ClaimantExposure entry (null for the first payment), calls expose, and completes the Payment entry with the returned ClaimantExposure as the result, in one commit. That one commit is why the stage never counts a payment twice: either the commit consumes the payment and writes the new total, or it does neither. The binder then retires the previous total. The twenty-four-hour accumulatorLease is the write lease of each new total, so a claimant with no payment for a day lapses from the space, and the lapse is an event chapter 10 can react to.

Two reducers on two peers could each take a different payment of the same claimant at the same moment, read the same old total, and each write a new total that ignores the other's payment. The binder prevents that with a JoinTicket per claimant: a reducer takes the claimant's ticket before it folds, renews the ticket's lease before every payment, and stops if a renewal fails. The hand-written version of this stage, take the payment, read the total, write a new one, loses updates in exactly that race, and no test on one peer shows it.

Reductions.current(space, ClaimantExposure.class, "exposure", claimant) is how any stage reads a claimant's newest total, and it is what the test uses on every peer. The developer guide's annotation chapter lists every attribute of @SpaceReduce, and the PetClinic scheduler keeps its appointment slot book the same way, as the other consumer.

Where we are in the claims flow

Stage 3, inside the Assembler. The four parts of a claim are in hand, and the assembler must write one ClaimAssessment that the adjusters can price without reading the four parts again.

The records in play

What the stage must do

Copy into the assessment exactly what the next stages need, and nothing else, so that the adjusters can price it, the quote desk can fork from it, and the senior reviewer can filter on its severity, each with one read of one record.

The Joined bag that the binder hands to assemble answers get(type) for the newest part of one type, find(type) for a part marked optional, all(type) for a gathered part, and entry(type) for the entry's metadata: who wrote it, its tags, its lease, and when. The assembler copies values out of the parts into the new record. damage.number("estimate") and damage.string("severity") read properties of the ontology instance, which chapter 12 explains.

The options: how to carry each value

Option 1: copy the value into the composed record. The assembler copies the severity, the fraud score, and the coverage limit into the ClaimAssessment, because the senior reviewer filters on the severity, the adjusters bid on it, and the pricing reads the limit. Choose it for any value a later stage matches on, keys on, or branches on; the writer owns the duplication, and the value freezes at composition time.

Option 2: carry the id of another entry. Every claim record carries policyId as a string rather than a policy. A stage that needs the policy reads it with a template on the id, as the Panelist in chapter 7 reads the PricedClaim by claimId. Choose it when the referent is large, has its own lease, or changes on its own; the reading stage pays one read and must handle a referent that lapsed.

Option 3: write a label as a tag. Return Tagged.of(record, key, value, ...), as the DamageEstimator does in chapter 12. Choose it when a stage must select on the value before decoding the record, or when the value is a label such as a class IRI rather than data. Tags stay in plain text under content encryption.

Option 4: compose parts from several spaces. Name a space on each @Part that lives elsewhere, as the OrderedAssembler in chapter 4 and the Party Bus plan assembler below do. Choose it when the parts live in different lanes; the join's own space is where its tickets go.

The options at a glance

The Party Bus plan assembler composes a ProposedTravelPlan from a TravelBrief in the trip space and five research results in the scouts space, and treats the Travelers record as optional: j.find(Travelers.class) returns an Optional, and the method supplies an empty party when nobody wrote one.

Where we are in the claims flow

Stages 3a, 3b, 4, and 1 again. The QuoteDesk wrote three QuoteTasks, and each of the three shops must take only the task that names it. The SeniorReviewer must see only the assessments whose severity is HIGH. The two adjusters must split the assessments so that the senior adjuster prices the severe ones and the junior the routine ones. And the Registrar of chapter 2 must send a claim down one of two paths, registered or rejected.

The records in play

What the stage must do

The NorthShop must take QuoteTask entries whose shop field is north and never touch the others. The SeniorReviewer must react to ClaimAssessment entries whose severity field is HIGH and ignore the rest.

How AgentSpaces does it

Every take and every reaction matches entries against a template. A template is a query: one record type, plus conditions on the record's fields and on the entry's tags. The binder builds the template for a method from the method's parameter type, and the annotation's where and tags attributes add conditions to it. The replica applies the template before it hands the entry to anyone, so a condition on the annotation keeps the method from ever seeing an entry that fails it.

where = "shop=north" adds the condition "the shop field equals north" to the NorthShop's template. The replica judges that condition before the take claims anything, so the north shop never leases a task meant for the east shop, and that task stays in the space for the east shop's take. Example 18 has one class per shop, NorthShop, EastShop, and SouthShop, because a Java annotation value must be a constant, and it binds one shop per peer.

The same attribute on a reaction keeps the replica from delivering a LOW or MEDIUM assessment to review at all. The test asserts that exactly one SeniorReview exists, for the one severe claim.

The order in which a replica judges a template matters. It compares the record type first, then the tags, then whether the entry is already claimed, then it decodes the record and judges the field conditions. Tags therefore cost nothing to check and a relay that cannot decrypt the record can still route on them (chapter 12); field conditions need the decoded record, so only a peer that holds the content key can judge them.

The options

Option 1: filter on a field, on the annotation. where = "shop=north" or where = "severity!=LOW". The binder adds the condition to the method's template at bind time and refuses a field the record lacks. Choose it when the routing key is a field with a fixed set of values; the filter compares the field's string form for equality or inequality, and a range stays in the method.

Option 2: filter on a tag, on the annotation. tags = "rdf:type=..." or tags = "region". The replica judges a tag before it decodes the record, so a relay without the content key can route on it, and a shard can hold only entries with it. Choose it when the producer labels the entry, as the DamageEstimator labels its instance in chapter 12.

Option 3: filter in the API, with any matcher. Build the template yourself: Template.of(PricedClaim.class).where("claimId", eq(id)), or gte, lt, in, contains. Choose it when the stage reads rather than subscribes, as the Panelist does in chapter 7, or when the condition is a comparison the annotation grammar cannot express.

Option 4: decide inside the method. Return null, as the PetClinic Vet does in chapter 3. Choose it when the decision needs a lookup or a computation. On a take, the binder has already claimed the entry by then and completes it when the method returns null, so the entry is gone; on a reaction the binder consumes nothing.

The options at a glance

What the stage must do

The Registrar must send each claim down one of two paths. A registered claim goes to the specialists; a rejected claim goes to the ledger. A Java method has one return type.

The Registrar.register method of chapter 2 declares Registration as its return type and returns either a RegisteredClaim or a Rejected. The binder writes whichever concrete record the method returns, and because you sealed the interface, the binder lists both permitted records on the agent's card, so a planner reading the card knows the registrar may produce either. The specialists consume RegisteredClaim; the Ledger consumes Rejected; each branch has its own consumer, and the flow never loses a claim it refused.

What the stage must do

Two adjusters price assessments. The SeniorAdjuster should price the severe claims and the JuniorAdjuster the routine ones, but neither should sit idle while the other has a backlog. The right routing depends on who is cheapest for each assessment at that moment, which no filter on the annotation can express.

How AgentSpaces does it

Chapter 1 built the assessment space with the AUCTION conflict strategy. Under that strategy every take carries a bid, the space collects the bids across the group for one gossip round, and the lowest bid wins the entry. An agent supplies its bid with a @BidFunction method, which the binder calls for each candidate entry before the take.

The SeniorAdjuster bids 10 for a HIGH assessment and 80 otherwise; the JuniorAdjuster bids 90 and 20. The test asserts that the senior adjuster priced the fire claim and the junior the collision. The pricing itself, Pricing.price, is the same code in both; only the bid differs. One agent per space per peer may bid, and every bid in a space should use one comparable cost unit.

The options, side by side

The three routing shapes answer three different questions. A filter asks which of the entries of this type are mine, and the answer is in the entry. A branch asks which type this entry should become, and the answer is in the producer. The auction asks which of several willing workers should take this entry, and the answer depends on the workers and the moment. The table collects them with the fork of chapter 3, which is the fourth shape: all of them at once.

The options at a glance

Where we are in the claims flow

Stages 5 and 6. An adjuster has written a PricedClaim. The department must put every priced claim to a panel of three, one panelist per peer, and act on the panel's decision: a PaymentOrder when the panel approves, a ClaimDenied when it denies.

The records in play

What the stages must do

The Underwriter opens one vote per priced claim, with the options approve and deny and a quorum of three. Each Panelist casts one ballot per vote, judging the priced claim against a ceiling of its own. The Approver acts exactly once when a vote closes.

How AgentSpaces does it

The vote capability keeps proposals, ballots, and decisions as ordinary entries in the decisions space, each signed by the agent that wrote it, so the space itself replicates the vote, authenticates every ballot, and keeps the audit trail. Three annotations describe one vote across three classes.

@Propose tells the binder that open opens a vote. The binder reacts to every PricedClaim in the assessment space, builds the proposal id from prefix plus the claim's claimId field, calls open for the question text, and writes a Proposal entry into the decisions space with the options, the quorum, and the ten-minute lease from the annotation. The binder opens each proposal id once per peer, and the method may return null to open nothing. The decisions.write line writes the Reminder that chapter 10 uses as the deadline, through a @SpaceRef field.

@Ballot tells the binder that judge casts ballots. The binder reacts to every Proposal whose id starts with claim:, calls judge, and writes a Ballot entry with the returned option, signed by the panelist's agent identity. The panelist reads the PricedClaim it is judging through a @SpaceRef field with a five-second wait, because the priced claim may not have replicated to this peer yet, and returns null to abstain if it has not. Example 18 gives the three panelists ceilings of 50,000, 50,000, and 15,000, so the panel splits two to one on the 25,000 fire claim and still approves it.

@OnDecision tells the binder that settle reacts to closed votes. When this peer's tally of ballots for a proposal reaches the quorum, the binder calls settle once with the Decision, which carries the winner, the tally, and the granularity the voters were counted at. The approver writes a PaymentOrder into the payments space by returning it, or a ClaimDenied into the ledger through a @SpaceRef field, since one return carries one record. Example 18 binds one Approver, on peer-a.

The options

Option 1: open with a fixed shape. @Propose holds the options, the quorum, the lease, and the rule that builds the proposal id, and the method returns only the question text. The Underwriter uses it because every claim vote looks the same. The Party Bus safety lead below uses it with a composite key, three fields joined into one id, so that several assessments of one wave open one vote.

Option 2: open with a shape built per call. Return a Motion from any bound method, built with Motion.of(id, question, options, quorum, lease). The Escalator of chapter 10 does this, and the Party Bus party lead below does it because its options are the destinations a scout proposed, which differ per trip. The binder opens a Motion's proposal id once, so a reaction that runs on every peer may return one safely.

Option 3: abstain. Return null from the @Ballot method. The Panelist abstains when the PricedClaim has not replicated within five seconds. An abstention is final for that voter on that proposal, so read with a timeout before abstaining.

Option 4: choose the quorum. The quorum is the number of distinct voters that closes the decision: three for the panel, one for the escalation. Too low and one peer decides; too high and a lost peer stalls the vote until the deadline of chapter 10 escalates it.

Option 5: choose who may vote. By default every authenticated agent in the group may cast a ballot. The vote capability can count only the holders of fresh cards, or only the agents an authorizer grants; the developer guide's security chapter covers both. A stage that needs the tally or the decision as data rather than as a cue injects a VoteClient with @CapabilityRef and asks it; a peer that serves the vote to the group registers it, through the facade or with @ProvidesCapability on the bean that builds it.

The options at a glance

The Party Bus safety lead reacts to every DangerAssessment, and several assessments, one per watcher channel, describe the same trip, location, and wave. The composite key joins the three fields into one proposal id, so the binder opens one vote per wave however many assessments arrive.

The party lead's options are the destinations a scout proposed, which differ per trip, so no annotation can hold them. The method builds a Motion with the options from the cue and returns it, and the binder opens the vote once per proposal id.

Where we are in the claims flow

Stage 7. The Approver wrote a PaymentOrder. A Payer on each of the three peers stands ready to pay it. The department must pay each order exactly once, and a network partition must not turn one order into two payments.

The records in play

What the stage must do

Take each PaymentOrder at most once across all three peers, pay it, and write the Payment in the same commit as the completion, so that neither a crash nor a partition produces two payments or zero.

How AgentSpaces does it

The lease race that the other spaces use promises at most one completed take per entry, but it allows two peers to both believe they hold an entry during a partition, and for a payment that is one belief too many. The ordered-log capability elects a Raft quorum among the three peers and serializes takes through a log: a take becomes a claim the log commits, the log admits one claim per entry generation, and every peer applies the same committed order, so every peer agrees on who holds each order.

@OrderedTake is @SpaceTake with the claim routed through the coordinator. The binder runs the same loop as chapter 2, but each claim goes through the log, and the binder resubmits a claim that a leader election lost. When the log admits the claim, the binder calls pay, then completes the PaymentOrder and writes the Payment in one commit, in the payments space. The ordered field is the coordinator the peer registered, which the payer uses only to record the commit index in the payment.

group.ordered(space, coordinator) tells the binder which coordinator backs @OrderedTake methods on the payments space. A peer hosts one ordered log per group, which is why the OrderedAssembler of chapter 4 also lives on the payments space. The log does not transact with the world outside the space: the method may still call a payment gateway once per retry, so the method makes the irreversible call last and keys it by the order's id.

The options, as a ladder

Rung 1: an idempotent write. If the step is a record and a second copy costs nothing, give the record a deterministic id and let a duplicate replace the first. The Ledger could write a ClaimClosed twice without harm.

Rung 2: a take under the lease race. @SpaceTake on an ordinary space promises at most one completed take per entry and tolerates transient duplicate work under a partition. The Registrar and the shops stand here, because registering or quoting twice is harmless.

Rung 3: a take through the ordered log. @OrderedTake promises exactly one completed take across the group, and costs a quorum round trip per claim and a live quorum. The Payer stands here, and example 12's Clerk below is the same stage on its own.

Rung 4: a join through the ordered log. @SpaceJoin(mode = ORDERED) gives the join's firing the same promise, for a join whose output starts an irreversible step, as the OrderedAssembler of chapter 4 does.

The options at a glance

Example 12 is this one stage on its own: three clerks, one log, orders written from several peers, and a test that kills a clerk mid-order and still counts one receipt per order.

Where we are in the claims flow

Stage 8. Each adjuster has priced a claim and set a reserve. The department wants to know the average reserve across every claim the whole fleet has priced, without any peer collecting every claim, and it wants one report when that figure has settled.

The records in play

What the stage must do

Every peer contributes the reserve of every claim it sees to one shared figure, the fleet converges on the average with no collector, and one agent writes one ReserveReport when the average stops moving.

How AgentSpaces does it

The aggregate capability runs push-sum gossip: every peer holds a value and a weight, each gossip round it halves them and sends half to one random peer that advertises the aggregate, and every peer's ratio converges to the fleet-wide average in a number of rounds logarithmic in the fleet size. An agent adds to it by returning a Contribution, and reads it by reacting to the settled estimate with @OnEstimate, or procedurally through an AggregateClient injected with @CapabilityRef (awaitSettled). A settle rule counts steps, and a step is a gossip round the peer took part in once it has heard the epoch at all, or the epoch heard and since gone quiet, which completes the streak: a peer nobody pushes to never settles on its own value, and a plateau before a late contribution does not count as settled either.

The ReserveSensor reacts to every PricedClaim and returns Contribution.to(epoch, value); the binder hands the value to the aggregate capability on this peer under the epoch name reserve:2026-10. Example 18 binds one ReserveSensor on each of the three peers, and every peer's replica delivers every PricedClaim, so each reserve enters the aggregate three times. The AVG operator does not mind: the average of three copies of each reserve equals the average of the reserves, which is why this chapter's options steer a fully replicated space away from SUM and COUNT. @OnEstimate tells the binder that report reacts to a settled estimate: the capability evaluates the settle rule at the end of each of its own ticks, and when the estimate for an epoch whose name starts with reserve: has stayed within one percent for twenty consecutive ticks, the binder calls report once and writes the ReserveReport to the ledger. Nothing polls.

The settle window is the number to tune. Forty steps is about ten quiet seconds at example 18's 250-millisecond peer tick, longer than the gap between the first and the last priced claim, so the one report carries the average of all four; twenty was not, once the paid claim's reserve followed the ordered log and could land twenty seconds after the denials' zero reserves, and a twenty-step settle reported that plateau. A flow that prices claims over a longer window wants a longer settle, or one epoch per claim.

The options

Option 1: contribute a value per entry. Return Contribution.to(epoch, value) from any bound method, as the ReserveSensor does for every PricedClaim. Choose it when the figure is a property of the entries a stage already sees.

Option 2: contribute a template's matches. Call PushSumAggregate.start(epochId, mode, space, template, field) on each peer. The capability reads every local entry the template matches, applies the field extractor to each, and contributes the fold under the mode. Choose it when the figure is over what each peer already holds; the template filters, the field maps, the mode reduces.

Option 3: choose the operator. AVG is the default and the one to reach for over a fully replicated space, because every peer holds every entry and an average of copies is the same average. SUM and COUNT multiply by the number of peers over a replicated space, so they belong over sharded or per-peer spaces. MIN, MAX, and a Quantile do not mind copies.

Option 4: react once when it settles. @OnEstimate(prefix, settleTicks, tolerance), as the Supervisor uses. Choose it when one agent must act on the figure once.

Option 5: read the live figure. AggregateClient.estimate(epoch) returns the current estimate, and awaitSettled(epoch, settle, timeout) blocks until it settles. The test reads the figure on peer-c this way. Choose it for a dashboard or for procedural code.

Option 6: decide on the figure. Return a Motion from the @OnEstimate method. The settled figure then opens a vote: sense, then decide.

The options at a glance

Where we are in the claims flow

Stage 6a, and the ledger. The Underwriter opened a vote and the panel may never answer. The department must escalate a claim the panel has not decided within the deadline, once, however many peers notice. And the Registrar rejected a claim with no amount; the department must close that case on the record rather than lose it.

The records in play

What the stage must do

When ten seconds pass after the underwriter opens a vote and no decision exists, open an escalation vote, once per claim. When the panel decides in time, do nothing.

How AgentSpaces does it

A space already runs timers: it sweeps leases and emits an EXPIRED event when an entry's write lease lapses. A deadline is therefore an entry written with the deadline as its lease, and a reaction that listens for that entry's expiry.

The Underwriter writes a Reminder for the claim with a lease equal to the panel's deadline. on = SpaceEvent.Kind.EXPIRED tells the binder to call escalate when a Reminder's lease lapses rather than when the underwriter writes it. The escalator asks the vote capability, through its votes field, whether a decision for the claim exists; if so it returns null, and if not it returns a Motion, which the binder turns into a new proposal. Every peer sweeps its own replica, so every peer that hosts an Escalator sees the lapse; the binder opens a Motion's proposal id once, so three escalators open one escalation. The test staffs a fleet with no panel and a short deadline and counts exactly one escalation per claim.

The options

Option 1: a deadline. Write an entry whose lease is the deadline and react to its EXPIRED event, as the Underwriter and the Escalator do. Choose it whenever something must happen if nothing happens in time.

Option 2: cancel a deadline. Keep the EntryHandle that write returned and call cancel() when the outcome arrives, or do what the escalator does and let the reaction find the outcome and return null. The second costs one lookup per lapse and needs no bookkeeping.

Option 3: notice a dead worker. React to REAPPEARED on a task type. A worker took the task, its lease lapsed, and the space offered the task again; the reaction sees that happen. Choose it for a supervisor that records failures. The task is already back in the space, so the supervisor observes rather than retries.

Option 4: notice completion elsewhere. React to COMPLETED. Choose it when a stage wants to know a task finished without consuming its result. The test agent below listens to a write and its lapse with one method.

Option 5: make the escalation happen once. Every peer sweeps its own replica, so every escalator sees the lapse. Return a Motion, which the binder opens once per proposal id, or write a record carrying the claim id that the next stage dedups on.

The options at a glance

A loop is a stage that writes its own cue record again with a round counter, until a condition holds. The claims flow has no loop, because a loop would be contrived there; the shape is the Registrar's sealed return turned inward. A stage takes a Retry(claimId, round), does the work, and returns either the result record or a new Retry with the round advanced. Two guards keep it finite: the stage returns the result instead of a retry when the work succeeds, and a where = "round!=5" filter on the annotation keeps the stage from taking a retry that has exhausted its rounds, so the exhausted retry sits in the space for a deadline to find. The cue type and the output type must differ, or the stage must filter on a field it never produces, for the reason chapter 3 gives.

What the stage must do

Close every case on the record, including the one the registrar refused, so that no claim disappears from the department's history.

The Ledger reacts to a Rejected in the intake space and writes a ClaimClosed into the ledger space under a twenty-four-hour lease. The same class has onPayment and onDenial for the other two outcomes, so every case closes through one agent whatever path it took. That is the smallest saga: a typed failure record, Rejected, and a compensating stage that reacts to it. A longer saga has one failure record per step that can fail and a compensating reaction per failure record, every record carrying the claimId. AgentSpaces supplies the records, the leases, and the correlation; the undo itself is yours.

A person is a stage. When a claim needs a manager's approval, the flow writes a request record for it and the manager writes an approval record through the console, the A2A gateway, or an application of your own. The flow waits for the approval the way it waits for anything: a join with the approval as a part, a Reminder written when the request went out, and an escalation when the reminder lapses. Nothing in the flow distinguishes a person from a worker. Lease the request for as long as a person takes, and put the deadline on the reminder, not on the request.

Where we are

Example 18 has no model and no planner; every stage is plain Java. This chapter says where each would go, with the one checked-in model worker the Spring AI examples provide, so that you can place a model step or a planner in your own flow without changing the patterns of the other chapters.

A model as a stage

A model does a stage's work the way any worker does. The method is a @SpaceTake, the model call sits inside it, and the structured record the model returns is the method's return value. The take lease covers the model's latency, and a crash mid-call lets the lease lapse and another worker retry.

The Summarizer takes a Brief from the work space, asks a Spring AI ChatClient for a summary, and returns a Summary, which the binder writes as the completion result. In the claims flow, the DamageEstimator of chapter 3 is where a model would read the claim's description and produce the damage finding; it would become a take rather than a reaction, because a model call can fail and should retry, and its lease would match the model's latency. The developer guide's Spring AI chapter covers the TakeLeaseAdvisor, which renews the take lease during a long call, and the fleet tools a model may choose between.

A planner as a composer

A planner works the other way round: it reads the cards of the agents in the group, treats each card's consumed and produced record types as an action, and composes a route from a starting record to a goal record. The Embabel bridge in the developer guide turns the fleet's cards into such actions. Invoking one is still a write of the consumed record into the right space and a correlated read of the produced record, so a planner composes the stages this guide describes; it does not replace them.

Where we are in the claims flow

Stage 2 again, the DamageEstimator. Example 18's records mirror a small claims vocabulary, an ontology with classes such as Claim and DamageFinding. Most of the flow carries that vocabulary as one Java record per class. The damage finding travels differently, as a generic instance of its class, to show the second way an ontology reaches a space.

The records in play

Every record in chapter 1 is this route. A namespace becomes a package, a class becomes a record, a datatype property becomes a component, an object property becomes a component holding the referent's id, and a class hierarchy becomes one record per leaf class or one record with a discriminator field. Every property then becomes a component a template can filter on, which is the strongest matching the space offers, and you pay one record per class.

One record carries any individual of any class. A template can match the components id, type, and typeIri; it cannot look inside properties, because a field condition reads one accessor and the map is one value. So anything a stage must match on moves out of the map: into a component, or into a tag on the entry. The map itself, like every map a signature covers (the entry's tags, a card's bindings), is encoded in canonical order on the wire since wire version 3, shorter UTF-8 keys first and bytewise between equal lengths, so an instance written by a Java peer and read by a Python or TypeScript one verifies whatever order its properties were built in.

The DamageEstimator builds a DamageFinding instance and returns it wrapped in Tagged.of(record, key, value, key, value). The binder writes the instance as an entry with two tags: claimId, which the Assembler in chapter 4 uses as the part's key through keyTag = "claimId", and rdf:type, which the assembler filters on through tags = "rdf:type=..." so that it joins damage findings and not some other class carried the same way. The assembler then reads the estimate and the severity out of the properties with damage.number("estimate") and damage.string("severity").

By default an entry's type name on the wire is the record's fully qualified class name with a version fragment. A NamespaceSchemaRegistry names the records of chosen packages by an ontology namespace instead, so that records, cards, remote actions, and the Python and TypeScript clients' constants all use the class IRI: NamespaceSchemaRegistry.of(Map.of("org.example.claims", "https://example.org/claims#")), given to the space builders and the binder, or a SchemaRegistry bean under the Spring Boot starter. The library's own reserved types keep their names.

The options

Route A: one record per class. Write a Java record for each class of the vocabulary. Every property is a component a template can filter on, every stage declares the concrete record it consumes, and the card tells the truth. Choose it when the vocabulary is stable and stages filter on many properties. Example 18 takes this route for every record but one.

Route B: generic instances. Carry each individual as an Instance with its class and a property map, and promote the properties stages match on into tags with Tagged.of. Choose it when the vocabulary changes faster than the code, or when one flow carries individuals of many classes. Example 18 takes this route for the damage finding, and chapter 4's assembler shows what it costs: a keyTag and a tags filter on the part instead of a field.

Route C: types named by IRI. Keep either route and add a NamespaceSchemaRegistry, so that the type name on every entry, card, and client constant is the class IRI. Choose it when systems outside the fleet, or clients in other languages, should recognise the ontology's names on the wire.

In every route: validate at the door. Check the vocabulary's constraints in the first take and return a Rejected record for incongruent data, as the Registrar does, so that the ledger closes the case instead of the flow losing it.

The options at a glance

Where we are

The whole flow. Example 18 runs as three peers over TCP, with five spaces and three capabilities on each, and its test runs the same fleet with a crash arranged. This chapter shows how example 18 assembles a peer, seats the agents, and asserts the outcome, so that your own flow has the same three parts.

Seating the agents

group().bind(agent) hands an agent to the binder of that peer's group and returns a handle that unbinds it when closed. Roles that must be singletons in the flow, the Assembler, the Underwriter, the Approver, the Ledger, the Supervisor, sit on one peer. Roles that are one per peer, the Panelist, the Payer, the ReserveSensor, sit on all three. The two Registrars show the lease race, and the two adjusters show the auction.

Arranging the crash

The Hook is the example's own interface, a callback the Registrar calls before registering, so that a test can throw inside the take. The test then asserts one property per stage, each by reading a space: every case closes once with its expected outcome; the crash happened once and every claim still registered; one assessment per claim however many joiners; the senior adjuster priced the severe claim; the panel split and still approved; exactly one payment per approved claim at every peer, folded once into its claimant's exposure; three quotes gathered and the lowest chosen; only the severe claim reviewed; no reminder escalated in the normal flow and one per claim when there is no panel; one reserve report at the four-claim average.

The harnesses

The fleet console shows the take ledger, which agent holds which entry under which lease, and the data map, which record types flow through which spaces with their tags. Both are the first place to look when a flow stalls; the wire-traffic panel, frames and bytes by kind as rates with the frames dropped as stale, replayed or unverifiable beside them, is where to look when a flow is slow rather than stuck. The checklist a flow leaves this guide with: every record carries the case id; every stage is a take or is safe to repeat; every effect that must happen once across the group is an ordered take, an ordered join, a vote, or a deduplicated write; every wait has a deadline; every failure is a record; and the test reads every property from a space.

The developer guide is the reference for each piece this guide composes: every annotation and attribute, the Space API, the conflict strategies, the capabilities, the console, and the same verbs from Python, TypeScript, and Clojure. The architecture guide decides what a flow like this should be built on: how many peers, which spaces and groups, which rung of the consistency ladder each stage stands on, and when a decision is a vote. Example 18's README walks the flow stage by stage with the test's assertions.