swarm-at-sdk 0.5.0
Git-native settlement protocol for AI agent workflows
Requires Python: >=3.10
Keywords: agent, ai, coordination, ledger, settlement, swarm

# swarm.at

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

<!-- mcp-name: io.github.Mediaeater/swarm-at -->

## Install

```bash
pip install swarm-at-sdk
```

With framework adapters:

```bash
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:

```python
from swarm_at import settle

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

Full control with `SettlementContext`:

```python
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:

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

```python
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. |

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

## Framework Adapters

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

**LangGraph:**
```python
from swarm_at.adapters.langgraph import SwarmNodeWrapper

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

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

**AutoGen:**
```python
from swarm_at.adapters.autogen import SwarmReplyCallback

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

**CrewAI:**
```python
from swarm_at.adapters.crewai import SwarmTaskCallback

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

**OpenAI Assistants:**
```python
from swarm_at.adapters.openai_assistants import SwarmRunHandler

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

## Run

```bash
# 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`](https://api.swarm.at/llms.txt) | LLM-readable protocol summary |
| [`/.well-known/agent-card.json`](https://api.swarm.at/.well-known/agent-card.json) | A2A agent-to-agent discovery card |
| [`/.well-known/openapi.json`](https://api.swarm.at/.well-known/openapi.json) | OpenAPI 3.1 spec |
| [`/robots.txt`](https://api.swarm.at/robots.txt) | Crawler guidance |
| [`/public/schema`](https://api.swarm.at/public/schema) | Protocol schema (JSON schemas, tiers, guarantees) |
| [`/public/blueprints`](https://api.swarm.at/public/blueprints) | Blueprint catalog |

Agent self-check (auth required):

```bash
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.

<details>
<summary><h2>Core Concepts</h2></summary>

| 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 |

</details>

<details>
<summary><h2>Settlement Types</h2></summary>

35 types covering knowledge verification and agent behaviors.

**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

</details>

## Public Ledger

The live settlement record is published at [github.com/Mediaeater/swarm-at-ledger](https://github.com/Mediaeater/swarm-at-ledger). Every entry is independently verifiable.

## Test

```bash
pytest tests/ -v
```

605 tests. ~11s.

---

© 2026 Mediaeater. All rights reserved.