Agent shapes

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 organism 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. A fresh PeerId per session, not bonded into any organism’s ACL. The agent publishes no stable mosaik identifier.

Bonding. One ticket per write-side surface, obtained from each per-member 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 organisms — 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 TDX Measurements 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 organism 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 organisms consume claims with evidence pointers back to source documents in a public DA shard.

Shape 3 — Agent as organism 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 organism has an OrganismConfig fingerprint. Individual members have their own identities (a stable PeerId per member operator, bonded under the organism’s TicketValidator).

Bonding. Each member operator holds a ticket under the organism’s TicketValidator. The organism 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 organism shape. Members submit observations; the organism runs a threshold or quorum rule on the observations; the organism commits the result as its own fact.

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

See contributor — composite organisms for the generic discipline.

Shape 4 — Agent swarm as organism

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

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

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

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

Example. A reputation-weighted forecasting organism. Twenty forecaster agents, each running as a standalone organism and publishing a Stream<Forecast>, are referenced by a coalition. A forecasting organism 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 organism 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 (organism member).
    │
    no (each agent commits on its own)
    │
    Does a downstream aggregator across agents exist?
    │
    ├── yes ── Shape 2 agents + Shape 4 organism.
    │
    └── 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 OrganismConfig identity across hybrid models. A organism 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 organism whose committee expects specific TDX Measurements 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 organism; the organism redeploys under an updated OrganismConfig spanning the new agent set.

ai on mosaik