Conflict
§3 Discovery (SPEC.md:33-36) mandates:
A conforming agent.json file MUST be published at:
https://{domain}/agent.json
This follows the same convention as robots.txt and sitemap.xml.
But v0.2 changelog (SPEC.md:450) cites the reference implementation as:
Reference implementation: laclawclaw.com/.well-known/agent.json
— a .well-known/ path, which is the IETF RFC 8615 convention adopted by every adjacent protocol:
- A2A:
/.well-known/agent-card.json
- OIDC:
/.well-known/openid-configuration
- MTA-STS:
/.well-known/mta-sts.txt
- WebFinger:
/.well-known/webfinger
The spec mandates one location; the ecosystem and the reference implementation use the other. Implementers (including the reference one) currently ship both copies to be safe, which guarantees drift over time.
What agents actually do
Agents that discover AWP via the spec text fetch /agent.json. Agents that discover via RFC 8615 muscle memory fetch /.well-known/agent.json. If only one is served, half of agents miss.
Proposed resolution (v0.3)
Option A — bless both, with .well-known/ canonical. Match the ecosystem. §3 becomes: MUST publish at /.well-known/agent.json. MAY also publish at /agent.json for legacy clients. Agents SHOULD try /.well-known/agent.json first.
Option B — bless both, with /agent.json canonical. Keep §3 as-is but explicitly permit .well-known/. Agents SHOULD try /agent.json first, fall back to /.well-known/agent.json.
Option C — mandate redirect. Whichever is canonical, the other MUST 301-redirect to it.
A is most aligned with IETF practice and the rest of the agent-protocol ecosystem. B preserves the robots.txt/sitemap.xml framing in §3. Either way, the spec needs to acknowledge the dual-location reality.
Conflict
§3 Discovery (SPEC.md:33-36) mandates:
But v0.2 changelog (SPEC.md:450) cites the reference implementation as:
— a
.well-known/path, which is the IETF RFC 8615 convention adopted by every adjacent protocol:/.well-known/agent-card.json/.well-known/openid-configuration/.well-known/mta-sts.txt/.well-known/webfingerThe spec mandates one location; the ecosystem and the reference implementation use the other. Implementers (including the reference one) currently ship both copies to be safe, which guarantees drift over time.
What agents actually do
Agents that discover AWP via the spec text fetch
/agent.json. Agents that discover via RFC 8615 muscle memory fetch/.well-known/agent.json. If only one is served, half of agents miss.Proposed resolution (v0.3)
Option A — bless both, with
.well-known/canonical. Match the ecosystem. §3 becomes: MUST publish at/.well-known/agent.json. MAY also publish at/agent.jsonfor legacy clients. Agents SHOULD try/.well-known/agent.jsonfirst.Option B — bless both, with
/agent.jsoncanonical. Keep §3 as-is but explicitly permit.well-known/. Agents SHOULD try/agent.jsonfirst, fall back to/.well-known/agent.json.Option C — mandate redirect. Whichever is canonical, the other MUST 301-redirect to it.
A is most aligned with IETF practice and the rest of the agent-protocol ecosystem. B preserves the robots.txt/sitemap.xml framing in §3. Either way, the spec needs to acknowledge the dual-location reality.