agentcard-disco

agentcard-disco

Score and optimise A2A Agent Cards for discoverability.

agentcard-disco analyses an Agent Card JSON file and gives it a discoverability score across four heuristic dimensions (plus optional AI-assisted analysis), surfacing exactly what to fix before publishing to an A2A registry.

┌─────────────────────────────────────────────────────────────┐
│  agentcard-disco          discoverability score             │
│                                                             │
│  🏆  DataPulse Analytics Agent                              │
│    Source: tests/fixtures/good_card.json                    │
│                                                             │
│    Score: 88.0 / 100   (88%)   Grade:  A                   │
└─────────────────────────────────────────────────────────────┘

---

Installation

pip install agentcard-disco

For AI-assisted scoring (--deep):

pip install "agentcard-disco[deep]"

---

Quick start

# Score a local card
agentcard-disco score ./agent-card.json
agentcard-disco score ./tests/fixtures/good_card.json --deep

# Score from a URL
agentcard-disco score https://api.example.com/.well-known/agent-card.json

# + AI quality analysis (requires GROQ_API_KEY in .env)
agentcard-disco score ./agent-card.json --deep

# Export report as JSON or Markdown
agentcard-disco score ./agent-card.json --format json --output report.json
agentcard-disco score ./agent-card.json --format markdown --output report.md

# CI gate — exit 1 if score is below 70%
agentcard-disco score ./agent-card.json --fail-under 70

# Get improvement suggestions only
agentcard-disco suggest ./agent-card.json --priority high

# Compare two cards side-by-side
agentcard-disco compare ./v1.json ./v2.json

---

Scoring dimensions

Grade scale:

---

AI scoring setup (--deep)

1. Install the deep extra: pip install "agentcard-disco[deep]"
2. Add your Groq API key to a .env file in your working directory:

GROQ_API_KEY="gsk_your_key_here"

4. Run with --deep:

agentcard-disco score ./agent-card.json --deep

---

Python API

from agentcard_disco.parser import load
from agentcard_disco.scoring.engine import score

card = load("agent-card.json")        # also accepts http(s):// URLs
report = score(card)                  # Tier 1 only
report = score(card, deep=True)       # + AI analysis

print(report.grade.value)            # "A", "B", ...
print(report.percentage)             # 88.0
print(report.total_score)            # 88.0

for suggestion in report.all_suggestions:
    print(suggestion.priority, suggestion.field, suggestion.message)

---

Commands

score

agentcard-disco score SOURCE [OPTIONS]

suggest

agentcard-disco suggest SOURCE [OPTIONS]

compare

agentcard-disco compare SOURCE SOURCE [SOURCE ...] [OPTIONS]

---

Development

git clone https://github.com/chinemeze/agentcard-disco
cd agentcard-disco
pip install -e ".[deep]"
pip install pytest pytest-cov mypy ruff

# Run tests
pytest tests/ -v

# Lint
ruff check src/

# Type check
mypy src/

---

License

MIT