Discovery (.well-known)

Standard discovery endpoints at the well-known URI path. These do not require authentication and are used by peers, clients, and crawlers.

GET /.well-known/agent-card.json

A2A discovery card describing the node’s agents and capabilities.

Response 200 OK

{
  "name": "my-akshi-node",
  "url": "https://node.example.com",
  "version": "0.5.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "skills": [
    {
      "id": "log-monitor",
      "name": "Log Monitor",
      "description": "Monitors log files for anomalies"
    },
    {
      "id": "researcher",
      "name": "Research Agent",
      "description": "Performs web research and summarization"
    }
  ]
}

GET /.well-known/did.json

DID (Decentralized Identifier) document for the node identity.

Response 200 OK

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:web:node.example.com",
  "verificationMethod": [
    {
      "id": "did:web:node.example.com#key-1",
      "type": "Ed25519VerificationKey2020",
      "publicKeyMultibase": "z6Mkf5rGM..."
    }
  ],
  "authentication": ["did:web:node.example.com#key-1"]
}

GET /.well-known/agents.md

Human-readable Markdown summary of the node and its agents. Useful for AI crawlers and documentation generators.

Response 200 OK (text/markdown)

# my-akshi-node

Akshi runtime v0.5.0

## Agents

- **log-monitor** — Monitors log files for anomalies
- **researcher** — Performs web research and summarization

## API

Base URL: https://node.example.com/api/v1/
A2A endpoint: https://node.example.com/api/v1/a2a/tasks