agent-seal-xyz

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

agent-seal-xyz 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.

Quick start

import { seal } from '@agent-seal/sdk'

const agent = await seal({
  name: 'my-agent',
  architect: '[email protected]',
  capabilities: ['code-review'],
})
console.log(agent.sijil, agent.sealUrl)

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

Install

npm install @agent-seal/sdk

CLI

# Register
npx @agent-seal/sdk register --name my-agent --architect [email protected] --capabilities code-review,pr-analysis

# Check status
npx @agent-seal/sdk status <agent-id>

# Verify seal and card
npx @agent-seal/sdk verify <agent-id>

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

# Verify a warrant chain offline (no network)
npx @agent-seal/sdk warrant verify chain.json

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

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

API

seal(options)

Registers an agent and returns an AgentRegistration object.

import { seal } from '@agent-seal/sdk'

const agent = await seal({
  name: 'my-agent',
  architect: '[email protected]',
  capabilities: ['code-review', 'pr-analysis'],
  model: 'claude-sonnet-4-6',      // optional
  privateKey: process.env.AGENT_KEY, // optional — re-use an existing identity
})

| Property | Type | Description | |---|---|---| | agent.sijil | number \| null | Sijil number in the registry | | agent.sealUrl | string | URL to the agent's SVG seal | | agent.badgeUrl | string | URL to the embeddable badge | | agent.verifyUrl | string | URL to verify the seal | | agent.agentId | string | UUID in the registry | | agent.publicKey | string | Hex-encoded Ed25519 public key | | agent.manifestHash | string | SHA-256 hash of the covenant |

register(options) / status(agentId) / verify(agentId)

Lower-level named exports for direct control.

attest(options) — 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.

import { attest } from '@agent-seal/sdk'

const result = await attest({ name: 'my-agent' })
console.log(result.driftStatus) // "healthy" | "authorized-evolution" | "unauthorized-drift"
console.log(result.health)      // "fresh" | "drifted" | ...

Options: { agentId?, name?, covenantPath?, privateKey?, registryUrl? } — one of agentId, name, or covenantPath 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.

import {
  issueWarrant, assembleChain, verifyChain,
  enforceAction, enforceAndReceipt, verifyReceipt,
} from '@agent-seal/sdk'

// 1. A keeper delegates a scoped, time-boxed warrant to an agent
const { warrant } = issueWarrant({
  issuer:  { id: 'keeper:acme', type: 'keeper', publicKey: keeperPub },
  subject: { id: 'agent:seal-1', type: 'agent', publicKey: agentPub },
  scope:   { capabilities: ['payments.send'], resources: ['acct:acme/*'] },
  notAfter: new Date(Date.now() + 3600_000).toISOString(),
}, keeperPrivateKey)

const chain = assembleChain([warrant])
verifyChain(chain).valid // → true

// 2. Gate an action *before* it runs
const action = { capability: 'payments.send', resource: 'acct:acme/checking' }
const decision = enforceAction(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
const { receipt } = enforceAndReceipt(chain, action, {
  receipt: { signingKey: enforcerPrivateKey, publicKey: enforcerPub, enforcerId: 'gw:1' },
})
verifyReceipt(receipt, { trustedKeys: [enforcerPub] }).valid // → true

enforceAction returns a structured EnforceDecision (allowed, code, reason, checks, effectiveScope, remainingBudget). 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.

Error handling

import { seal, AgentSealError, RateLimitError } from '@agent-seal/sdk'

try {
  const agent = await seal({ name: 'my-agent', architect: '[email protected]' })
} catch (err) {
  if (err instanceof RateLimitError) {
    console.error(`Rate limited. Retry in ${err.retryAfter}s.`)
  } else if (err instanceof AgentSealError) {
    console.error(`Registration failed: ${err.message}`)
  }
}

Key management

On first use, agent-seal-xyz 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 identity across environments (e.g., CI), pass privateKey as a hex string.

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.

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