Agents as citizens

audience: ai

Overview introduces the four shapes an agent can take. This page walks each shape concretely: when to pick it, what identity you commit to, what bonding looks like, what changes when the agent is retired or rotated.

The four shapes are not a ladder to climb. An agent society may contain every shape simultaneously: a pool of inference integrators querying an attestation fabric confluence whose members are standalone-organism agents, all referenced by one coalition.

Shape 1 — Agent as integrator

Pick when. The agent’s output is a private action (a trade, a tool invocation, an HTTP call) not consumed by peers on mosaik. Policy updates happen out of band. No other party needs to bond against the agent’s identity.

Identity. ClientId, ephemeral per session. The agent publishes no stable mosaik identifier.

Bonding. One ticket per write-side surface, obtained from each per-citizen operator the agent writes to.

Lifecycle. Start, observe, act, shut down. No retirement marker; peers never expected the agent to commit.

Cost to run. Equal to a non-agent integrator. No committee, no state machine, no ACL.

Example. A cross-chain arbitrage agent that observes offer::AuctionOutcome on three lattices and submits bundles via offer::Offer::<Bundle>::bid. The agent’s policy is a model weighted by observed fills.

See quickstart for the bring-up sequence.

Shape 2 — Agent as standalone organism

Pick when.

The agent’s output is consumed by peers — other agents, non-agent integrators, or confluences — that need a stable address to bond against.
The agent’s history is consumed — for audit, reputation scoring, or as evidence in downstream commits.
The agent’s policy runs under committee consensus (k-of-n members of the organism run the policy deterministically on the same input set).

Identity. A Config fingerprint derived by the agent’s operator. Stable across operational rotations per the stable-id / content-hash split: stable id unchanged on MR_TD bumps, content hash bumps on every operational rotation.

Bonding. Other parties hold tickets under the agent’s TicketValidator. A reputation organism bonds read-only; a downstream confluence bonds read-only for the agent’s public surface and possibly write-only for evidence submission.

Public surface. One or two primitives, following the narrow-surface discipline:

#[non_exhaustive]
pub struct AgentConfig<'a> {
    pub name: &'a str,
    /// State-affecting parameters: model family,
    /// version, decoding temperature, any policy-level
    /// constant downstream consumers must agree on.
    pub content: AgentContent<'a>,
    /// Who may bond into the agent's surfaces.
    pub acl: AclComposition<'a>,
}

// Public surface example:
//   AgentOutput    Stream<AgentCommitment>
//   AgentArtefacts Collection<ArtefactId, Artefact>

Lifecycle. Bring-up mirrors any mosaik-native committee organism:

Publish the Config.
Stand up committee members with the agent’s policy running deterministically (threshold cryptography or TDX attestation if the policy handles sensitive inputs).
When retiring, emit a RetirementMarker on each public primitive pointing at the replacement agent, if any.

Determinism caveat. An AI policy built on a non-deterministic decoder cannot run under a majority- honest Raft committee unmodified. Two common answers:

Single-member deployment. The agent runs with N=1 and is simply a bonded process; losing integrity reduces to trusting that operator, same as any other N=1 organism.
Attested deployment. Committee members run the same model, same weights, same decoding seed inside TDX; determinism is enforced by the measurement, not by Raft.
Threshold inference. Committee members each run independent inference; a threshold scheme aggregates their outputs. Useful when the agent’s job is classification or scoring; harder when the output is free-form generation.

Example. An oracle-style agent that commits a Stream<Claim> of fact-checked news items keyed by (claim_hash, source). Downstream confluences consume claims with evidence pointers back to source documents in a public DA shard.

Shape 3 — Agent as confluence member

Pick when. A set of agents (possibly heterogeneous — different models, different operators) needs to commit one joint output rather than N independent ones. The output is what downstream consumers see; individual member opinions are committed internally but not as the authoritative fact.

Identity. The confluence has a ConfluenceConfig fingerprint. Individual members have their own identities (usually a ClientId per member operator), scoped inside the confluence’s ACL.

Bonding. Each member operator holds a ticket under the confluence’s TicketValidator. The confluence may require TDX attestation on every member, or require that members hold a ticket from a specific reputation organism that scored them highly enough to qualify.

State machine shape. Standard mosaik confluence shape. Members submit observations; the confluence runs a threshold or quorum rule on the observations; the confluence commits the result as its own fact.

Example. A classification committee: N vision agents each submit a label for every incoming image; the confluence commits the label when some majority of members agree, plus metadata on dissenting members for downstream calibration.

See contributor — confluences for the generic discipline.

Shape 4 — Agent swarm as confluence

Pick when. Many agents run independently as standalone organisms (shape 2) and a confluence stitches their public surfaces into one aggregated view.

This is distinct from shape 3: in shape 3 the agents are the confluence’s committee; in shape 4 the agents are upstream citizens the confluence reads from.

Identity. Every agent has its own Config fingerprint; the confluence’s Config folds each agent’s stable id as a spanned citizen. The coalition references the agents via OrganismRef and the confluence via ConfluenceConfig.

Bonding. The confluence’s committee bonds against each agent organism’s public surface as any cross- citizen confluence would. No coupling between agents at the protocol layer.

Example. A reputation-weighted forecasting confluence. Twenty forecaster agents, each running as a standalone organism and publishing a Stream<Forecast>, are referenced by a coalition. A forecasting confluence subscribes to each agent’s forecast stream and commits a weighted average. A reputation organism (also a standalone organism, referenced by the same coalition) scores each agent based on realised outcomes; the confluence reads the scores and weights accordingly.

This shape is the mechanical match for most of the “emergent coordination” section; see emergent coordination for worked patterns.

Choosing a shape — decision tree

  Is the agent's output consumed by peers on mosaik?
    │
    └── no  ── Shape 1 (integrator). Cheapest.
    │
    yes
    │
    Does the agent's committee reach one joint output
    rather than per-member outputs?
    │
    ├── yes ── Shape 3 (confluence member).
    │
    no (each agent commits on its own)
    │
    Does a downstream aggregator across agents exist?
    │
    ├── yes ── Shape 2 agents + Shape 4 confluence.
    │
    └── no  ── Shape 2 only.

Identity hygiene across shapes

Do not reuse a fingerprint across shape changes. An agent promoted from shape 1 to shape 2 publishes a new Config with a fresh stable id. There is no retroactive identity.
Do not share ConfluenceConfig identity across hybrid models. A confluence whose member set changes enough to qualify as a new state machine publishes a new Config and emits a retirement marker on the old one.
Pin content hash only when you need to. An agent confluence whose committee expects specific MR_TDs on upstream agents (shape 4) pins their content hash. Consumer-agent societies that tolerate weights swapping within a content-hash contract pin stable id only. See the stable-id / content-hash split.

Retirement and handover

A retiring agent organism emits a RetirementMarker whose replacement field points at the successor, if any. Downstream consumers bound to the agent follow the pointer rather than re-discovering.

For shape 4 (swarm), retirement cascades: retiring one upstream agent does not retire the confluence; the confluence redeploys under an updated ConfluenceConfig spanning the new agent set.

Keyboard shortcuts

AI