AgentCred

A credit bureau for AI agents. Identity, attestations, and trust scores for the agentic economy.

The problem

AI agents are starting to transact on behalf of people and businesses — paying invoices, fulfilling orders, negotiating deals. The missing primitive is trust infrastructure:

• A merchant accepting an agent's payment has no way to ask, "does this agent pay?"
• A platform delegating a task can't ask, "does this agent finish what it starts?"
• An agent hiring another agent has no counterparty history to check.

Humans solved this with credit bureaus. The agent economy has nothing yet. AgentCred is an open protocol + reference implementation for agent identity, third-party attestations, and derived trust scores.

How it works

flowchart LR
    subgraph clients["Clients — keys never leave"]
        AG["AI agent<br/>(Ed25519 keypair)"]
        CP["Counterparty<br/>agent · platform · human"]
        VF["Verifier<br/>platform · arbiter · regulator"]
    end

    subgraph registry["Registry — local state or agentcred serve"]
        ID["Identities<br/>public keys · capabilities · revocation"]
        LOG["Hash-chained append-only log<br/>attestations · disputes · deals · key rotations"]
        SCORE["Scoring engine<br/>calibrated · decayed · fault-aware"]
    end

    AG -- "register<br/>(public JWK only)" --> ID
    CP -- "signed attestations" --> LOG
    ID --> SCORE
    LOG --> SCORE
    VF -- "query · verify · evidence" --> SCORE
    SCORE -- "trust report<br/>band A–E" --> VF

Loading

1. Register — an agent gets a persistent identity (did:agentcred:<id>) binding it to a responsible owner, a capability set, and a public key.
2. Attest — counterparties record signed events: task_completed, payment_settled, dispute_opened, capability_verified. Self-attestations don't count; only counterparty-signed events do.
3. Score — a deterministic scoring function derives metrics (completion rate, dispute ratio, settled volume, tenure) and maps them to a trust band A–E.
4. Query — any platform, agent, or human can check a counterparty's score before delegating or transacting.

The trust lifecycle

sequenceDiagram
    autonumber
    participant A as Agent (key holder)
    participant R as Registry
    participant C as Counterparty

    A->>R: register (public JWK only)
    R-->>A: identity + did:agentcred:…

    C->>R: attest(agent, type, payload) — signed locally
    R->>R: verify signature · replay guard · append to chain

    A->>R: query(agent)
    R-->>A: score · band · metrics · flags

Loading

Repository structure

├── docs/spec.md                  # Protocol specification (v0.4)
├── schema/                       # JSON Schemas for identity & attestations
├── tools/simulate.py             # Scoring calibration harness (runs in CI)
├── src/agentcred/
│   ├── models.py                 # Core data objects
│   ├── canonical.py              # Canonical JSON form (signing/hashing input)
│   ├── crypto.py                 # Ed25519 keys, signing, verification, DIDs
│   ├── log.py                    # Hash-chained append-only record log
│   ├── scoring.py                # Calibrated, fault-aware scoring engine
│   ├── registry.py               # File-backed reference registry + disputes
│   ├── evidence.py               # Offline evidence-bundle verifier
│   ├── api.py                    # HTTP registry API (FastAPI)
│   └── cli.py                    # The `agentcred` command
└── tests/                        # Test suite (96 tests)

Quickstart

pip install -e ".[crypto]"

# the agent you want scored
agentcred keygen --out seller.json
agentcred register --key seller.json --name invoice-bot --caps invoices.parse
#   → prints the identity incl. did:agentcred:xxx

# a counterparty vouches for real interactions (signed, chain-committed)
agentcred keygen --out buyer.json
agentcred register --key buyer.json --name payer-bot
agentcred attest --key buyer.json --agent did:agentcred:xxx \
    --type payment_settled --payload '{"value_usd": 120.00}'

agentcred query --agent did:agentcred:xxx   # score + band A–E
agentcred verify                            # chain + every signature
agentcred log                               # append-only history

# self-service, one-way: history is kept, new attestations stop
agentcred revoke --key seller.json

# compromise recovery without losing the identity: DID stays, key changes
agentcred keygen --out seller-v2.json
agentcred rotate --key seller.json --new-key seller-v2.json

Owner binding & lost-key recovery (v0.8)

Bind an accountable principal at registration — the owner can revoke the agent and rotate its key even when the agent key is lost:

agentcred keygen --out owner.json
agentcred register --key bot.json --name shop-bot --owner-key owner.json
# ...bot key lost? the owner recovers:
agentcred keygen --out bot-v2.json
agentcred rotate --key owner.json --agent did:agentcred:xxx --new-key bot-v2.json

Deals — attestation-gated settlement (v0.6)

Rail-agnostic escrow: a mutual deal whose release condition is a signed, deal-bound attestation on-chain. Any payment rail can bind to it later.

stateDiagram-v2
    [*] --> open: deal.opened (payer + payee sign)
    open --> settled: deal.settled (condition attestation proven)
    open --> cancelled: mutual cancellation (refund)
    open --> expired: deadline passes (derived - no timers)
    expired --> settled: arbiter grace
    settled --> [*]
    cancelled --> [*]

Loading

agentcred deal-open --key buyer.json --payee-key seller.json \
    --payee did:agentcred:xxx --amount 250 --condition task_completed \
    --terms "process the invoices" --deadline 2026-12-01T00:00:00Z

# the payer attests delivery, bound to the deal — then releases
ATT=$(agentcred attest --key buyer.json --agent did:agentcred:xxx \
    --type task_completed --payload '{"deal": "deal_yyy", "value_usd": 250}' | head -1 | sed 's/recorded \(att_[a-z0-9]*\):.*/\1/')
agentcred deal-settle --key buyer.json --deal deal_yyy --settlement "$ATT"

agentcred deals --agent did:agentcred:xxx

Settlement is refused unless the cited attestation exists, is about the payee, of the agreed type, signed by payer or arbiter, and bound via payload.deal — generic praise settles nothing (spec §11).

Remote registries (v0.7)

The same CLI drives any deployed registry — add --url, keys never leave your machine:

agentcred --url https://registry.example.com register --key keys/bot.json --name invoice-bot
agentcred --url https://registry.example.com attest --key keys/buyer.json \
    --agent did:agentcred:xxx --type task_completed --payload '{"value_usd": 120}'
agentcred --url https://registry.example.com query --agent did:agentcred:xxx
agentcred --url https://registry.example.com verify

Or from Python: agentcred.client.RemoteRegistry(base_url) mirrors the local Registry surface (register, attest, disputes, deals, rotation, revocation), signing locally per spec §7.

Disputes & evidence (v0.4)

When an attested interaction goes wrong, the court system takes over:

flowchart TD
    O["dispute.opened<br/>signed by the opener<br/>targets ONE attestation<br/>rate-limited"] --> MUT["mutual resolution<br/>opener + accused both sign"]
    O --> ARB["arbiter resolution<br/>nominated third party signs"]
    MUT --> U["upheld — fault lands<br/>on the accused"]
    MUT --> RJ["rejected — lifted<br/>false-accuser penalty"]
    MUT --> ST["settled — no fault<br/>mutual walk-away"]
    ARB --> U
    ARB --> RJ
    ARB --> ST
    U & RJ & ST --> E["evidence bundle<br/>verified offline by anyone"]

Loading

agentcred dispute-open --key buyer.json --target att_xxx --reason "task never completed"
# mutual settlement — both parties sign
agentcred dispute-resolve --dispute dsp_xxx --outcome rejected \
    --key buyer.json --key seller.json

# export the portable court document; anyone can verify it offline
agentcred evidence --dispute dsp_xxx --out bundle.json
agentcred verify-bundle --file bundle.json

Fault is assigned: upheld disputes damage the accused, rejected and settled ones are lifted — a false accusation costs the accused nothing. The evidence bundle carries the signed records and public keys, so any arbiter, platform, or regulator can verify it without registry access. Details in spec §10.

HTTP API (v0.3)

pip install -e ".[api]"
agentcred serve --state ./agentcred-state --port 8000

Private keys never leave clients — sign locally (spec §7), then submit:

# register (public JWK only)
curl -X POST localhost:8000/agents -H 'content-type: application/json' \
  -d '{"public_jwk": {"kty":"OKP","crv":"Ed25519","x":"..."},"display_name":"invoice-bot"}'

# trust report
curl localhost:8000/agents/did:agentcred:xxx

# integrity audit
curl localhost:8000/verify

POST /attestations verifies signatures server-side before committing to the log; POST /agents/{did}/revoke proves authority with a signature over the revocation intent. Full contract in spec §9.

Deploy

The registry is stateful — it needs a persistent disk, so run it where volumes exist (not serverless):

# Docker anywhere
docker build -t agentcred .
docker run -p 8000:8000 -v agentcred-state:/data agentcred

# Render (blueprint with persistent disk + /health checks)
render blueprint launch

# Fly.io (volume + health checks preconfigured)
fly launch && fly deploy

State directory resolution: explicit argument → AGENTCRED_STATE env → ./agentcred-state.

Status & roadmap

v0.4.1 shipped: Ed25519-signed attestations, tamper-evident chained logs, the court system (structured disputes, fault assignment, evidence bundles), an HTTP registry API, self-service revocation — and scoring with a 180-day evidence half-life (dormant agents slide, active ones hold) plus a serial-false-accuser penalty. 12 trust invariants enforced in CI. Next: dispute rate limiting, escrow on settlement rails — see ROADMAP.md and the protocol spec.

Contributing

Issues and PRs welcome — read the spec first, then open an issue describing what you'd like to tackle.

License

MIT