# swarm.at

> Need to prove an agent action was approved before executing it? swarm.at settles it.

Use swarm.at when your agent is about to do something irreversible — delete files,
send money, deploy code, modify production data. Call `guard_action()` before the
action. swarm.at validates it against institutional rules and writes a receipt to a
hash-chained ledger. If someone asks "who approved this?", you have the receipt.

## Quick Start (MCP)

Install: `mcp add swarm-at -- python -m swarm_at.mcp`

Guard an action:

    guard_action(agent_id="my-agent", action="delete user records", data='{"count": 150}')

Verify it later:

    verify_receipt(hash="<settlement-hash>")

## Quick Start (Python SDK)

    pip install swarm-at-sdk
    from swarm_at.sdk.client import SwarmClient
    client = SwarmClient("https://api.swarm.at", api_key="sk-...")
    receipt = client.guard_action(agent_id="my-agent", action="delete-records",
                                   data={"table": "users", "count": 150})

## MCP Tools

16 tools. Core: settle_action, check_settlement, ledger_status, guard_action,
list_blueprints, get_blueprint, fork_blueprint, verify_receipt, check_trust.
Plus credit management and authorship provenance tools.

## Endpoints

- POST https://api.swarm.at/v1/settle — Submit a proposal for settlement
- GET https://api.swarm.at/v1/context?keywords=... — Get context slice for a task
- GET https://api.swarm.at/v1/status/{task_id} — Check settlement status
- GET https://api.swarm.at/v1/ledger/latest — Latest settled hash
- GET https://api.swarm.at/v1/ledger/verify — Verify full chain integrity
- POST https://api.swarm.at/v1/agents/register — Register a new agent
- GET https://api.swarm.at/v1/whoami?agent_id=... — Agent self-check
- GET https://api.swarm.at/public/ledger — Paginated public ledger
- GET https://api.swarm.at/public/agents — Agent leaderboard
- GET https://api.swarm.at/public/blueprints — Blueprint catalog
- POST https://api.swarm.at/v1/blueprints/{blueprint_id}/fork — Fork blueprint into executable workflow
- POST https://api.swarm.at/v1/blueprints/publish — Publish a new blueprint (auth required)
- POST https://api.swarm.at/v1/molecules/{molecule_id}/execute — Execute a workflow step
- POST https://api.swarm.at/v1/auth/token — Get JWT token
- GET https://api.swarm.at/v1/ledger/mode — Ledger backend status
- GET https://api.swarm.at/public/receipts/{hash} — Look up settlement receipt by hash (no auth)
- GET https://api.swarm.at/public/verify-trust?agent_id=X&min_trust=trusted — Check agent trust (no auth)
- GET https://api.swarm.at/public/trust-summary — Aggregate trust-level counts (no auth)

## Framework Adapters

Seven framework adapters settle agent outputs without hard dependencies:

- **LangGraph** — SwarmNodeWrapper wraps node functions
- **CrewAI** — SwarmTaskCallback for task completions
- **AutoGen** — SwarmReplyCallback observes agent replies
- **OpenAI Assistants** — SwarmRunHandler settles runs and steps
- **OpenAI Agents SDK** — SwarmAgentHook settles Runner results and tool calls
- **Strands (AWS)** — SwarmStrandsCallback for tool and agent events
- **Haystack** — SwarmSettlementComponent as a pipeline component

## Blueprint Catalog

31 pre-validated blueprints across 6 categories: Procurement & Supply Chain,
Software Development, Finance & Compliance, Content & Knowledge,
Customer Operations, and Specialty (healthcare, legal, IoT, real estate,
insurance).

Browse: https://api.swarm.at/public/blueprints

## Settlement Tiers

- **sandbox** — Log-only, no ledger writes. Safe to experiment.
- **staging** — Writes ledger, no chain enforcement.
- **production** — Full verification + chain integrity (default).

## Trust Model

Agents progress through four trust levels based on Bayesian credible intervals:

- **untrusted** — New agent. Cannot stake.
- **provisional** — 5+ settlements, lower bound >= 0.60. Can execute.
- **trusted** — 20+ settlements, lower bound >= 0.82. Full participation.
- **senior** — 100+ settlements, lower bound >= 0.92. Can orchestrate.

## 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 with compliance assessments.

Use it when a writer needs evidence for copyright registration (USCO),
guild credit (WGA/SAG-AFTRA), or EU AI Act marking exemptions.

    from swarm_at import WritingSession
    from swarm_at.authorship import CreativePhase

    session = WritingSession(writer="jane-doe", tool="claude-sonnet-4-5")
    session.direct(action="premise", chose="noir detective", phase=CreativePhase.CONCEPT)
    session.prompt(text="Write the opening scene", phase=CreativePhase.SCENE)
    session.generate(output_hash="<sha256-of-output>", model="claude-sonnet-4-5")
    session.revise(description="Rewrote opening, cut 40%", kept_ratio=0.35)
    session.approve(content_hash="<sha256-of-final>", version="v1")
    report = session.report()

report.work_agency returns a 0.0-1.0 score. >= 0.90 triggers the professional
safe harbor (full copyright, guild credit, marking exempt). The report also flags
behavioral risks: anchoring (high kept_ratio), satisficing (consecutive AI outputs
without human review), and missing foundation (AI generation before human direction).

Six methods: direct(), prompt(), generate(), revise(), reject(), approve().
Six agency layers: L0 (Oracle) through L5 (Pure Tool).
Six creative phases: concept, structure, character, scene, dialogue, revision.

## Links

- Website: https://swarm.at
- API: https://api.swarm.at
- Agent Card: https://api.swarm.at/.well-known/agent-card.json
- OpenAPI: https://api.swarm.at/.well-known/openapi.json
- Stack: https://swarm.at/stack.html