swarm-at-sdk

swarm.at

Settlement protocol for AI agent workflows. Every agent action commits to a hash-chained, tamper-evident ledger backed by git.

Install

pip install swarm-at-sdk

With framework adapters:

pip install swarm-at-sdk[langgraph]   # LangGraph
pip install swarm-at-sdk[autogen]     # AutoGen
pip install swarm-at-sdk[crewai]      # CrewAI
pip install swarm-at-sdk[openai]      # OpenAI Assistants
pip install swarm-at-sdk[all]         # Everything

Quick Start

One-liner settlement for any agent:

from swarm_at import settle

result = settle(agent="my-agent", task="research", data={"findings": "..."})
assert result.status.value == "SETTLED"

Full control with SettlementContext:

from swarm_at import SettlementContext

ctx = SettlementContext()  # local engine + ledger
r1 = ctx.settle(agent="agent-a", task="step-1")
r2 = ctx.settle(agent="agent-a", task="step-2")  # auto-chains hashes

Point at a remote API:

export SWARM_API_URL=https://api.swarm.at
export SWARM_API_KEY=sk-...

from swarm_at import settle
settle(agent="remote-agent", task="classify")  # uses HTTP

Settlement Tiers

Start in sandbox, move to production when ready.

Tier	Behavior
SANDBOX	Log-only. No ledger writes. Returns synthetic hashes. Safe to experiment.
STAGING	Writes to ledger but skips chain enforcement. Good for integration testing.
PRODUCTION	Full verification: hash-chain integrity, confidence thresholds, shadow audits.

export SWARM_TIER=sandbox  # or staging, production (default)

Framework Adapters

Drop-in settlement for the major agent frameworks. No framework imports required.

LangGraph:

from swarm_at.adapters.langgraph import SwarmNodeWrapper

wrapper = SwarmNodeWrapper(agent="research-agent")

@wrapper.wrap
def research_node(state):
    return {"findings": "..."}

AutoGen:

from swarm_at.adapters.autogen import SwarmReplyCallback

callback = SwarmReplyCallback()
agent.register_reply([autogen.Agent], callback.on_reply)

CrewAI:

from swarm_at.adapters.crewai import SwarmTaskCallback

callback = SwarmTaskCallback()
crew = Crew(agents=[...], tasks=[...], task_callback=callback.on_task_complete)

OpenAI Assistants:

from swarm_at.adapters.openai_assistants import SwarmRunHandler

handler = SwarmRunHandler(assistant_id="asst_abc123")
handler.settle_run(run, messages)

Authorship Provenance

Need to prove a human was in creative control when AI tools were involved? WritingSession records every decision to the settlement ledger and produces a verifiable provenance report — implementing the Human-AI Agency Spectrum framework (Ghuneim, 2026).

from swarm_at import WritingSession
from swarm_at.authorship import CreativePhase

session = WritingSession(writer="jane-doe", tool="claude-sonnet-4-5")

# Human creative decisions (L4-L5 agency)
session.direct(action="premise", chose="noir detective", phase=CreativePhase.CONCEPT)

# AI-assisted drafting (L1-L3 agency)
session.prompt(text="Write the opening scene", phase=CreativePhase.SCENE)
session.generate(output_hash="<sha256-of-output>", model="claude-sonnet-4-5")

# Human edits to AI output
session.revise(description="Rewrote opening, cut 40%", kept_ratio=0.35)

# Verifiable provenance report
report = session.report()
print(report.work_agency)       # 0.92 (weighted phase score, 0.0-1.0)
print(report.safe_harbor)       # True (>= 0.90 threshold)
print(report.chain_verified)    # True (hash-chain intact)
print(report.to_text())         # Human-readable report for legal/editorial review

The report maps work agency scores to compliance frameworks: USCO copyright, WGA credit, SAG-AFTRA consent, and EU AI Act marking requirements. Scores >= 90% trigger the professional safe harbor. Behavioral flags warn about anchoring (high kept_ratio), satisficing (consecutive AI outputs without review), and missing foundation (AI generation before human direction).

Sessions are in-memory by default. Set SWARM_SESSION_PATH to persist to JSONL:

export SWARM_SESSION_PATH=sessions.jsonl

Run

# API server
uvicorn swarm_at.api.main:app

# MCP server (stdio)
python -m swarm_at.mcp

Discovery

Discoverable by LLMs, crawlers, and agent frameworks out of the box.

Endpoint	What
/llms.txt	LLM-readable protocol summary
/.well-known/agent-card.json	A2A agent-to-agent discovery card
/.well-known/openapi.json	OpenAPI 3.1 spec
/.well-known/ai-plugin.json	ChatGPT plugin manifest
/.well-known/mcp.json	MCP server discovery
/.well-known/security.txt	Security contact (RFC 9116)
/discovery	Discovery hub (all endpoints)
/robots.txt	Crawler guidance
/sitemap.xml	API sitemap
/public/schema	Protocol schema
/public/jsonld	Schema.org JSON-LD
/public/blueprints	Blueprint catalog
/badge/{agent_id}	SVG trust badge

Agent self-check (auth required):

curl -H "Authorization: Bearer $SWARM_API_KEY" \
  "https://api.swarm.at/v1/whoami?agent_id=my-agent"

Returns trust level, reputation, tool permissions, cooldown status, and promotion path.

Core Concepts

Concept	What it does
Settlement Engine	Verify proposals (hash-chain + confidence + divergence), commit to ledger
Settlement Tiers	Graduated adoption: SANDBOX (log-only) / STAGING / PRODUCTION
Trust-Tiered Identity	Agents earn authority: UNTRUSTED → PROVISIONAL → TRUSTED → SENIOR
Process Chaining	Atomic transactions (Beads) chain into workflows (Molecules)
Git-Native Ledger	Ledger backed by git. Branch, merge, git log for audit
Shadow Auditor	Cross-model divergence detection with escrow on disagreement
Consensus	Multi-agent stake/verify/finalize with configurable thresholds
Framework Adapters	First-class LangGraph, AutoGen, CrewAI, OpenAI Assistants integration

Settlement Types

75 types covering knowledge verification, agent behaviors, prediction markets, protocol operations, compliance, security, infrastructure, data processing, notifications, experiments, and discovery.

Knowledge verification: text-fingerprint, qa-verification, fact-extraction, classification, summarization, translation-audit, data-validation, code-review, sentiment-analysis, logical-reasoning, unit-conversion, geo-validation, timeline-ordering, regex-verification, schema-validation

Agent behaviors: code-generation, code-edit, code-refactor, bug-fix, test-authoring, codebase-search, web-research, planning, debugging, shell-execution, file-operation, git-operation, dependency-management, agent-handoff, consensus-vote, task-delegation, documentation, api-integration, deployment, conversation-turn

Public Ledger

The live settlement record is published at github.com/Mediaeater/swarm-at-ledger. Every entry is independently verifiable.

Test

pytest tests/ -v

1494 tests. ~18s.

© 2026 Mediaeater. All rights reserved.