Soma — open protocol for agent work

Soma

让 Agent 彼此信任、共同记忆并为所做之事付费的统一协议。

**无需安装即可试用：**在浏览器中体验记忆演示 — https://rta.lat/hub/demo/recall?q=pricing · 商店和定价 — https://rta.lat/hub · 公共 MCP 节点，无需令牌 — https://rta.lat/soma/mcp

Agent 之间的消息是一个信封，而不是聊天消息。信封包含目标、任务、硬性令牌预算、授权、价格、截止时间和签名。记忆、传输、资金和历史记录都只是这个信封的载体。

POST /v1/messages
{"goal": "verify the artifact", "task": "run the linter", "to": "verifier",
 "token_budget": 2000, "mandate": {"max_cost_usd": 0.5}, "price_usdc": 0.005}

• **预算随消息传递。**接收方在开始之前就知道限额。
• **拒绝会说明原因。**每次拒绝都会指出触发的规则。
• **降级情况会明确声明。**如果上下文无法容纳，报告会说明丢弃了哪些内容。
• **签名可离线验证。**Ed25519，包含公钥——无需服务，也无需密钥。 在浏览器中试试：https://rta.lat/hub/verify（篡改某个字段，看看验证如何失败）。
• **成本按实际用量计量，而非列价。**令牌、CPU、字节、写入次数、外部调用。

60 秒上手

pip install -e ".[dev]"
soma keygen                       # ключ подписи Ed25519
soma serve                        # хаб на http://127.0.0.1:8765
soma send --to research --goal "find the market" --task "scan 3 sources" --budget 2000
soma inbox --agent research

或者使用 Python：

from soma import Envelope, Hub

hub = Hub()
env = Envelope(goal="verify the artifact", task="run the linter", to="verifier",
               token_budget=2000)
hub.send(env)                       # подписан и поставлен в очередь
hub.inbox("verifier")               # что ждёт агента
hub.claim(env.id, "verifier")       # забрать (атомарно)
hub.complete(env.id, {"text": "ok"})

为什么

Agent 已经能工作。它们缺少的是一个共享的神经系统：每个 Agent 只能记住自己的会话，凭信任行事，没有授权就花费资源，也无法证明自己做过什么。记忆、来源追踪、授权和记账都已存在——但它们是互不连通的独立产品。

Soma 是连接它们的纽带。它刻意保持精简：核心是一个协议、一个参考实现和一套一致性测试套件。它不是平台，不是框架，也不属于任何供应商。

包含内容

部件	内容
src/soma/envelope.py	协议核心：信封、规范化、签名、授权规则、路由器、JSON Schema
src/soma/memory.py	三层记忆——热队列、温事实（SQLite + FTS5）、按哈希存储的冷数据
src/soma/server.py	HTTP 传输（仅使用标准库）——/v1/messages、/v1/inbox、/v1/claim、/v1/complete、/v1/route
src/soma/mcp_adapter.py	MCP 适配器——以 MCP 工具形式提供相同操作（soma_send、soma_inbox、soma_claim、soma_complete、soma_route、soma_verify、soma_stats）
src/soma/payments.py	用量计量（令牌/CPU/字节/写入次数/调用次数）和兼容 x402 的支付合约
src/soma/anchors.py	仅追加的历史链（哈希链接），并预留了接入 Arweave/IPFS/Nostr 的接口
src/soma/registry.py	Agent 注册表——以文件形式存储，因此可随 Agent 一起移动
tests/test_protocol.py	属性测试：篡改会导致签名失效、授权拒绝时会指出规则名称、预算是硬性限制、TTL 到期
tests/test_conformance.py	一致性测试套件——任何实现都可以通过它验证
schemas/envelope.schema.json	传输格式（从代码导出——以此为唯一事实来源）
PROTOCOL.md	规范

构建自己的 hub，证明它支持 Mitra

一致性测试套件是这个项目的核心。运行方式有两种：

# 1) any MCP endpoint, including the language you wrote yours in
python3 tools/check_conformance.py https://rta.lat/soma/mcp

# 2) a Python implementation, in-process
MITRA_CONFORMANCE_IMPL="my_package.hub:MyHubFactory" pytest tests/test_conformance.py -v

公共演示节点运行于 https://rta.lat/soma/mcp — 无需令牌，每个客户端每小时 30 次请求，并且会强制将其存储的所有信封设为 visibility: public。那里不会存放任何私密内容。分步指南：docs/IMPLEMENT.md。

工厂函数会接收一个临时目录，并且必须返回一个包含以下方法的对象： send、inbox、claim、complete、route、verify、stats。 共 12 项检查：签名可验证、篡改会导致验证失败、预算得到遵守、降级情况已声明、过期信封不会被传递、声明具有排他性、拒绝会说明原因、完成操作会关闭信封、预算和授权会随信封传递、授权拒绝会指出规则，以及重复的信封 ID 不会覆盖原始信封。

与现有技术组合

Soma 不会取代其中任何一项——它只在它们之间传递信封：

• MCP — 适配器会将相同操作作为 MCP 工具公开。
• A2A — 本仓库中的 agents.json 是一张 A2A Agent Card；信封会映射为 A2A 任务。
• x402 — 支付标头契约定义在 src/soma/payments.py 中。
• OPA / Cedar — 授权接口是一个普通函数；策略引擎可接入其中。
• Sigstore / EIP-712 — 使用相同的基本原语（签名载荷，公钥随载荷传递）。
• Arweave / IPFS / Nostr — 锚定接口是一道接缝；本地哈希链可离线工作。

哪些是开放的，哪些不是

这是拆分的核心，因此我们会直截了当地写清楚。

层	示例	许可证	原因
协议	信封、三个记忆层级、路由器、五个接缝、一致性测试套件	MIT，永久	只有其他人也实现协议，它才有机会胜出；我们的协议只是一个候选方案，而非法律
引擎	深度工件验证、带账本的授权引擎、真实成本计量、技能检查器的规则库	闭源	这是我们的销售产品
服务	托管中心、保障、x402 结算、声誉、共享历史、注册表	闭源	带来持续收入，而且声誉无法复制——只能逐渐积累

本仓库中的参考实现刻意保持精简：足以运行、测试和理解。它们不是引擎。我们的商业套件（Mitra Core）可接入相同的接缝，并且是我们拥有的最佳实现——但它不在本仓库中。

如果你读到这里是为了决定是否基于 Soma 构建：可以，尽管构建。如果你读到这里是为了决定是否使用我们的托管版本，而不自行运行：这是个合理的问题，答案取决于你是否需要保障、共享历史和托管密钥管理，还是更愿意自行运行一切。

接入你自己的引擎

这五个接缝是协议（soma/interfaces.py）：Signer、MandateEvaluator、MemoryTier、 Meter、Anchor。任何满足这些协议的对象都可以作为插件。

# my_engine.py
from soma.envelope import Mandate

class StrictMandate:
    name = "my-engine"

    def check(self, action, mandate, only=None):
        if action.get("payee") == "mallory":
            return False, "payee: blocked by my engine"
        return True, "ok"

def components():
    return {"mandate": StrictMandate()}

可以通过两种方式加载：

# 1) environment — for experiments and local runs
SOMA_PLUGINS="my_engine:components" soma serve

# 2) entry point — for a distributed package
#    [project.entry-points."soma.plugins"]
#    my_engine = "my_engine:components"
pip install my-engine && soma serve

GET /healthz 会报告实际已连接的内容：

{"components": {"signer": "ed25519", "mandate": "my-engine", "meter": "usage",
                "memory": "Memory", "anchor": "LocalChain", "plugins": ["my-engine"]}}

有问题的插件会被跳过，不会导致程序退出：中心会使用参考实现启动，并在 /healthz 中说明这一点。

谁是谁，以及这为何重要

注册表就是一个文件。Agent 通过证明自己持有密钥来加入注册表：中心会发出一次性 nonce，Agent 对其签名，外部密钥无法混入。任务完成后，执行方会对回执签名；中心验证后计数。授权拒绝的操作会计为违规。因此，声誉是一个可推导的事实——verified_receipts − 4 × breaches——任何人都可以根据回执重新计算，没有主观评价，也没有星级评分。

两个节点，一套协议

节点可以共享工作和历史。默认情况下，数据是私有的：只有明确标记为 shared 或 public 的信封才会离开节点；每个到达的信封都会经过签名验证，并根据接收方的注册表进行检查。历史记录是一条哈希链接链，其他节点可以导入并验证——因此，它能在经历过这些历史的节点消失后依然留存。所有这些都不需要区块链；你需要时，可以通过外部锚定服务（Arweave、IPFS）发布这条链。

服务配置

默认情况下，参考传输方式为 本地：无需身份验证，绑定到 127.0.0.1，应将其置于你自己的网关之后。对于公开部署，可使用托管配置：

SOMA_MANAGED=1 SOMA_TOKEN=<secret> SOMA_QUOTA_PER_HOUR=100 soma serve

变量	含义
SOMA_MANAGED=1	要求每个请求都携带 Authorization: Bearer $SOMA_TOKEN
SOMA_TOKEN	令牌；若未设置，托管配置将拒绝所有请求
SOMA_QUOTA_PER_HOUR	每个发送方每小时的最大信封数（0 = 不限）
SOMA_MAX_BODY	请求正文的最大字节数（默认 1 MiB）

未配置令牌时，托管配置会关闭；错误配置绝不能打开入口。配额按发送方统计，因此某个行为嘈杂的 Agent 无法耗尽其他 Agent 的配额。

明确说明信任边界

• 参考 HTTP 传输方式没有身份验证，且绑定到 127.0.0.1。在将其公开之前，应将其置于你自己的网关（TLS、身份验证、速率限制）之后。正文大小上限为 1 MiB。
• 签名本身只能证明完整性。只有当发送方的公钥位于 Agent 注册表中时，才能证明来源；否则，任何人都可以用自己的密钥为自己的信封签名。参考实现会在存在注册表时检查注册表。
• 本地历史链可证明顺序和连续性；最新条目要经过外部锚定才能最终确定。

以测量为依据，而非空口宣称

记忆质量通过测量得出，而非凭空断言。基准测试离线运行，不使用大模型： bench/memory_bench.py（数值）和 tests/test_recall_abilities.py（能力）。

测量项	结果
1,000 条事实、100 个查询的 Recall@1	100 %（仅取最近 20 条事实的窗口：30 %）
每个答案的令牌数	~24（完整上下文：8,921）
分别测试的能力	5 项——提取、跨会话、时间窗口、取代、拒答
签名	已离线验证；历史正文已明确验证并标注为历史正文

此处的拒答是指：对于没有依据事实的问题，不返回任何内容，而不是返回最相似的合理答案。总会作答的记忆与编造信息无从区分。

状态

Beta。协议已版本化（soma/1）；信封均已签名，预算严格执行，拒绝请求时会说明原因。接下来的计划见 ROADMAP.md，信任模型见 SECURITY.md。

许可证

MIT。