A draft specification for Agent Cards — declarative documents that disclose what an AI agent is, what it can do, what it refuses, and how it has been evaluated.
HuggingFace gave models a way to disclose themselves through model cards. Agents need the same — but the disclosure surface is different. Agents have tool surfaces, refusal behavior, memory persistence, and deployment posture that models alone do not. An Agent Card is the document that makes those properties machine-readable, auditable, and comparable across agents.
| Pillar | What it does |
|---|---|
| Disclose | A declarative capability surface — what models, what tools, what context window, what memory model |
| Constrain | A refusal taxonomy and a list of categories that require human-in-the-loop approval |
| Audit | Eval results, deployment posture, and an incident-response surface |
A model card documents an LLM. An agent is a system built on top of an LLM, with tools, prompts, and policies layered in. The agent's capability surface is not the model's capability surface.
Two examples of agent properties that model cards cannot express:
- An agent built on Claude Opus may be configured to refuse a category the base model would not refuse, because of a safety prompt or a policy layer
- An agent's tool surface (e.g. "can write to your AWS account") is determined by integration choices, not by the model
READMEs are unstructured. An Agent Card is parseable: a CI pipeline can validate it, a registry can index it, a procurement team can compare two agents side-by-side without reading paragraphs of prose.
- Pick an
agent.id(kebab-case, unique within your org or product line). - Author an Agent Card document conforming to
agent-card.schema.json. Start from examples. - Validate with any JSON Schema 2020-12 validator.
- Publish at
https://<your-product>/.well-known/agents/<agent-id>.json(preferred) or alongside the agent's source. - Reference Tool Cards (mcp-tool-card-spec) and Prompt Provenance records (prompt-provenance-spec) where applicable.
SPEC.md— full v0.1 specificationagent-card.schema.json— JSON Schema (draft 2020-12)examples/— reference documents for a customer-support agent, an SRE incident agent, and a sandboxed eval agent
v0.1 draft. Issues and pull requests welcome.
MIT-licensed. The specification text, JSON Schema, and example documents in this repository may be freely implemented, extended, redistributed, or incorporated into commercial or non-commercial products with attribution. Reference implementations of this spec (such as mcp-kinetic-gain) are licensed separately under AGPL-3.0.
A family of nine open specifications for the answer-engine and agent era. Each spec is a self-contained JSON document format with its own JSON Schema and reference examples; together they compose into an end-to-end account of entity, agent, prompt, tool, citation, EdTech disclosure, and incident reporting. Single landing: kinetic-gain-protocol-suite.
| Spec | What it does |
|---|---|
| AEO Protocol | Entity declaration at /.well-known/aeo.json — authoritative claims, citation preferences, audit hooks |
| Prompt Provenance | Versioned, lineaged, reviewable LLM prompt records |
| Agent Cards (this) | Declarative agent capability and refusal disclosure |
| AI Evidence Format | Structured citations that travel with LLM-generated claims |
| MCP Tool Cards | Per-tool disclosure layered on Model Context Protocol servers |
| AI Tutor Cards | EdTech-specialized agent disclosure (vendor-side) |
| Student AI Disclosure | Student-side disclosure attached to submitted work |
| Classroom AI AUP | District / school / course AI policy (third leg of the EdTech trio) |
| AI Incident Card | Post-incident disclosure for AI agents — references this spec via affected.agent_card_uris[] |
| Clinical AI Disclosure | HealthTech vertical — vendor disclosure for healthcare AI (HIPAA / FDA / SaMD). References this spec via agent_card_uri. |
| Repo | What it does |
|---|---|
prompt-injection-bench |
30-attack corpus + Python harness for prompt injection. Every record carries an agent_card_refusal_categories back-ref to this spec's refusal_taxonomy[].category — grep your declared categories against the corpus to test whether your stated commitments hold under attack. |
Connect: LinkedIn · Kinetic Gain · Medium · Skills