MCP 服务器

swarm-at

Enables agent settlement, trust verification, and ledger operations for multi-agent workflows, with tools for blueprint management, credit tracking, and provenance recording.

README

swarm.at Public Ledger

Hash-chained public record of verified agent settlements. Append-only, tamper-evident, auditable by anyone.

Every entry in ledger.jsonl is a SHA-256 hash-chained settlement that passed the full verification pipeline: integrity check, confidence threshold, and shadow audit. Modifying any entry breaks all subsequent hashes.

Ledger Format

Each line in ledger.jsonl is a JSON object:

{
  "timestamp": 1770480398.05,
  "task_id": "fingerprint-pg84",
  "parent_hash": "000000...000000",
  "payload": { "type": "text-fingerprint", "title": "Frankenstein", "..." : "..." },
  "current_hash": "453eaa...178b287"
}

parent_hash links to the previous entry's current_hash (genesis = 0 x 64)
current_hash = SHA-256 of the entry with current_hash set to ""
The chain is tamper-evident: modifying any entry breaks all subsequent hashes

Canonical Hash Algorithm

To verify any entry:

Parse the JSON line into a dict
Set current_hash to "" (empty string)
Serialize with json.dumps(entry, sort_keys=True).encode() (UTF-8)
Compute hashlib.sha256(serialized).hexdigest()
Compare against the stored current_hash

The genesis (first entry's parent_hash) is always "0" * 64 (64 zero characters).

Data Provenance

Entries in this ledger are synthetic seed data generated from public domain sources (Project Gutenberg texts, scientific constants, geographic facts). They demonstrate the settlement protocol's hash-chaining and verification pipeline. They are not records of real agent interactions.

Verification

Three ways to verify the chain:

Standalone (zero dependencies, Python 3.8+):

python verify.py
# OK: 1107 entries, chain intact

SDK:

from swarm_at.settler import Ledger
ledger = Ledger(path="ledger.jsonl")
print(ledger.verify_chain())  # True

API:

curl https://api.swarm.at/public/ledger/verify
# {"intact": true, "entry_count": 1107}

Settlement Receipts

Every settled entry produces a receipt that any agent can look up by hash. No authentication required.

curl https://api.swarm.at/public/receipts/{hash}
# {"status": "SETTLED", "hash": "...", "task_id": "...", "timestamp": ..., "parent_hash": "..."}

Receipts let third parties verify that a specific settlement happened, when it happened, and where it sits in the chain.

Trust Verification

Check an agent's trust level without authentication:

# Does this agent meet a trust threshold?
curl "https://api.swarm.at/public/verify-trust?agent_id=X&min_trust=trusted"
# {"agent_id": "X", "meets_requirement": true, "trust_level": "trusted", "reputation_score": 0.95}

# How many agents at each trust level?
curl https://api.swarm.at/public/trust-summary
# {"total_agents": 5, "by_trust_level": {"untrusted": 0, "provisional": 0, "trusted": 4, "senior": 1}}

Trust Badges

Embeddable SVG badges show an agent's trust level at a glance. No authentication required.

https://api.swarm.at/badge/{agent_id}

Colors: untrusted (red), provisional (yellow), trusted (green), senior (blue).

MCP Server

29 tools available via the Model Context Protocol:

mcp add swarm-at -- python -m swarm_at.mcp

Tool	Description
settle_action	Validate an action against institutional rules
check_settlement	Query ledger status for a task or hash
ledger_status	Current chain state (latest hash, entry count, integrity)
guard_action	Settle before acting — propose + settle + receipt in one call
list_blueprints	Browse workflow blueprints by tag
get_blueprint	Full blueprint detail with steps and credit cost
get_credits	Check an agent's credit balance
topup_credits	Add credits to an agent
fork_blueprint	Fork a blueprint into an executable workflow
verify_receipt	Look up a settlement receipt by hash
check_trust	Check if an agent meets a minimum trust threshold
settle_batch	Settle multiple proposals in one call
register_agent	Register a new agent identity with trust tracking
get_agent	Look up an agent's profile and reputation
list_agents	Browse agents by trust level and role
whoami	Agent self-introspection (trust, tools, next promotion)
execute_step	Execute a single workflow step in a molecule
list_molecules	List active workflow molecules with progress
get_molecule	Get full molecule state with all beads
register_webhook	Subscribe to settlement events
list_webhooks	List registered webhook subscriptions
unregister_webhook	Remove a webhook subscription
claim_authorship	Create a verifiable authorship record
verify_authorship	Check authorship claims by content hash
start_writing_session	Start tracking authorship provenance
record_writing_event	Record a creative event in a session
approve_writing	Record final approval of content
get_provenance_report	Generate a verifiable provenance report
list_writing_sessions	List active authorship sessions

Framework Adapters

Seven adapters settle agent outputs with zero hard dependencies on the framework:

Framework	Adapter	Entry Point
LangGraph	`SwarmNodeWrapper`	Wraps node functions
CrewAI	`SwarmTaskCallback`	Task completion callback
AutoGen	`SwarmReplyCallback`	Agent reply observer
OpenAI Assistants	`SwarmRunHandler`	Run and step settlement
OpenAI Agents SDK	`SwarmAgentHook`	Runner result and tool call settlement
Strands (AWS)	`SwarmStrandsCallback`	Tool and agent completion callbacks
Haystack	`SwarmSettlementComponent`	Pipeline component returning receipts

Install adapters via optional extras:

pip install swarm-at-sdk[langgraph]
pip install swarm-at-sdk[openai-agents]
pip install swarm-at-sdk[strands]
pip install swarm-at-sdk[haystack]

Blueprint Catalog

58 pre-validated blueprints across 9 categories:

Category	Count	Examples
Procurement & Supply Chain	5	vendor-negotiation, purchase-approval, delivery-confirmation
Software Development	5	code-review-pipeline, pr-merge-audit, incident-escalation
Finance & Compliance	5	invoice-matching, kyc-verification, financial-close
Content & Knowledge	5	research-workflow, fact-checking, translation-verification
Customer Operations	5	escalation-routing, refund-approval, sla-compliance
Specialty	6	audit-chain, healthcare-referral, insurance-adjudication
AI & ML Ops	9	model-validation, training-pipeline, prompt-regression
Security & Compliance	9	vulnerability-triage, access-review, incident-response
Data Engineering	9	etl-pipeline, data-quality, schema-migration

Browse: api.swarm.at/public/blueprints

Each blueprint defines 2-4 steps with role assignments (worker, auditor, specialist, orchestrator, validator), dependency chains, and credit costs (2.0-8.0 per settlement).

Settlement Types

<details> <summary>42 types covering knowledge verification, agent behaviors, and protocol operations</summary>

Knowledge Verification

Type	Description
text-fingerprint	Public domain text ingestion + hashing
qa-verification	Factual Q&A with multi-agent consensus
fact-extraction	Structured entity extraction from text
classification	Genre/topic/tone multi-label tagging
summarization	Text condensation with cross-verification
translation-audit	Cross-language verification
data-validation	Math constants + periodic table verification
code-review	Algorithm correctness + complexity analysis
sentiment-analysis	Dimensional sentiment scoring
logical-reasoning	Syllogism and formal logic verification
unit-conversion	Metric/imperial/scientific unit verification
geo-validation	Geographic fact verification
timeline-ordering	Chronological event ordering
regex-verification	Pattern matching correctness
schema-validation	Data schema conformance checking

Agent Behaviors

Type	Description
code-generation	New code creation with language + framework metadata
code-edit	Modifications to existing code with diff tracking
code-refactor	Structural improvements preserving behavior
bug-fix	Defect resolution with root cause analysis
test-authoring	Test creation with coverage and assertion tracking
codebase-search	Code search operations with match scoring
web-research	Web research with source verification
planning	Task decomposition and execution planning
debugging	Diagnostic investigation with hypothesis tracking
shell-execution	Shell command execution with safety classification
file-operation	File system operations with change tracking
git-operation	Git operations with ref and diff metadata
dependency-management	Package and dependency management
agent-handoff	Task delegation between agents
consensus-vote	Multi-agent consensus participation
task-delegation	Work distribution to sub-agents
documentation	Documentation creation and updates
api-integration	External API calls with endpoint tracking
deployment	Build, deploy, and release operations
conversation-turn	Conversational exchange settlement

Protocol Operations

Type	Description
blueprint-fork	Blueprint forked into executable workflow
guard-action	Pre-action settlement check (settle before you act)
trust-check	Agent trust level verification against threshold
credit-topup	Credits added to agent balance
receipt-verify	Settlement receipt lookup by hash
badge-request	Trust badge SVG generation
adapter-settlement	Framework adapter settling agent output

</details>

Lexicon

Term	Definition
Settlement	A verified, hash-chained record of an agent action. One credit = one settlement.
Ledger	Append-only JSONL file where settlements are recorded. Each entry's hash chains to the previous.
Proposal	An agent's request to settle an action. Contains a header (task ID, parent hash) and payload (data, confidence score).
Receipt	Proof that a settlement occurred. Contains hash, task ID, timestamp, and parent hash. Publicly verifiable.
Blueprint	A pre-validated workflow template with ordered steps, role assignments, and credit cost. Forkable by any agent.
Workflow	An executable instance of a blueprint. Created by forking. Each step maps to one settlement.
Trust Level	Agent reputation tier: untrusted, provisional, trusted, senior. Computed via Bayesian credible intervals.
Credit	Unit of settlement currency. 1 credit = 1 settlement. New agents get 100 free.
Guard Action	Pattern: settle before you act. Propose, settle, get receipt in one call. Raises error on rejection.
Shadow Audit	Cross-model verification where a second model independently checks the primary's output.
Divergence	When a shadow audit disagrees with the primary. Penalizes the agent's trust score.
Adapter	Framework integration that settles agent outputs without hard-importing the framework. Uses duck typing.
Agent Card	A2A discovery document at `/.well-known/agent-card.json` describing the protocol's capabilities.
Tier	Settlement strictness level: sandbox (log-only), staging (writes, no chain enforcement), production (full).