agent-card-diff

Diff two A2A Agent Card documents and classify the changes. The agent-cards counterpart to mcp-tools-diff.

Status: v0.1.0 — Node 20/22 supported, library + CLI.

Why

Agent cards declare an agent's autonomy level, memory persistence, models, tools, refusal taxonomy, evaluations, and incident-response posture. Many of those are load-bearing for procurement and security review. When the card changes between two versions, which changes break the trust assumptions downstream operators already approved?

This library answers that question deterministically.

What counts as breaking

Change	Breaking?	Why
autonomy_level escalated (e.g. supervised → autonomous)	✅	More authority than previously vetted
memory_persistence escalated (e.g. session → persistent)	✅	New data-retention surface
max_context_tokens decreased	✅	Previously-working prompts may no longer fit
Tool removed	✅	Callers depending on it break
Model removed	✅	Cost or behavior baseline shifts
Refusal category removed	✅	Agent now answers what it previously refused
incident_response_uri removed	✅	Especially severe on autonomy_level=autonomous
Tool / model / refusal added	—	Additive
Description, evaluations, deployment changes	—	Documented, not contract-breaking

CLI

npx agent-card-diff <previous.json> <next.json> [--format json|markdown|summary]
                                                [--strict] [--out FILE]

Exit code:

• 0 — no changes, or only non-breaking changes
• 1 — diff is breaking (or --strict and any change exists)
• 2 — usage / I/O error

Use it in CI to gate AgentCard PRs: agent-card-diff old.json new.json --format summary fails the job on breaking change.

Library

import { diffAgentCards, toMarkdown, toSummary } from "agent-card-diff";

const diff = diffAgentCards(previous, next);
console.log(diff.breaking);          // boolean
console.log(diff.changes);           // [{ reason, detail? }, …]
console.log(diff.added.tools);       // names of newly-listed tools
console.log(diff.removed.models);    // names of removed models
console.log(toMarkdown(diff));
console.log(toSummary(diff));        // "BREAKING 7 changes" / "no changes"

Composes with

• agent-cards-spec — the schema this library diffs against.
• a2a-mcp-bridge — produces AgentCards from MCP server descriptors; pair with this diff to gate bridge regenerations.
• mcp-tools-diff — sibling diff tool for MCP tools/list snapshots; same shape, same exit-code semantics.

Develop

npm install
npm run lint && npm run typecheck && npm run coverage && npm run build
npm run demo

License

AGPL-3.0-or-later