Configuring agents.json for AI Agents

What is agents.json?#

agents.json is a configuration file that declares your site or repository's agentic capabilities to AI developer tools. It is different from the A2A agent card (agent.json) in that it targets human-operated AI coding assistants and development tools rather than autonomous agents. When an AI coding assistant like Cursor, Windsurf, or Claude Code encounters your codebase or API, it reads agents.json to understand what automated capabilities are available. This file lists available tool endpoints, code generation templates, testing commands, and deployment procedures that the AI assistant can execute on behalf of the developer.

Creating agents.json#

Place agents.json at the root of your repository or at /.well-known/agents.json on your domain. The file describes agentic capabilities in a format AI coding tools can parse.

{
  "version": "1.0",
  "name": "Citability API",
  "description": "Domain intelligence and AI visibility scoring API",
  "capabilities": {
    "api_endpoints": [
      {
        "name": "Scan Domain",
        "method": "POST",
        "path": "/api/v1/scan",
        "description": "Scan a domain for AI visibility",
        "parameters": {
          "domain": { "type": "string", "required": true }
        }
      }
    ],
    "commands": [
      {
        "name": "run_tests",
        "command": "pytest tests/ -v",
        "description": "Run the full test suite"
      },
      {
        "name": "lint",
        "command": "ruff check .",
        "description": "Run linter on all Python files"
      }
    ]
  }
}

agents.json vs AGENTS.md#

AGENTS.md is a companion file (now governed by the AAIF alongside MCP) that provides human-readable context for AI coding agents working in your repository. While agents.json is structured data for machine parsing, AGENTS.md is a markdown narrative that helps AI understand your project's architecture, conventions, and development practices. Use both: agents.json for tool discovery and AGENTS.md for context. Think of agents.json as the API spec and AGENTS.md as the developer guide.

• agents.json: Machine-readable, declares capabilities and endpoints.
• AGENTS.md: Human-readable, explains architecture and conventions.
• Use both together for comprehensive AI developer tool support.
• Place agents.json at /.well-known/agents.json on your domain.
• Place AGENTS.md at the root of your code repository.