Swarm Integration Guide

This is a deep integration manual for implementing MachineID into Swarm-style agent orchestration. It is intentionally extensive so it can serve as a single reference for: (1) designing enforceable validation boundaries in multi-agent handoff flows, (2) modeling devices correctly across execution surfaces, and (3) applying remote stop control across tool-heavy and side-effect-heavy runs.

Everything reduces to one invariant:

Register. Validate. Work.

If validation fails, work does not begin.

In Swarm, “work begins” at recognizable boundaries: starting a run, executing a tool function, performing a side effect, and transferring control during a handoff.

The fastest way to verify the control plane is to add a single hard gate to your runner, then revoke that device in the dashboard and confirm execution stops on the next validate.

Swarm-style systems center on a small set of primitives:

• Agents that produce messages and call tools
• Tools (functions) where external requests and side effects occur
• Handoffs where control transfers between agents
• Loops / re-entry where execution continues across steps

Handoffs are where responsibility moves from one agent to another. Treat that transfer as an enforcement point.

Tools are where costs and external effects begin. If you add only one in-run boundary beyond run entry, make it a tool-call gate.

Many Swarm-style runs iterate: plan → call tools → update state → handoff → continue. If you validate only once at startup, a run can continue deep into a loop even after revoke/disable.

Streaming improves responsiveness. It is not an enforcement boundary. A streamed run can still incur tool costs and side effects. Put validation boundaries where costs and effects occur — tool execution, handoffs, and side effects — not where output is displayed.

The Python SDK is the simplest integration surface: machineid-io/python-sdk.

pip install machineid-io

import os
from machineid import MachineID

m = MachineID.from_env()

device_id = os.getenv("MACHINEID_DEVICE_ID", "swarm:dev:runner:01")

m.register(device_id)

decision = m.validate(device_id)
if not decision["allowed"]:
    print("Execution denied:", decision.get("code"), decision.get("request_id"))
    raise SystemExit(1)

If you want minimal dependencies, call the canonical endpoints directly. Send your org key via x-org-key and a deterministic deviceId.

POST https://machineid.io/api/v1/devices/register
Headers:
  x-org-key: org_...
Body:
  {"deviceId":"swarm:prod:runner:01"}

POST https://machineid.io/api/v1/devices/validate
Headers:
  x-org-key: org_...
Body:
  {"deviceId":"swarm:prod:runner:01"}

Wrappers let you add enforcement without rewriting your orchestration logic. The goal is consistent: validate immediately before the boundary where work begins or side effects commit.

def must_be_allowed(m, device_id, boundary):
    d = m.validate(device_id)
    if not d["allowed"]:
        print(f"Denied at {boundary}:", d.get("code"), d.get("request_id"))
        raise SystemExit(1)
    return d

def gated_tool_call(tool_fn, *args, **kwargs):
    must_be_allowed(m, device_id, "before_tool_call")
    return tool_fn(*args, **kwargs)

def gated_handoff(next_agent_name):
    must_be_allowed(m, device_id, f"before_handoff:{next_agent_name}")
    # perform handoff here

def commit_side_effect():
    must_be_allowed(m, device_id, "before_side_effect")
    perform_irreversible_action()

Device IDs should be stable enough to audit, but specific enough to revoke. A practical pattern:

swarm:{env}:{role}:{instance}

Examples that map cleanly to Swarm execution surfaces:

• swarm:dev:runner:01 — your orchestrator process
• swarm:prod:agent-planner:01 — planner role (if you model per-agent roles)
• swarm:prod:tool-runner:03 — tool-heavy surface
• swarm:prod:event-consumer:06 — event-triggered runs
• swarm:prod:cron-nightly:01 — scheduled run identity

Treat validation like a safety-critical call. Use short timeouts and fail closed. If permission cannot be confirmed, work should not proceed.

The free tier is enough to prove control end-to-end. The objective is to confirm that revoke/disable stops execution at predictable checkpoints.

This tier supports multiple concurrent runners, consumers, and tool-heavy surfaces while keeping identity manageable.

At this scale, execution surfaces multiply under load: autoscaling, event storms, retries, and fan-out workflows. The dominant requirement is consistent enforcement across replicas and over time.

Near the upper end of standard caps, the dominant failure mode is systemic multiplication: retries, recursive workflows, and many simultaneous execution surfaces.

If you need device limits beyond standard tiers, MachineID supports custom device limits. Your implementation pattern does not change: identity per execution surface and explicit validation boundaries.

MachineID provides a console at machineid.io/dashboard. The console exists outside your runtime so control does not depend on the process cooperating.

In addition to revoking individual devices, MachineID supports an org-wide disable control. This changes validate outcomes across the org (allowed becomes false).

Remote controls become effective at the next validate. Stop latency is determined by your boundary placement: if you only validate at run entry, revocation will not stop a long run already deep in tool loops.

These patterns defeat the purpose of external enforcement:

• Proceed anyway on validation timeout or error
• Continue for a fixed grace window while enforcement is unavailable
• Fallback to internal flags as an alternate authority path
• Validate only at run entry for long-running, tool-heavy runs

The prompts below are designed to produce practical integration plans with minimal guesswork. Replace bracketed placeholders and paste into your LLM of choice.

I have a Python Swarm-style orchestrator (agents + tools + handoffs). I want hard enforcement using MachineID.

Context:
- My org key: [PASTE ORG KEY]
- Base URL: https://machineid.io
- Device ID pattern: swarm:{env}:{role}:{instance}
- Fail-closed policy, short timeout (1–3s)
- Validation boundaries required:
  1) Run entry (register + validate, fail closed)
  2) Before every tool execution (highest leverage)
  3) Before every handoff (control transfer)
  4) Before irreversible side effects (writes, sends, payments)
  5) At loop re-entry points (high-cost cycles)

Please provide:
1) Exact files/locations to change
2) Copy/paste code blocks using the MachineID Python SDK (pip install machineid-io)
3) A test plan:
   - revoke a device from dashboard
   - restore it
   - use org-wide disable
   - verify stops occur at the next validate boundary

Help me model MachineID devices for my Swarm-style system.

Inputs:
- Agents: [list agent roles]
- Tools: [list tools, note which ones are high-risk side effects]
- Triggers: [API requests / cron / queue / event consumer]
- Expected scale: [3 / 25 / 250 / 1000]
- I need readable device IDs and surgical revoke control.

Output:
- A proposed device ID scheme
- A concrete list of device IDs for the target tier
- Where to validate (run entry / tools / handoffs / side effects / loop re-entry)
- A minimal runbook for revoke + org-wide disable

I have a Swarm-style run that loops and can call tools repeatedly.

Goal:
- Add MachineID validate boundaries inside the loop so I can stop it remotely.
- Fail closed on validation timeout or error.

Please provide:
- Exactly where to place validation calls
- A wrapper pattern that is hard to forget
- A test plan using dashboard revoke and org-wide disable

• Python SDK: github.com/machineid-io/python-sdk
• MachineID GitHub org: github.com/machineid-io
• Dashboard: machineid.io/dashboard
• Core enforcement guidance: Implementation Guide and Operational Guarantees

← Back to Docs