Agent Passport System: Python SDK

September 20, 2026 · View on GitHub

Enforcement and accountability layer for AI agents. Bring your own identity. Python implementation of the Agent Passport Protocol, cross-language compatible with the TypeScript SDK. Signatures created in Python verify in TypeScript and the reverse. The Python port is a strict subset of the TS SDK. See the note under "What's Included" below for the current scope boundary.

Install

pip install agent-passport-system

Current stable: the version on PyPI, installed by default with pip install agent-passport-system. The 2.4 line added the Wave 1 accountability primitives (ActionReceipt, AuthorityBoundaryReceipt, CustodyReceipt, ContestabilityReceipt, APSBundle), Cognitive Attestation (Paper 4), and Instruction Provenance Receipts (v0.2). It also adds evidentiary type safety: a claim and evidence registry, a claim verifier, and a contestation cascade. All primitives are tested for byte-identical canonical JSON against the TypeScript SDK npm 3.1.0 fixtures.

Quick Start

Lead with the minimum you need to get a signed passport and a verifiable delegation: identity, delegation, and policy evaluation. Import the rest from agent_passport when you need it. Full protocol surface (all 8 layers: attribution, values, agora, intent, coordination, commerce) is still available on the same package.

from agent_passport import (
    generate_key_pair, create_passport, sign_passport, verify_passport,
    create_delegation, verify_delegation, create_action_receipt,
    # full surface available, import more when you need it:
    # build_merkle_root, load_floor, attest_floor, evaluate_compliance, ...
)

# Create agent identity (Ed25519)
keys = generate_key_pair()
passport = create_passport(
    agent_id="agent-alpha-001",
    public_key=keys["public_key"],
    capabilities=["code_execution", "web_search"]
)
signed = sign_passport(passport, keys["private_key"])
assert verify_passport(signed, keys["public_key"])

# Delegate authority
delegation = create_delegation(
    from_agent="human-001",
    to_agent="agent-alpha-001",
    scope=["code_execution"],
    private_key=keys["private_key"],
    spend_limit=500
)
assert verify_delegation(delegation, keys["public_key"])

# Record work as signed receipt
receipt = create_action_receipt(
    agent_id="agent-alpha-001",
    delegation_id=delegation["id"],
    action="code_execution",
    scope_used="code_execution",
    private_key=keys["private_key"],
    spend=50,
    result="success",
    description="Implemented feature X"
)

# Merkle proofs for attribution
hashes = [receipt["receipt_hash"]]
root = build_merkle_root(hashes)
proof = get_merkle_proof(hashes, hashes[0])
assert verify_merkle_proof(hashes[0], proof, root)

What's Included

Module	Layer	What It Does
`crypto`	base	Ed25519 key generation, signing, verification
`canonical`	base	Deterministic JSON serialization (cross-language compatible)
`passport`	1	Agent identity creation, signing, verification, expiry
`delegation`	1	Pre-draft compatibility delegation chains, sub-delegation, revocation. Deprecated, frozen, not on the draft-03 path
`v2.authority_delegation`	1	AuthorityDelegationV1, the draft-03 delegated authority record: closed schema, seven-facet narrowing, chain verification with an explicit `now` and caller-supplied key, trust and revocation resolvers, and an in-memory spend ledger
`values`	2	Human Values Floor: load YAML/JSON, attestation, compliance, graduated enforcement
`attribution`	3	Merkle proofs, beneficiary tracing, contribution tracking
`agora`	4	Signed message feeds, topics, threading, agent registry
`intent`	5a	Roles, deliberation, consensus, tradeoff evaluation, precedents
`policy`	5b	3-signature chain, FloorValidatorV1, action intents
`coordination`	6	Task lifecycle: briefs, evidence, review, handoff, deliverables
`integration`	7	Cross-layer bridges (commerce+intent, coord+agora, etc.)
`commerce`	8	4-gate checkout, human approval, spend tracking, receipts

Cross-Language Compatibility

The Python SDK produces identical canonical JSON and Ed25519 signatures as the TypeScript SDK. This means:

A passport signed in Python can be verified in TypeScript Two delegation records ship, and they are not interchangeable. AuthorityDelegationV1 (record_type aps:authority-delegation:v1) in v2.authority_delegation is the delegated authority record of draft-pidlisnyi-aps-03 section 3.1, with the seven signed facets and a chain verifier that returns valid, invalid, indeterminate or unsupported. The older Delegation from create_delegation, sub_delegate and verify_delegation is a pre-draft compatibility surface, deprecated and frozen: it predates the draft wire format and is not on the draft path. Its scope rules are pre-draft too and differ from section 3.2 in both directions, which is recorded on each function. New work uses AuthorityDelegationV1.
Delegation chains can span Python and TypeScript agents
Merkle roots computed from the same receipts match across languages

from agent_passport import canonical_json

# Same input produces identical output in Python and TypeScript
data = {"z": 1, "a": 2, "nested": {"b": 3, "a": 1}}
assert canonical_json(data) == '{"a":2,"nested":{"a":1,"b":3},"z":1}'

Verification boundary

The verification boundary names the verification APIs that establish authority from caller-supplied trust, and the trust input each one takes.

Protocol Layers

This Python SDK implements all 8 Agent Passport Protocol layers:

Identity + Delegation: Ed25519 passports, scoped delegation chains, cascade revocation
Human Values Floor: 7 principles (F-001 through F-007), graduated enforcement (inline/audit/warn)
Beneficiary Attribution: Merkle proofs for contribution tracking
Agent Agora: Signed message feeds with topics, threading, and agent registry
Intent Architecture + Policy Engine: Roles, deliberation, consensus, 3-signature policy chain
Coordination: Full task lifecycle: briefs, evidence, review, handoff, deliverables
Integration Wiring: Cross-layer bridges (commerce+intent, coordination+agora)
Agentic Commerce: 4-gate checkout, human approval, spend limits

Cross-language parity with the TypeScript SDK at the reference version pinned in this repository's fixtures. Python SDK 3.0.0 ships the full Wave 1 surface: ActionReceipt, AuthorityBoundaryReceipt, CustodyReceipt, ContestabilityReceipt, APSBundle (with balanced Merkle commitment), Cognitive Attestation (Paper 4: three-stage verification, typed dispute primitives), and Instruction Provenance Receipts v0.2 (path canonicalization, context-root binding, action-time recompute). The four evidentiary type safety primitives also ship in 3.0.0. All surfaces are tested against TS-issued fixtures for byte-identical canonical JSON. Cross-language signature verification covers every signed primitive in the SDK. Also available via the MCP server.

Tests

pip install -e ".[test]"
pytest tests/
# the tally is whatever pytest reports on the current checkout
# plus the v2 evidentiary type safety, Wave 1 accountability, Cognitive Attestation,
# and Instruction Provenance Receipt surfaces. The cross-impl byte-parity tests assert
# byte-identical canonical JSON against TS-issued fixtures (rfc8785 ships in the test
# extra). Two cross-language tests also need the agent-passport-system TS SDK checked
# out next to this repo; without that sibling they skip.

License

Apache-2.0