AGA Python SDK

Cryptographic governance receipts for AI agent tool calls. This SDK emits the canonical SEP evidence bundle, the same offline-verifiable artifact the AGA gateway produces, so a governance decision sealed in Python re-derives, byte-for-byte, under the reference verifiers in three languages (JavaScript, Go, Python): three separate implementations, runnable offline without the producer.

PyPI distribution: aga-governance.

What the SDK emits

Each governed tool call becomes a signed, 15-field governance receipt. Receipts hash-link into an append-only chain, the chain's leaves bind into a Merkle root, and a gateway-signed checkpoint binds the root, leaf count, and chain head so truncation is detectable. The bundle uses standard primitives only:

• Ed25519 receipt signatures (RFC 8032).
• SHA-256 for hash chaining, Merkle trees, and leaf computation.
• JCS-lineage canonicalization: deterministic, byte-compatible with the reference verifier and with the TypeScript and Go implementations.
• A no-prefix binary Merkle tree with a mandatory signed checkpoint (the construction is specified in aga-receipt-spec/, vendored in the public aga-mcp-server repository).

Install

pip install aga-governance

Install aga-governance (the distribution name). The unrelated PyPI project named aga is a different package; installing it will not give you this SDK.

Quick Start

from aga import AgentSession

SEED = bytes.fromhex("cc" * 32)  # 32-byte signing seed (provision securely)

with AgentSession(gateway_id="my-gateway", signing_key_seed=SEED) as session:
    session.record_tool_call(
        tool_name="read_file",
        decision="PERMITTED",
        reason="allowed by policy",
        request_id="req-001",
    )
    bundle = session.export_bundle()      # a canonical SEP evidence bundle (dict)
    result = session.verify()
    assert result["overall_valid"]

Verifying a bundle

Verification is producer-independent: any conformant verifier reaches the same verdict on the same bundle, offline. Start with the Python-native paths this package ships.

CLI:

aga verify bundle.json          # human-readable, check-by-check output
aga verify bundle.json --json   # the full result object as JSON

Bundle: bundle.json
Algorithm: Ed25519-SHA256-JCS
Receipts checked: 2
  Algorithm valid:     True
  Signatures valid:    True
  Chain integrity:     True
  Merkle proofs:       True
  Bundle consistent:   True
  Checkpoint valid:    True
  Envelope consistent: True

Verification: PASSED (integrity only: issuer not verified; pass --pubkey to verify provenance)

API:

import aga

result = aga.verify_bundle_file("bundle.json")
assert result["overall_valid"]

Pin the gateway public key to also prove who issued the bundle; without a pinned key you get an integrity-only result:

aga verify bundle.json --pubkey <64-hex-gateway-public-key>
# -> Verification: PASSED (provenance verified)

result = aga.verify_bundle_file("bundle.json", expected_public_key="<64-hex>")

Cross-checking with the other reference verifiers

A Python-produced bundle verifies under the reference verifiers in three languages (JavaScript, Go, and Python): three separate implementations, runnable offline without the producer. The SDK's canonicalization and leaf computation are pinned to the same cross-language conformance vectors, so a bundle sealed here re-derives byte-for-byte under each. This SDK's verifier enforces the same strict conformance rules (exact-key schema, canonical timestamps and ordering, envelope consistency, strict-hex Merkle proofs, and a mandatory signed checkpoint), so it agrees with them verdict-for-verdict rather than being a looser convenience check.

Check-name mapping vs the JS reference verifier

The two stacks decompose the same seven-check verification differently. Overall verdicts and exit codes agree on every conformance-corpus case (re-proven 2026-07-01: 10/10 cells across pristine/tampered bundles with unpinned, correct, and wrong keys); the sub-check that reports a given tamper can differ:

Known decomposition difference: the JS reference recomputes every Merkle leaf from full receipt content, so a receipt-signature tamper also fails its merkle_and_bijection; this SDK surfaces the same tamper in receipt_signatures_valid, chain_integrity_valid, and bundle_consistent while merkle_proofs_valid can remain true. Neither is looser: the bundle fails in both stacks, exit 1. A malformed --pubkey pin is a usage error (exit 2) here, as it is in the JS reference and in aga-verify 2.2.0 and later.

# JavaScript reference verifier, vendored as aga-receipt-spec/ in the public
# repository https://github.com/attestedintelligence/aga-mcp-server:
node aga-receipt-spec/verify/verify-sep.mjs bundle.json --pubkey <gateway-public-key>

Scope: what a verified bundle proves

A verified bundle proves the integrity of the receipts present: each is authentic, correctly ordered, Merkle-included, and (when a key is pinned) provenance-bound. It does not prove the policy was correct, and it does not prove non-omission: completeness of capture is bounded by the tamper-evidence of the interception point, which is outside the bundle. Arguments are committed by SHA-256 hash (arguments_hash), and verifying a bundle never requires disclosing argument contents. We prove the record, not that the policy was correct.

Source and provenance

The SDK's source repository is private. The sdist carries the complete library source (src/aga) under Apache-2.0. Each release is built and uploaded by PyPI trusted publishing, and its PEP 740 attestation names the repository and the workflow that built it. The format specification, the reference verifiers and the public conformance corpus are in aga-mcp-server.

Tests

The automated suite (python -m pytest) runs in the publishing workflow before every release. The published wheel and sdist ship the library only; the tests are not part of the installed package.

License

Apache-2.0. Patent Pending.