Why your AI agent needs a .well-known discovery endpoint

#ai #webdev #security #opensource

You know how websites publish /.well-known/security.txt so security researchers can find the right contact? RFC 9116 made that a standard. Simple file, fixed location, machine-readable. It works because everyone agrees where to look.

AI agents need something similar. Not for security contacts, for governance discovery.

The problem

Say you're integrating with an AI service. You want to know: does this agent sign its actions? What algorithm? Where do I verify a signature? What capabilities does the governance layer support?

Right now you'd dig through docs, maybe find an API reference, maybe email someone. There's no standard place to look.

The pattern

A /.well-known/governance.json file at a predictable URL. Any client or auditor can fetch it and immediately understand what governance is available.

Here's what goes in it:

{
  "name": "your-service",
  "version": "1",
  "endpoints": {
    "sign": "https://api.example.com/v1/agents/{agent_id}/sign",
    "verify": "https://api.example.com/v1/verify/{signature_id}",
    "agents": "https://api.example.com/v1/agents"
  },
  "algorithms": ["ml-dsa-44", "ml-dsa-65", "ml-dsa-87"],
  "capabilities": [
    "sign",
    "verify",
    "delegation",
    "policy_enforcement",
    "audit_export_csv"
  ],
  "auth": {
    "type": "api_key",
    "header": "X-API-Key"
  },
  "license": "MIT"
}

The key sections:

endpoints - where to sign actions, verify signatures, manage agents
algorithms - which cryptographic algorithms are supported (ML-DSA is the FIPS 204 post-quantum family)
capabilities - what the governance layer can actually do
auth - how to authenticate

Why this matters for interoperability

If every AI governance provider publishes this file at the same path, tooling can auto-discover it. CI/CD pipelines can check if governance is configured. Auditors can programmatically verify that an agent's governance claims match reality.

It's the same reason robots.txt works. Convention over configuration. You don't need a registry or a discovery service. Just a file at a known path.

A live example

We publish ours at asqav.com/.well-known/governance.json. It includes endpoints, supported algorithms, integration list, and links to docs. Anyone can fetch it right now.

But this isn't an asqav-specific idea. Any project doing AI governance could publish the same file. The schema is straightforward. Adapt it to whatever your service provides.

Adopting this yourself

If you run an AI governance service, or even just an agent platform with audit capabilities:

Create /.well-known/governance.json on your domain
List your endpoints, algorithms, and capabilities
Keep it updated when your API changes

No spec to implement. No committee to join. Just a JSON file at a URL that makes sense.

The more projects that do this, the easier it gets to build tooling around AI governance discovery. And that's the whole point, making governance something you can verify programmatically instead of taking someone's word for it.

DEV Community