Agent Doctor

An AI-agent-facing service that audits ERC-8004 agent registrations and tells owners exactly how to fix them.

Why: of 170,000+ agents registered in the ERC-8004 registries, only 3–15% expose BOTH a valid registration file AND a live declared endpoint (arXiv:2606.26028). Agent Doctor diagnoses that gap: it resolves the on-chain identity, fetches and validates the registration file, probes every declared endpoint for liveness, verifies the ENSIP-25 bidirectional ENS link, and returns a graded report (A–F) with a concrete, ordered fix list.

What it checks

Grades: A all pass · B warnings only · C endpoint/ENS failures · D broken registration file · F identity unresolvable.

Related MCP server: mcp-audit-server

Quickstart

cd agent-doctor
python3 -m venv .venv
.venv/bin/pip install web3 fastapi uvicorn httpx mcp pytest

CLI

.venv/bin/python -m agent_doctor check --chain base --agent-id 42
.venv/bin/python -m agent_doctor check --chain base --agent-id 42 --ens myagent.eth
.venv/bin/python -m agent_doctor check --ens myagent.eth          # best-effort discovery
.venv/bin/python -m agent_doctor check --chain base --agent-id 42 --json

Exit code 0 for grades A/B, 1 otherwise (CI-friendly).

HTTP API

.venv/bin/uvicorn agent_doctor.api:app --port 8004
curl 'http://127.0.0.1:8004/check?chain=base&agentId=42'
curl 'http://127.0.0.1:8004/check?ens=myagent.eth'
curl 'http://127.0.0.1:8004/healthz'

MCP (stdio)

.venv/bin/python -m agent_doctor.mcp_server

Exposes one tool, diagnose_agent(chain, agent_id, ens, timeout). Claude Code registration example:

claude mcp add agent-doctor -- /path/to/agent-doctor/.venv/bin/python -m agent_doctor.mcp_server

Configuration

• AGENT_DOCTOR_RPC_<CHAIN> (e.g. AGENT_DOCTOR_RPC_BASE) — override the default publicnode RPCs; ENS always resolves on Ethereum mainnet.

• AGENT_DOCTOR_IPFS_GATEWAY — default https://ipfs.io/ipfs/.

• AGENT_DOCTOR_HTTP_TIMEOUT — default 10 s.

Tests

.venv/bin/python -m pytest            # unit tests (offline)
.venv/bin/python -m pytest --live     # + live read-only test against the real Base registry

Fixtures include the ENSIP-25 worked example: registry 0x8004A169…a432 on eip155:1, agentId 42 → agent-registration[0x000100000101148004a169fb4a3325136eb29fa0ceb6d2e539a432][42].

Register Agent Doctor itself (owner-only steps)

The repo ships its own dogfood identity in identity/: registration.json (valid per our own validator), mint_identity.py (unsigned tx builder — never touches keys), ens_records.py (exact ENSIP-25 record printer). To go live:

1. Registration file is hosted — this repo is public, so the canonical agentURI is https://raw.githubusercontent.com/Maxwell012/agent-doctor/main/identity/registration.json. The agentdoctor.example.com service endpoints inside it are still placeholders — replace them once the HTTP API is deployed somewhere real.

2. Fund a wallet on Base (a few dollars of ETH for gas).

3. Mint the identity — build the unsigned tx and sign it in your own wallet:

   .venv/bin/python identity/mint_identity.py --agent-uri https://raw.githubusercontent.com/Maxwell012/agent-doctor/main/identity/registration.json --from 0xYourAddress

   Function: register(string agentURI) on 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 (Base, chainId 8453). Read the minted agentId from the Registered event, then update registrations[].agentId in registration.json (currently a 0 placeholder) and re-upload.

4. Buy the ENS name — agent-doctor.eth (checked free on mainnet 2026-07-13); register it in the ENS app, set its ETH address record to the minting wallet.

5. Set the ENSIP-25 text record (bidirectional link):

   .venv/bin/python identity/ens_records.py --ens <yourname>.eth --chain base --agent-id <agentId>

   Set the printed key to value 1 in the ENS app; also update the ENS services[] entry in registration.json if the name differs from the placeholder. Optionally set profile text records (avatar, description, url).

6. Optional: buy the $1 verification certificate at veral.tech for an extra trust signal.

7. Self-check until grade A:

   .venv/bin/python -m agent_doctor check --chain base --agent-id <agentId> --ens <yourname>.eth

Design notes / known limits (MVP)

• Read-only chain access; no keys, no signing, no state.

• The deployed registry proxy does not answer totalSupply() / enumeration (observed 2026-07-09), so ENS-only diagnosis without an agentId is best-effort and warns instead of guessing.

• MCP probe is reachability-only; a real MCP handshake (initialize/tools-list) is a natural next step.

• Registration schema is validated leniently on purpose — the EIP-8004 registration-v1 field list is not a closed schema.