Technical documentation.

Verify a bundle

Verification is six checks, seven with a pinned issuer key. Without a pinned key, a PASS proves integrity: every receipt signature verifies, the hash chain is unbroken, the Merkle proofs check out, and the signed checkpoint anchors the recomputed root. It does not prove who issued the bundle. Pinning the issuer key adds the seventh check, provenance: the bundle was signed by the key you expected.

CLI (Node 18+)

# fetch the signed sample bundle and verify it (integrity)
curl -sO https://attestedintelligence.com/sample-bundle.json
npx --yes @attested-intelligence/aga-verify sample-bundle.json

# pin the issuing key (provenance): the sample is signed by the demo gateway
npx --yes @attested-intelligence/aga-verify sample-bundle.json \
  --pubkey b900a315c50d9516c4efcb7a2300c25c602855eac8aa3b5a9d0939234d738ebe

The first run reports VERIFIED with an integrity-only note; the pinned run adds the gateway_key_match check and reports provenance verified.

Browser

Drag the same file into the in-browser verifier. Paste the gateway key into the pin field to check provenance; leave it blank for an integrity-only verdict. Everything runs client-side.

Python

pip install aga-governance
python -m aga verify sample-bundle.json
python -m aga verify sample-bundle.json --pubkey <64-hex-key>

Single dependency: PyNaCl (Ed25519 signatures). Python 3.9+. The published Python CLI reports the integrity checks and exits 0 on PASSED; pass --pubkey with the expected 64-hex gateway key to add the provenance check, matching the aga-verify CLI and the browser verifier. Verification is offline in all three paths: no network, certificates, or external services required.

Pin a gateway key

Get the expected key out of band from the gateway operator: a running gateway reports its public key through the get_server_info MCP tool. Do not read the expected key out of the bundle you are checking; that restates the bundle's own claim instead of testing it.

By default the gateway signs with an ephemeral key that rotates on every restart, so a pinned key stops matching after a restart. Persist one stable seed instead:

# generate a 64-hex Ed25519 seed once (32 random bytes)
node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"

Provide it via the AGA_GATEWAY_KEY environment variable, or AGA_GATEWAY_KEY_FILE with a path to the seed file. In Claude Desktop, add an env block:

{
  "mcpServers": {
    "aga": {
      "command": "npx",
      "args": ["-y", "@attested-intelligence/aga-mcp-server"],
      "env": { "AGA_GATEWAY_KEY": "<your-64-hex-seed>" }
    }
  }
}

Keep the seed secret and out of version control. With a stable key set, get_server_info reports the same public key across restarts, and that is the key relying parties pin.

Integrate the MCP server

The gateway installs from npm and runs as an MCP server. Add it to claude_desktop_config.json and restart Claude Desktop:

{
  "mcpServers": {
    "aga": {
      "command": "npx",
      "args": ["-y", "@attested-intelligence/aga-mcp-server"]
    }
  }
}

The gateway exposes 15 MCP tools across identity (get_server_info, get_portal_state), lifecycle, measurement and decision, evidence (generate_evidence_bundle, verify_bundle_offline), privacy, delegation, and audit. Claude can then seal artifacts, measure integrity, and produce evidence bundles through natural language. Tested with Node 20+. Set the signing key first (previous guide) so bundle provenance stays pinnable.

Export evidence

An export packages the signed receipts, their Merkle inclusion proofs, and the signed checkpoint into one portable JSON file. From the Python SDK, record decisions in a session and write the bundle to disk:

import json
from aga import AgentSession

with AgentSession(gateway_id="my-gateway") as session:
    session.record_tool_call(
        tool_name="read_file",
        decision="PERMITTED",
        reason="path within allowed prefix",
        request_id="req-001",
        arguments={"path": "/data/report.csv"},
    )
    session.record_tool_call(
        tool_name="write_file",
        decision="DENIED",
        reason="path outside allowed prefix",
        request_id="req-002",
        arguments={"path": "/etc/shadow"},
    )
    bundle = session.export_bundle()
    result = session.verify()
    print(f"Valid: {result['overall_valid']}")  # True
    with open("evidence-bundle.json", "w") as f:
        json.dump(bundle, f)

python session.py
python -m aga verify evidence-bundle.json

Through the MCP server, ask Claude for an evidence bundle and the generate_evidence_bundle tool returns the same format; verify_bundle_offline checks it without leaving the machine. A bundle in this format verifies with any of the verifiers in the first guide, and with the reference verifier shipped in the conformance corpus download.