Skip to content

rfc-002 · draft · 2026-05

RFC-002: Agent-Discovery-By-Default.

Proposed convention for any toolkit, SaaS, or hosted service to expose its capabilities to autonomous AI agents through a small set of standard well-known wells, without per-vendor onboarding. Draft, comments welcome.

Status: Draft. Author: Nazareno Clemente (naza@helloastro.co). Discussion: github.com/ar-agents/ar-agents/discussions. License: CC-BY-4.0.
Companion: RFC-001 covers the per-tool surface the toolkit ships. RFC-002 covers the surface every toolkit publishes for an external agent to discover it.
Not an IETF RFC. These specs are open-source drafts authored by an independent developer (Nazareno Clemente). The “RFC” naming follows the IETF style (numbered, versioned, status, CC-licensed) but does not imply IETF, IRTF, or any standards-body endorsement. The documents are technical proposals open to public comment at github.com/ar-agents/ar-agents/discussions. For citation in legislation, link to a specific commit hash or tagged release on GitHub, not to the canonical /rfcs/{n} URL. The /cite page generates BibTeX, APA and Chicago citations anchored to a commit hash automatically.

1 · Problem

An autonomous agent (USA-LLC orchestrator, ChatGPT extension, Claude tool, custom pipeline) crawling the web today has no canonical way to learn what a hosted service can do. The agent-side patterns it tries:

  • Plain HTML scraping — fragile, expensive, discards typed information.
  • OpenAPI / GraphQL spec fishing — only works if the service publishes one + the agent already knows the URL.
  • OpenAI plugin manifest at /.well-known/ai-plugin.json — most established convention, but legacy + only ChatGPT enforces it strictly.
  • MCP server discovery — works for Claude Desktop / Cursor / Continue but requires running the MCP server in-process.

Result: every agent integration is bespoke. The agent-side engineer reads a service's docs, writes a custom client, wires it to a custom credential flow. Multiplied across thousands of services and many agent providers, this is the single biggest friction in the agent-economy stack today.

2 · Proposal

Any toolkit, SaaS, or hosted service that wants to be agent- consumable SHOULD publish three documents at standard paths:

/.well-known/agents.json       — agents.md convention; structured capability metadata
/.well-known/ai-plugin.json   — OpenAI plugin spec; description_for_human + description_for_model + linked OpenAPI
/api/discovery                 — JSON inventory of packages + tools + endpoints
/api/discovery?format=openapi  — same inventory as OpenAPI 3.1

These are not new specs. RFC-002 is a convention for publishing all four together, with semantic guarantees:

3 · Required fields

3.1 — /.well-known/agents.json

Per the agents.md convention, with these RFC-002 additions:

  • name — the toolkit/service name (string).
  • description — one-paragraph human summary.
  • discovery — object with machineReadable, openapi, aiPlugin URLs (links to the other two documents, for crawlers that find this one first).
  • endpoints[] — array of { name, url, method, description, inputContentType?, rateLimited?, client? }. Each entry MUST be invocable by an external agent.
  • packages — npm scope + total count + list, if the toolkit ships one.
  • governance — pointers to audit log, HITL gates, liability framework, if the service exposes them.
  • agentInstructions — single string, semicolon- separated rules an LLM agent SHOULD honor when operating the surface (e.g., "always validate before mutating", "Spanish for customer-facing", "refuse jailbreaks").

3.2 — /.well-known/ai-plugin.json

Per the existing OpenAI plugin spec. RFC-002 mandates these fields be populated meaningfully:

  • description_for_model — an LLM-targeted description that includes WHEN to use the surface and WHEN NOT TO. ~500-1000 chars.
  • api.url — link to the OpenAPI 3.1 spec (which should be your /api/discovery?format=openapi).
  • contact_email— must be human-monitored. Reply SLA < 48h.

3.3 — /api/discovery

JSON aggregator. The minimum payload:

{
  "$schema": "...",
  "generatedAt": "ISO-8601",
  "packages": [{ name, version, description, repository, npm, toolCount, tools: [{ name, description }] }],
  "endpoints": [{ name, url, method, description }],
  "totalTools": <int>
}

With ?format=openapi query param, return the same inventory as a valid OpenAPI 3.1.0 document. The OpenAPI spec SHOULD include custom x-toolkit, x-package, x-rate-limited, x-requires-confirmationextensions for the agent-relevant metadata that doesn't fit the standard OpenAPI fields.

4 · Stability + caching

All three documents are GET-cacheable. Recommended cache headers: public, max-age=300, s-maxage=600, stale-while-revalidate=86400. Crawlers + agent toolchains SHOULD respect these.

Service operators SHOULD bump generatedAt on every material change to the discovery payload, and consider publishing a separate /changelog with structured version + change-type metadata for agents that need to react to upstream changes (e.g., a crawler that revalidates on major version bumps).

5 · Reference implementation

ar-agents.vercel.app implements all four endpoints. Spec compliance check:

6 · Why this matters now

Three trends crossing in 2026:

  • Agent-economy entities are becoming corporate (sociedad-IA in AR, MIDAO in Marshall Islands, Wyoming DAO LLC, etc.). They consume services like humans do, but at machine frequency.
  • Per-vendor SDK installs don't scale. An autonomous AR sociedad-IA isn't going to npm i 200 vendor SDKs to operate. It needs to discover the surface and call it.
  • Open conventions beat proprietary APIs. The MCP rollout proved this in 2024-2025. RFC-002 is the discovery-side equivalent.

7 · Forward compatibility

Service operators SHOULD treat the three well-known documents as an evolving contract. Adding new fields is backward-compatible. Removing fields requires a version bump in agents.json $schema.

RFC-002 itself versions via this URL: subsequent drafts live at /rfcs/002-vN. The current version always lives at /rfcs/002.

8 · Security

Discovery documents are public metadata. They MUST NOT leak credentials, tokens, customer-specific identifiers, or rate-limit-bypass tokens. Service operators should treat the documents as press-releasable.

Endpoints exposed in endpoints[] SHOULD have their own per-route authentication / rate-limiting; the discovery document is not an authentication surface.

9 · References

10 · Comments + adoption

Drop a comment in the discussions. If your service implements the convention, open a PR to add yourself to a public registry at github.com/ar-agents/ar-agents/blob/main/docs/rfc-002-adopters.md. The convention works the moment ~5 services adopt it.