_a

Versioning

How the AID specification evolves.

Versioning and Changelog

The Agent Identity & Discovery (AID) standard is designed to be a stable, living protocol. To ensure predictability for implementers while allowing for future improvements, we follow a clear and simple versioning strategy based on Semantic Versioning (SemVer) principles.

The v Key in the TXT Record

The v key within an AID TXT record (for example, v=aid2) signifies the major version of the specification that the record conforms to.

  • v=aid2: This is the current v2 default and preferred profile for new records.
  • v=aid1: This is the legacy v1.x.x compatibility profile. Clients may continue to read it for backward compatibility.
  • Breaking Changes: Any future change that is not backward-compatible with the v=aid2 rules will result in a new major version.
  • Client Behavior: A client that only understands aid1 MUST ignore records that do not have v=aid1. Current clients should prefer aid2 and use aid1 only as legacy compatibility input.

Specification Updates and Releases

The AID specification and its surrounding tooling (libraries, validators) are versioned using Git tags in the official repository.

  • Major Versions (e.g., v2.0.0): Reserved for breaking changes to the protocol, requiring a new v key (e.g., v=aid2). These will be accompanied by a major update to the documentation.
  • Minor Versions (e.g., v2.1.0): Reserved for new, non-breaking features that are backward-compatible with the current major version. For example, adding a new optional metadata key to the TXT record would be a minor release. Implementers can adopt these features at their own pace.
  • Patch Versions (e.g., v1.0.1): Used for clarifications, typo fixes, and documentation improvements that do not change the protocol's behavior. These are backward-compatible by definition.

Version History

v2.0.0 — June 2026

  • Current record profile: v=aid2 is the preferred profile for new records.
  • Base-first discovery: _agent.<domain> is the canonical lookup. Protocol-prefixed names are legacy, diagnostic, or explicitly configured base-failure probing.
  • PKA key cleanup: k is the unpadded base64url Ed25519 JWK x value.
  • Derived key identity: HTTP signature keyid is the RFC 7638 JWK thumbprint derived from k.
  • No DNS kid in v2: kid/i remains valid only for legacy aid1 PKA.
  • RFC 9421 endpoint proof: v2 PKA uses nonce-bound HTTP Message Signatures with created, expires, and Cache-Control: no-store.
  • Trust source: Discovery results distinguish DNS-rooted records from .well-known records with trustSource=dns or trustSource=well-known-tls.

v1.2.0 — Compatibility Baseline

  • Finalized the aid1 compatibility baseline used during the v2 migration window.
  • Added docs/d, dep/e, pka/k, and kid/i as legacy v1-compatible fields.
  • Preserved single-letter aliases for compact TXT records.
  • Kept legacy PKA behavior available for existing aid1 clients.

v1.1.0 — August 2025

  • Public Key Attestation (PKA): Optional Ed25519 endpoint proof via HTTP Message Signatures (RFC 9421)
  • Key aliases: Single-letter aliases for all TXT record keys (v, p, u, s, a, d, e, k, i) for byte efficiency
  • Metadata keys: docs/d for documentation URL, dep/e for deprecation timestamp
  • Protocol extensions: Added grpc, graphql, websocket, zeroconf, and ucp protocol tokens
  • .well-known fallback: JSON-based fallback at /.well-known/agent for providers without DNS control
  • Protocol-specific subdomains: Non-normative guidance for _agent._<proto>.<domain>

v1.0.0 — Initial Release

  • Core TXT record format at _agent.<domain> with v, uri, proto, auth, desc keys
  • Discovery algorithm with DNS lookup, parsing, and validation
  • Error codes: ERR_DNS_LOOKUP_FAILED, ERR_NO_RECORD, ERR_INVALID_TXT, ERR_UNSUPPORTED_PROTO, ERR_SECURITY
  • Protocol tokens: mcp, a2a, openapi, local
  • Auth hints: none, apikey, pat, basic, mtls, oauth2_code, oauth2_device, custom

Documentation Updates — August 2025

  • v1.1 docs finalized: aliases, metadata, protocol extensions, .well-known fallback, and PKA
  • New page: Identity & PKA with ELI5 and technical details
  • New page: aid-doctor CLI — Complete guide to the validation and generation tool
  • New section: Understand — Concepts, FAQ, and comparison guides

For full technical changes, see the Specification.

Our Philosophy on Stability

We believe a discovery protocol must be exceptionally stable. Our commitment to you is:

  1. Breaking Changes are Rare: Major version bumps will be infrequent and will only be made when there is a significant, community-vetted reason to do so.
  2. Clarity Through Communication: Any upcoming minor or major changes will be discussed openly in the community repository before being finalized.
  3. v2 is the Current Foundation: New deployments should publish aid2 records. The aid1 profile remains supported only for legacy and backward-compatibility clients.