agent-action-capsule (reference library)

The reference implementation of the Agent Action Capsule profile: parse and seal a Capsule, and run the Class 1 verifier defined in the Internet-Draft (../spec/). Published to PyPI as agent-action-capsule. See RELEASING.md for the release workflow and PyPI Trusted Publisher setup.

The spec (../spec/) is the source of truth. Where the draft says MUST / MUST NOT, the code and tests enforce it, section by section.

Quickstart (30 seconds)

Install the payload-only core (stdlib only — zero required dependencies):

pip install agent-action-capsule        # from a checkout: cd python && pip install .

Verify a conformant capsule — point at a shipped positive vector:

$ agent-action-capsule verify ../vectors/capsule/pos-executed-confirmed/input.json
Agent Action Capsule — Class-1 payload verification: ../vectors/capsule/pos-executed-confirmed/input.json
  ok: True
  capsule_id (recomputed): 5b7c4ff1bcf4364e0dd8c8b65eddddbb1d6102f27bed3ad1a3595cba51d3502a
  derived: effect_mode=confirmed attestation_mode=self_attested ledger_mode=standalone
  findings: none
# exit code 0

Verify a failing capsule — the finding is self-explaining, with its §6 check number:

$ agent-action-capsule verify ../vectors/capsule/neg-confirmed-without-response/input.json
  ok: False
  ...
  findings:
    - [error] (check 3) confirmed_without_response: effect.status 'confirmed' requires a 64-hex response_digest (§5.2)
# exit code 1  (0 = ok, 1 = not ok, 2 = could not run / malformed input)

Add --json for the raw VerificationResult, or --store <dir-or-ledger-file> for store-level chain checks (supersedes / concurrent-supersedes / open-items).

The two layers

Verification is two layers, and this package is honest about which it does:

The current AAC Producer Envelope is separate from an RFC 9943 Signed Statement: it signs the raw 32-byte Capsule ID with exactly three protected headers and does not carry RFC 9943's required CWT claims. Install agent-action-capsule[envelope] and call verify_producer_envelope(capsule_id, envelope_bytes) to verify that profile. The function returns the authenticated public key; it does not decide whether the key is authorized for an operator or developer.

from agent_action_capsule.producer_envelope import verify_producer_envelope

To verify an Evidence Bundle's interval coverage and per-record membership (agent_action_capsule.bundle.verify_bundle), install the bundle extra. It adds the public CLL reference that checks the MMR proofs:

pip install 'agent-action-capsule[bundle]'

Without it those two claims fail closed as completeness_verifier_unavailable. That finding means this installation could not check the proofs. It does not mean the certificate is invalid.

verify_bundle(bundle, strict=True) adds the checks a verifier needs before it calls a Bundle VALID, and sets result.verdict to VALID, INCOMPLETE or INVALID:

• each record's producer signature (signatures), including vintage jcs-n records; an unsigned record is not shown unless you pass require_signature=True;
• the checkpoint, read only from its signed COSE form (checkpoint); without one, interval coverage and membership are not shown, so the Bundle is never VALID;
• producer-selected Bundles, the disclosures overlay as one claim, and whether every record names the checkpoint's key;
• witness receipts in checkpoint.witnesses (cll, rekor and scrapi bindings) under the keys of the witness_directory you pass, a parsed witnesses.json. Without one, no witness is trusted.

Strict mode needs agent-action-capsule[bundle,envelope]. vectors/bundle/strict/ states the rules.

build_evidence_bundle(source, root=..., interval_from=...) builds a Bundle from a ProofSource: the log's signed COSE checkpoint, its leaves, records by Capsule ID, and inclusion and range proofs. It holds no key, and it checks the result with verify_bundle(strict=True) before returning it, refusing anything that verifier calls INVALID. proof_source_from_cll(backend, records) makes a ProofSource from a CLL backend (scan_entries, load_cll) and a record store whose get(capsule_id) returns capsule and producer_envelope bytes.

• interval_from=N carries every record from seq N to the checkpoint tip, and none below N, with a range proof: the Bundle can read VALID. N=1 is the whole log.
• interval_from=None carries only the chosen records, each with its own inclusion proof, and states completeness.selection: "producer-selected": nothing is claimed about the records between them, so it reads INCOMPLETE.

interval_from has no default, so a caller never hands over the whole log by omission. A range over a leaf that is not a record, a carried record below N and a record past the checkpoint are refused by name. A missing citation or an unsigned record is stated, not refused, and reads INCOMPLETE. build_unproven_bundle(records, root=...) is the form with no log proof, for Capsules that belong to no log. build_evidence_bundle needs the bundle and envelope extras; build_unproven_bundle needs only envelope.

agent_action_capsule.settlement.verify_settlements(capsules, key_policy=..., wrapped_objects=...) derives the payment and delivery states of draft-mih-agent-settlement-records-00 from both parties' leg records. It passes every case in vectors/settlement/. It needs the envelope extra.

To answer an Evidence Request, call agent_action_capsule.evidence_request.answer(request_bytes, store=..., signer=...). It implements draft-mih-agent-evidence-request-00 and passes every case in vectors/evidence-request/: it parses the request (JSON, or deterministic CBOR with binding="cbor"), resolves the subject exactly, and returns an Artifact or a signed Refusal. Your store (an EvidenceStore) answers exact lookups, lists its coverage anchors and builds the artifact, so the responder works over any log. To send an Artifact in the interop profile's signed envelope, pass it to sign_envelope and encode the result in the request's binding. check_refusal and verify_refusal_offline check a signed refusal with no network. A requester reads a reply with parse_reply, authenticates an envelope with Envelope.verify_for(request_bytes, responder_key), and checks its Checkpointed Local Log material with check_cll_material; a responder encodes that material with encode_cll_inclusion_proof and encode_cll_consistency_proof. The module needs cryptography only to sign refusals and envelopes and to verify signatures, so install the envelope extra for that.

To verify both layers of a SCITT Signed Statement, install the optional extra and pass --transparent:

pip install 'agent-action-capsule[transparent]'     # adds the public scitt-cose verifier

agent-action-capsule verify --transparent statement.cose --issuer-key issuer_pub.pem [--log-key log_pub.pem --leaf-entry-hex <hex>]

For an RFC 9943 Capsule-ID registration statement, this command authenticates and prints the raw Capsule ID. Class-1 verification of the Capsule JSON is a separate operation. For a JSON-bearing Signed Statement, it also runs Class-1 verification over the authenticated payload.

  substrate (SCITT/COSE, via scitt-cose):
    signature_verified : True
    receipt_verified   : True
    attestation_tier   : anchored        # 'anchored' ONLY when a receipt actually verified (§3.2)
  payload (Agent Action Capsule, Class-1):
  ok: True

Without a verified receipt the substrate tier is self_attested, never anchored. The optional extra is public (scitt-cose, deps cbor2 + cryptography); the default install pulls nothing extra.

Build → verify (producer side)

../examples/build_and_verify.py is the smallest honest round trip: construct a capsule with the typed builders, seal() it (compute capsule_id), then verify() it — an executed action and a blocked one, in ~40 lines.

Capsule.seal() is this package's sealing boundary. Recording an agent's actions as they happen (default dispositions, chaining, framework adapters) is capsule-emit's job: use its capsule_emit.seal and its LangChain and CrewAI adapters (capsule_emit.adapters.langchain, capsule_emit.adapters.crewai). agent_action_capsule.emit() and agent_action_capsule.integrations (with the langchain and crewai extras), deprecated in 0.9.0, are removed in 0.10.0. The version constants (DEFAULT_SPEC_VERSION, ACCEPTED_SPEC_VERSIONS, ...) live in agent_action_capsule.versions and stay exported from the package root.

Conformance vectors

../vectors/capsule/ is the frozen conformance suite a second implementer runs against their own verifier: each input.json plus its spec-anchored expected.json (ok, the §6 check numbers + severities, the derived modes, the recomputed capsule_id). See ../spec/section-map.md for the spec section map.

What it implements

from agent_action_capsule import verify, Capsule, EffectRecord, Disposition, AssuranceBlock

capsule = Capsule(
    spec_version="draft-mih-scitt-agent-action-capsule-05", format_version="4",
    canonicalization_id="jcs",
    action_id="po-12345", action_type="decide", operator="ACME-CO", developer="agent@v1",
    timestamp="2026-06-13T00:00:00Z",
    effect=EffectRecord(status="confirmed", type="write_order",
                        response_digest="a"*64, effect_attestation="gate_executed"),
    assurance=AssuranceBlock(attestation_mode="self_attested", effect_mode="confirmed",
                             ledger_mode="standalone"),
    disposition=Disposition(decision="accept", approver="human", human_disposed=True,
                            verdict_class="executed"),
).seal()

result = verify(capsule)        # never throws
assert result.ok               # a single `ok` gates trust in every other field

Cross-record references (references[], §5.5.5)

chain is exclusively a Capsule's own same-stream parent. references cites everything else — a different producer's Capsule, or any other artifact this action targeted or responded to. Absent and an explicit empty array are semantically the same ("no such citation") but are distinct bytes, so they produce different capsule_id digests — pass references=() only when that distinction matters to a caller:

from agent_action_capsule import Capsule, ReferenceEntry, LogCoordinates

capsule = Capsule(
    spec_version="draft-mih-scitt-agent-action-capsule-05", format_version="4",
    canonicalization_id="jcs",
    action_id="deny-42", action_type="decide", operator="ACME-CO", developer="agent@v1",
    timestamp="2026-09-08T00:00:00Z",
    references=(
        ReferenceEntry(
            type="agent-action-capsule", digest_alg="SHA-256",
            digest="b" * 64,                    # the cited Capsule's capsule_id
            citation_purpose="responds_to",      # or "acted_on"; §12 citation_purpose registry
        ),
        ReferenceEntry(
            type="foreign-artifact", digest_alg="future-hash", digest="opaque-digest",
            log_coordinates=LogCoordinates(log_id="example-log", leaf_index=3, inclusion_proof={...}),
        ),
    ),
).seal()

capsule["references"]  # [{"type": ..., "digest_alg": ..., "digest": ..., "citation_purpose": ...}, {...}]

A references entry MUST NOT duplicate chain.parent_capsule_id — citing the producer's own same-stream parent is stated once, in chain, never redundantly in references (Capsule(...) raises InvariantError if it does). Only the agent-action-capsule/SHA-256 self-identity context constrains digest to 64-lowercase-hex; every other type/digest_alg combination is CPB's to define and stays open. log_coordinates, when present, is an upgrade (not a second identity) and its inclusion_proof is never independently verified by Class 1.

Scope boundary (deliberate)

Does — the Class 1 agent-profile surface (§6), performable from the Capsule's own bytes plus the registry contents (and, for chain checks, the producer's store of Capsules).

Does NOT —

• Substrate verification. The COSE_Sign1 signature, registration, and the Receipt's inclusion proof are the SCITT/COSE substrate's, by reference (scitt-cose). This package never derives anchored; a claimed anchored mode is reported as an unverifiable overclaim (§5.3).
• Class 2 / manifest-aware verification (§8.2). Constraint Records are represented as data (§8.1) but no manifest is fetched and no evidence-schema check is performed.

Develop / test

cd python
pip install -e ".[dev]"
python -m pytest -q        # positive + negative (MUST-reject) suite
python -m ruff check .

The test suite is the conformance contract: every MUST / MUST NOT in the implemented sections has a positive and a negative case, and the frozen byte-level vectors under ../vectors/capsule/ are replayed through verify() / verify_store(). The two-layer (--transparent) tests run only when the optional [transparent] extra is installed, and skip cleanly otherwise.