Rigging cheatsheet.

① Build a rig

from rigging.runtime import Rig
from rigging.identity import KeyPair, generate_keypair
from rigging.adapters import LocalPythonAdapter

planner_key = generate_keypair()
worker_key  = generate_keypair()

rig = Rig(name="my-system")
rig.register(planner, keypair=planner_key)
rig.register(worker,  keypair=worker_key)

② Delegate

result = await rig.call(
    caller=planner,
    callee_did=worker.did,
    capability="translate_pdf",
    input={"uri": "s3://docs/x.pdf",
           "target_language": "fr"},
    cost_budget=("usd", "0.50"),
    verifier=quality.did,
)

③ Inspect

trace = rig.finish()
trace.write("trace.json")

# CLI
rig trace inspect ./trace.json
rig trace inspect --highlight=blame

Typed errors you may get

• VerifierRejected — verifier signed a reject verdict.
• BudgetOverrun — callee exceeded the contract budget.
• BudgetExhausted — caller's parent budget already spent.
• ContractExpired — wall-clock past expires.
• ContractRejected — callee declined the proposal.
• CalleeUnreachable — DID not registered.
• VerifierUnreachable — verifier DID not registered.
• SignatureInvalid — JWS does not verify.
• CapabilityMismatch — capability or schema does not match the card.
• PolicyDenied — runtime policy refused.
• RecursionCapExceeded — contract or verifier nesting cap hit.

Span kinds in the trace

• rig.contract.propose — caller-signed contract sent to callee.
• rig.contract.accept — callee-signed acceptance.
• rig.contract.reject — callee declined (with reason).
• rig.contract.void — runtime voided (expired / overrun / unreachable / signature).
• rig.execute — callee ran the capability; output envelope attached.
• rig.verify — verifier sub-contract; verdict envelope attached.
• rig.cost.debit — ledger entry against the contract.

The six refusals

• routing against unsigned cards.
• contracts whose capabilities are undeclared.
• silent retries.
• attributing cost to anyone but the contract holder.
• admitting unverified output as verified.
• being a marketplace, scheduler, router, or harness.

CLI

rig identity create
rig identity show
rig identity verify card.json

rig run 01-two-agent-handoff
rig run 03-adversarial-subagent

rig trace inspect ./trace.json
rig bench
rig bench --full
rig spec validate docs/spec/...

Mental model

• Cards — who an agent is and what it claims.
• Contracts — what A asked B to do, signed.
• Blame — which envelope, walked backwards, caused the failure.
• The rig uses MCP and A2A; it does not replace them.
• The rig has no LLM-specific code in core. Provider concerns live in adapters.

When in doubt

• Always pass cost_budget. No exceptions.
• Always pass verifier in production.
• Refuse silent retries. If your code has except / retry around rig.call, that's an explicit retry contract — sign and trace it.
• If you find yourself importing cryptography outside rigging-identity, you missed a layer.