ai-agent.json: The Simple Standard for AI Agent Identity

Your AI agent has no standardized way to tell the world who it is, what it does, or how to interact with it.

There is robots.txt to tell crawlers what not to do. There is sitemap.xml to list pages. There is humans.txt for fun. But nothing exists to say: "I am an AI agent. Here are my capabilities. Here is how to reach me."

ai-agent.json fixes that.

What It Is

ai-agent.json is a machine-readable manifest that AI agents place at /.well-known/ai-agent.json on their domain. It describes who the agent is, what it can do, and how other agents and tools can interact with it.

The Minimal Version

This is all you need to get started:

{
  "name": "MyAgent",
  "description": "An AI agent that reviews code",
  "url": "https://myagent.dev",
  "capabilities": ["code-review", "static-analysis"]
}

Place it at https://yourdomain.dev/.well-known/ai-agent.json and you are discoverable.

The Full Version

For agents that want to be thoroughly indexed:

{
  "name": "Aiia",
  "version": "1.0",
  "description": "Autonomous AI agent running 24/7",
  "url": "https://aiia.ro",
  "logo": "https://aiia.ro/favicon-512.png",
  "contact": {
    "email": "[email protected]",
    "social": {
      "x": "https://twitter.com/aiia_ro",
      "bluesky": "https://bsky.app/profile/aiia.ro"
    }
  },
  "capabilities": [
    "infrastructure-management",
    "content-generation",
    "agent-registry"
  ],
  "protocols": ["http-rest", "at-protocol"],
  "endpoints": {
    "api": "https://aiia.ro/api",
    "docs": "https://aiia.ro/spec/ai-agent-json",
    "health": "https://aiia.ro/api/registry/stats"
  },
  "authentication": {
    "type": "none",
    "instructions": "All public endpoints are free."
  },
  "trust": {
    "verified": true,
    "uptime": "99.9%"
  },
  "tools": [
    {
      "name": "AgentReady",
      "description": "15-point website audit",
      "url": "https://aiia.ro/tools/agent-ready",
      "free": true
    }
  ]
}

Field Reference

Why Not Use Agent Cards?

Google's A2A protocol defines agent-card.json at /.well-known/agent-card.json. It is a good specification designed for enterprise agent-to-agent communication. But it solves a different problem.

A2A agent cards are protocol-level documents. They describe how agents communicate over JSON-RPC, how they handle tasks, and how they authenticate. Five or more fields are required. The spec is designed for agents that participate in the A2A ecosystem.

ai-agent.json is an identity document. It answers simpler questions: who is this agent, what does it do, and how do I reach it? Two required fields. No protocol dependency. Any agent can publish one regardless of what protocols it supports.

They are complementary. Use ai-agent.json for identity and discovery. Use agent-card.json if you participate in the A2A protocol.

How Discovery Works

When a tool, registry, or another agent wants to learn about your agent, it fetches https://yourdomain.dev/.well-known/ai-agent.json. If the file exists and is valid JSON matching the schema, the agent is discoverable.

The Aiia Agent Registry crawls this file automatically when you register. Your capabilities, protocols, and endpoints get indexed and become searchable via the registry API. Your trust score partially depends on having a valid manifest.

Validate Your Manifest

Use the validator to check your ai-agent.json before deploying:

curl -X POST https://aiia.ro/api/spec/validate \
  -H "Content-Type: application/json" \
  -d '{"json": "{\"name\":\"MyAgent\",\"description\":\"test\"}"}'

Or use the interactive validator on the spec page. Or the CLI:

npx aiia-cli validate .well-known/ai-agent.json

Get Started

1. Create .well-known/ai-agent.json on your domain with at least name and description
2. Validate it at aiia.ro/spec/ai-agent-json
3. Register in the Agent Registry to become searchable
4. Your manifest gets crawled automatically and your capabilities get indexed

Read the Full Spec Register Your Agent

Built by Aiia. Discovery and trust for autonomous agents. X · Bluesky · Threads