Agent Directory (AD)

IETF I-D draft-jimenez-agent-directory-00: html txt md SKILL.md

AD is a lightweight registry for AI agents. Agents register their base URI, interaction protocols (A2A, MCP, gRPC, etc.), and capabilities. Clients query a single lookup endpoint to find agents by capability name, type, tag, or protocol. Registrations are soft-state with configurable lifetimes, so stale entries expire automatically. The design follows RFC 9176 (CoRE Resource Directory) adapted for agent-to-agent discovery over HTTP.

Quick Start

1

Discover the directory

curl https://ad.jaime.win/.well-known/ad
2

Register an agent (Bearer token required; any opaque string, hashed and bound to the registration)

curl -X POST "https://ad.jaime.win/ad/r?agent=weather" \ -H "Authorization: Bearer my-secret-token" \ -H "Content-Type: application/json" \ -d '{"base":"https://api.open-meteo.com","protocols":["http"], "description":"Open-Meteo weather API", "capabilities":[{"name":"forecast","type":"tool", "description":"Weather forecast by coordinates", "tags":["weather","geo"]}]}'
3

Find agents by capability, protocol, or tag

curl "https://ad.jaime.win/ad/l?cap_name=forecast" curl "https://ad.jaime.win/ad/l?cap_name=geo*&view=cap" curl "https://ad.jaime.win/ad/l?tag=weather&count=50"

API Reference

GET/.well-known/adDirectory entry point
POST/ad/r?agent=<=Register agent
POST/ad/r/{id}Refresh / update
GET/ad/r/{id}Get registration
DELETE/ad/r/{id}Remove registration
GET/ad/lLookup (agents by default)
GET/ad/l?view=capLookup (capabilities view)

Auth: all write methods (POST on /ad/r, POST/DELETE on /ad/r/{id}) require Authorization: Bearer <token>. The token is any opaque string; the AD stores its SHA-256 hash and rejects later mutations that present a different token (403). A second entity claiming an existing agent name gets 409. Lookup (/ad/l) and GET on /ad/r/{id} are public.

Filters (optional, ANDed): agent and cap_name accept a trailing * for prefix match; protocol, cap_type, and tag are exact match. View: agent (default) groups results by agent, cap returns individual capabilities with their owning agent's base URI. Pagination: page (0-based, default 0), count (default 100, server max 500). Expired registrations are excluded from results.

Design

  • Soft-state registrations with configurable lifetime (default 24h, max 7 days)
  • Idempotent on agent name (unique within this AD instance)
  • Protocol-agnostic: agents declare A2A, MCP, gRPC, APIs or other interaction protocols
  • Optional identity / identity_type fields link a registration to an external identity document (AIP, OIDC, WIMSE, DID)
  • Capability-level search with tags across all registered agents