Skip to content

SPEC.md

Latest commit

 

History

History
132 lines (104 loc) · 4.01 KB

SPEC.md

File metadata and controls

132 lines (104 loc) · 4.01 KB

agents.txt Specification v1.0

Overview

agents.txt is a file served at the root of a website that describes how autonomous AI agents can interact with the site. It is the agent-interaction counterpart to robots.txt.

File Location

  • Plain text: https://example.com/agents.txt
  • JSON (optional): https://example.com/.well-known/agents

Both formats carry the same information. The plain-text file is required; the JSON endpoint is recommended.

Plain Text Format

General Syntax

  • Lines starting with # are comments
  • Lines starting with ## are section headers
  • Fields use Key: Value format
  • Endpoint lines use METHOD /path format (e.g., GET /api/feeds)
  • Inline comments on endpoint lines are allowed after #

Required Fields

Field Format Description
Name String Platform name
URL HTTP(S) URL Canonical site URL
Description String What the platform offers to agents
Capability String (one per line) A capability the agent must support. At least one required.
Register METHOD URL Registration endpoint (e.g., POST https://example.com/api/register)
Auth-Method String Authentication method (e.g., Bearer token, API key)

Optional Fields

Field Format Description
Contact Email or URL Contact for human operators
Payment String Payment method — currency, network, chain ID
Payment-Wallet Wallet address Wallet to receive payments (e.g., 0x...)
Min-Bid String Minimum payment/bid amount (e.g., 0.10 USDC)
Rate-Limit String Rate limit description (e.g., 120/minute)
JSON URL URL to the JSON version of this file

Sections

Section headers (##) are optional but recommended for readability:

  • ## IDENTITY — Name, URL, Description, Contact
  • ## AGENT CAPABILITIES REQUIRED — Capability entries
  • ## AUTHENTICATION — Register, Auth-Method
  • ## ENDPOINTS — API endpoint listing
  • ## PAYMENT METHODS — Payment, Payment-Wallet, Min-Bid
  • ## RATE LIMITS — Rate-Limit entries
  • ## RULES — Usage rules (as comments)
  • ## MACHINE-READABLE — JSON field

Endpoint Listing

Endpoints are listed with their HTTP method and path:

GET  /api/feeds/catalog     # Optional description
POST /api/agents/register   # Optional description

JSON Format

The JSON format mirrors the plain-text fields in a structured object served at /.well-known/agents with Content-Type: application/json.

Schema

{
  "spec_version": "1.0",
  "name": "string (required)",
  "url": "string (required, HTTP/HTTPS URL)",
  "description": "string (required)",
  "contact": "string (optional, email or URL)",
  "last_updated": "string (optional, ISO 8601 date)",
  "capabilities_required": ["string (at least one required)"],
  "authentication": {
    "method": "string (required)",
    "register": {
      "method": "string (HTTP method)",
      "endpoint": "string (URL)",
      "body": {}
    }
  },
  "endpoints": [
    {
      "method": "string (HTTP method)",
      "path": "string",
      "description": "string (optional)",
      "auth_required": "boolean (optional)"
    }
  ],
  "payment": {
    "methods": [
      {
        "currency": "string",
        "network": "string",
        "chain_id": "number (optional)"
      }
    ],
    "wallet": "string (optional)",
    "min_bid": "string (optional)"
  },
  "rate_limits": {
    "authenticated": "string (optional)",
    "unauthenticated": "string (optional)"
  },
  "rules": ["string (optional)"]
}

Discovery

Agents discovering a new site should:

  1. Fetch https://site.com/agents.txt (plain text)
  2. If a JSON: field is present, fetch the JSON endpoint for structured data
  3. Alternatively, check https://site.com/.well-known/agents directly

Versioning

The spec version is indicated by:

  • A # Spec version: X.Y comment in the plain-text file
  • A "spec_version": "X.Y" field in the JSON format

Current version: 1.0