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

#security #ai #opensource #webdev

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