Soma: an open protocol for agents to trust each other (with a conformance suite)

#ai #agents #opensource #protocol

We open-sourced Soma — a small protocol for agents to trust each other, remember together,
and pay for what they actually did.

https://github.com/mrpkk/soma-protocol (MIT, Python, no required dependencies)

Most agent frameworks solve the inside problem: how to orchestrate several agents in one
process. Soma solves the between problem: how two agents that have never met, do not share a
runtime, and do not trust each other, exchange work with a budget, a mandate and a signature.

The one idea

A message between agents is an envelope, not a chat line.

{
  "goal": "verify the artifact",
  "task": "run the linter on ./SKILL.md",
  "to": "verifier",
  "token_budget": 2000,
  "mandate": {"max_cost_usd": 0.5},
  "price_usdc": 0.005,
  "ttl_s": 3600
}

Everything else is a carrier of that envelope. That one decision produces the properties that
matter in production:

The budget travels with the message. The receiver knows the limit before it starts, so context assembly is a hard constraint, not a hope.
Refusals name the rule. A mandate check returns amount: 50.0 above the mandate of 0.5 — not a boolean. An agent can act on the reason.
Degradation is declared. If the context did not fit, the report says what was dropped (dropped: [...]). Silent truncation is how agents become confidently wrong.
Signatures verify offline. Ed25519, and the public key travels inside the envelope, so a skeptic can check it without trusting the hub and without a secret.
Cost is measured, not listed. Tokens, CPU seconds, bytes, writes, external calls — a call that burns 30k tokens and 4 seconds is priced by that.

Three memory tiers, one hard budget

Tier	Where	Rule
hot	envelope queue	goal and task always in context; TTL cleans up
warm	facts with versions and edges (SQLite + FTS5, trigram)	retrieved by query, selected under budget
cold	artifacts addressed by `sha256`	fetched by hash, included only if it fits

The context never grows; the store does. That is the whole anti-degradation mechanism, and it is
about 200 lines of code.

The part we care about most: a conformance suite

Protocols only win if other people implement them. So the repository ships a test suite that
any implementation can pass:

SOMA_CONFORMANCE_IMPL="my_package.hub:MyHubFactory" pytest tests/test_conformance.py -v

Ten checks, each one a property a real deployment depends on:

#	Property
C1	send returns an envelope id
C2	envelopes are signed and verify
C3	tampering invalidates the signature
C4	the assembled context respects `token_budget`
C5	degradation is declared (`dropped` present)
C6	expired envelopes are not delivered
C7	claims are exclusive
C8	routing refusals explain themselves
C9	completion closes the envelope
C10	budget and mandate travel with the envelope

If your hub passes these, an agent can talk to ours and ours can talk to yours.

What it is not

Not a runtime. Not an orchestrator. Not a hosted platform. Not a mandatory blockchain. A protocol,
a reference implementation and a suite of tests — roughly 1,200 lines including docs.

Composing, not replacing

The envelope shape maps onto what already exists, so Soma is a carrier rather than a competitor:

MCP — an adapter exposes the same operations as MCP tools;
A2A — an envelope is a task, agents.json is the Agent Card;
x402 — the payment contract is defined; settlement stays a transport concern;
OPA / Cedar — the mandate is a plain function, so a policy engine plugs in;
Sigstore / EIP-712 — the same primitive: signed payload, public key travels with it;
Arweave / IPFS / Nostr — the history anchor is a seam; a local hash chain works offline.

Try it in five minutes

pip install -e ".[dev]"
soma keygen
soma serve
soma send --to research --goal "find the market" --task "scan 3 sources" --budget 2000
soma inbox --agent research

Beta, MIT, and deliberately small. If you are building agents that have to work with agents you
do not control, the envelope is worth a look — and if you build a hub, the conformance suite is
the fastest way to argue that it is compatible.

Repository: https://github.com/mrpkk/soma-protocol

Renamed from mitra-hub to soma-protocol on the first day after publication, at the owner's request: the protocol is the organism (Soma — the rhythm and the shared oath), while the commercial bundle of engines keeps the name Mitra Core.

DEV Community