TopoLift AgentCard

An open, vendor-neutral spec for how AI agents describe themselves so they can be found — by orchestrators, by other agents, by humans. v0.1.0 draft

It is to agent discovery what robots.txt was to the early web: a tiny, conventional file at a well-known location that lets crawlers and rankers do their job better.

What it looks like

Each agent (or its operator) publishes a JSON document at https://your-agent.example.com/.well-known/agents.json. Here's a minimal card: 

{
  "agent_id": "com.example.research-summarizer",
  "name": "Research Summarizer",
  "description": "Reads PDFs, plain-text documents, and web pages. Returns concise summaries.",
  "version": "2.3.1",
  "card_version": "0.1.0",
  "url": "https://research-summarizer.example.com/agent",
  "protocols": ["a2a", "mcp", "http"],
  "example_queries": [
    "summarize this PDF",
    "what's the TL;DR of this paper",
    "key points from a 60-page report"
  ],
  "anti_use_cases": [
    "Real-time conversation",
    "Translating documents between languages"
  ],
  "capabilities": [
    {
      "name": "summarize_document",
      "description": "Take a document and return a concise summary.",
      "examples": [{
        "input": "summarize https://arxiv.org/abs/2024.12345 in 200 words",
        "output": "This paper introduces a method for ..."
      }]
    }
  ]
}

The example_queries and anti_use_cases fields are the discoverability difference: they tell rankers what you actually want to be matched for, and just as importantly, what you don't.

Why does this exist

Agents are proliferating faster than registries can hand-curate them. Today most discovery layers fall back to keyword matching over a description string — brittle when one agent says "translate to French" and another says "convert English text to a different natural language."

A well-written AgentCard costs an hour to write and pays back every time an orchestrator considers your agent.

Compatibility

Compatible with Google A2A AgentCard and MCP server descriptors. The required fields are a subset of A2A; the optional discovery fields are additive. An agent can publish a single /.well-known/agents.json that satisfies all three.

Read more

Spec → The normative specification, RFC-2119 style. Best practices → How to write fields that rank well. JSON Schema → Machine-validated card structure (Draft 2020-12). Examples → Annotated good cards and one anti-pattern card. GitHub → Source, changelog, issues, contributions. TopoRank → One ranker that consumes AgentCards.

License

Apache 2.0. Use it without us — that's the point.