agent-seal-xyz 0.3.0

Give your AI agent a signed, verifiable identity in one line.

agent-seal

Give your AI agent a signed, verifiable identity in one line.

agent-seal registers your AI agent with the Agent Seal Registry — a court-grade, cryptographic identity system for autonomous agents. Keys are generated locally and never leave your machine; the registry only ever sees public keys and signatures.

Quick start

from agent_seal_xyz import seal

agent = seal(
    name="my-agent",
    architect="[e-mail]",
    capabilities=["code-review"],
)
print(agent.sijil, agent.seal_url)

That's it. Your agent now has a public, cryptographically verifiable identity.

Install

pip install agent-seal-xyz

CLI

# Register
agent-seal register --name my-agent --architect [e-mail] --capabilities code-review,pr-analysis

# Check status
agent-seal status <agent-id>

# Verify seal and card
agent-seal verify <agent-id>

# Attestation heartbeat — prove the agent is still the sealed agent
agent-seal attest --name my-agent --every 3600

# Check an action against a warrant *before* it runs (the gatekeeper)
agent-seal enforce --warrant chain.json --action "send payment from acct:acme/checking"

# Verify a signed decision receipt offline
agent-seal receipt verify receipt.json --trusted-key <hex>

API

seal(name, architect, capabilities=None, *, model="unknown", private_key=None)

Registers an agent and returns an AgentRegistration object.

Attribute	Type	Description
agent.sijil	int	Sijil number in the registry
agent.seal_url	str	URL to the agent's SVG seal
agent.badge_url	str	URL to the embeddable badge
agent.verify_url	str	URL to verify the seal
agent.agent_id	str	UUID in the registry
agent.public_key	str	Hex-encoded Ed25519 public key
agent.manifest_hash	str	SHA-256 hash of the covenant

AgentSealClient(registry_url="https://agent-seal.xyz")

Lower-level client with register(), status(), verify(), and attest() methods.

AgentSealClient.attest(...) — Drift Monitoring

Sends a signed agent:attest heartbeat carrying the DNA sequence recomputed from the covenant stored at registration (~/.agent-seal/covenants/). The registry compares it to the sealed baseline and reports drift.

from agent_seal_xyz import AgentSealClient

client = AgentSealClient()
result = client.attest(name="my-agent")
print(result["drift"]["decision"]["status"])   # healthy | authorized-evolution | unauthorized-drift
print(result["state"]["attestation"]["health"]) # fresh | drifted | ...

Keyword arguments: agent_id, name, covenant_path, private_key — one of the first three is required. Health is public at GET /v1/public/agents/{id}/status → attestation.health.

Warrant Chains, Runtime Enforcement & Decision Receipts

Beyond identity, the SDK ships an offline authority layer — power-of-attorney as code. A keeper issues a signed warrant delegating a scoped set of capabilities to an agent; the agent can attenuate (never widen) that scope down the chain. Every check is pure and offline — no network, no shared secret.

from agent_seal_xyz import (
    issue_warrant, verify_chain,
    enforce_action, enforce_and_receipt, verify_receipt,
)

# 1. A keeper delegates a scoped, time-boxed warrant to an agent
result = issue_warrant(
    issuer={"id": "keeper:acme", "type": "keeper", "publicKey": keeper_pub},
    subject={"id": "agent:seal-1", "type": "agent", "publicKey": agent_pub},
    scope={"capabilities": ["payments.send"], "resources": ["acct:acme/*"]},
    not_after=not_after_iso,
    issuer_private_key=keeper_private_key,
)
chain = result["chain"]
verify_chain(chain).valid  # -> True

# 2. Gate an action *before* it runs
action = {"capability": "payments.send", "resource": "acct:acme/checking"}
decision = enforce_action(chain, action)
decision.allowed  # -> True   (False + code 'resource-out-of-scope' if outside the grant)

# 3. Mint a non-repudiable, signed proof of the decision
decision, receipt = enforce_and_receipt(
    chain, action, signing_key=enforcer_private_key, enforcer_id="gw:1",
)
verify_receipt(receipt, trusted_keys=[enforcer_pub]).valid  # -> True

enforce_action returns an EnforceDecision with .allowed, .code, .reason, and a full per-gate audit trail in .checks. Warrants support capability + resource scoping, spend budgets, caveats, expiry, and revocation cascades. Decision receipts are Ed25519-signed and verify offline against a trusted-key set.

Key management

On first use, agent-seal generates an Ed25519 keypair and stores it at:

~/.agent-seal/keys/private.hex   (mode 0600)
~/.agent-seal/keys/public.hex    (mode 0600)

The private key never leaves your machine. To re-use an existing identity across environments (e.g., CI), pass private_key= as a hex string.

Error handling

from agent_seal_xyz import seal, AgentSealError, RateLimitError

try:
    agent = seal(name="my-agent", architect="[e-mail]")
except RateLimitError as e:
    print(f"Rate limited. Retry in {e.retry_after}s.")
except AgentSealError as e:
    print(f"Registration failed: {e}")

Rate-limited requests (HTTP 429) are retried automatically up to 3 times, respecting the Retry-After header.

What is Agent Seal?

Agent Seal is a public registry that gives AI agents cryptographic, human-accountable identities. Every registered agent receives a Sijil number, a signed covenant, and a public seal — verifiable by anyone at agent-seal.xyz/verifier.

Built for the EU AI Act era: immutable audit trail, liability anchors, and EU AI Act readiness evidence out of the box.

---

agent-seal.xyz · Verify an agent · Registry API