Agent Identity & Discovery (AID)

AID is a minimal, open standard that answers one question: "Given a domain name, where is its AI agent?"

It uses a single DNS TXT record to make any agent service—whether it speaks MCP, A2A, or another protocol—instantly discoverable. No more digging through API docs, no more manual configuration.

Built by the team at agentcommunity.org

v1.2 Highlights

• ✅ DNS-first discovery with optional protocol-specific subdomains (_agent._<proto>.<domain>)
• ✅ Well-known fallback (HTTPS-only, JSON, ≤64KB, ~2s timeout, no redirects; TTL=300 on success)
• ✅ PKA endpoint proof with Ed25519 HTTP Message Signatures (RFC 9421) and ±300s time windows
• ✅ Key aliases for byte efficiency (single-letter keys: v,p,u,s,a,d,e,k,i)
• ✅ Metadata fields (docs for documentation URLs, dep for deprecation timestamps)
• ✅ New protocols (gRPC, GraphQL, WebSocket, Zeroconf)
• ✅ Multi-language parity (TypeScript, Python, Go, Rust, .NET, Java)
• ✅ Enhanced CLI with draft saving, standardized error messages, and comprehensive test coverage

AID website

How It Works

AID establishes a well-known location for agent discovery. The process is simple, secure, and built on the backbone of the internet.

graph TD
    A[User provides domain] --> B[Query _agent.domain TXT record]
    B --> C{Record found?}
    C -->|No| D[Discovery fails]
    C -->|Yes| E[Parse record]
    E --> F{Valid format?}
    F -->|No| G[Invalid record error]
    F -->|Yes| H[Extract uri, proto, auth]
    H --> I[Connect to agent]
    I --> J[Use MCP/A2A/OpenAPI protocol]

Notes:

• Canonical location is _agent.<domain>. When a specific protocol is requested, clients may query _agent._<proto>.<domain> then _agent.<proto>.<domain> before the base record.
• .well-known JSON fallback is allowed only on DNS failure (HTTPS-only, JSON content-type, ≤64KB, ~2s timeout, no redirects). On success, TTL=300.
• If pka/kid are present, clients perform an Ed25519 HTTP Message Signatures handshake with exact covered fields and ±300s windows.

Guiding Principles

• Decentralized & Open: No central registry, no vendor lock-in. If you control a domain, you can publish an AID record.
• Contract-First: A language-agnostic YAML file is the single source of truth for all protocol constants, ensuring cross-language consistency.
• Protocol-Agnostic: Discover agents speaking MCP, A2A, OpenAPI, or even local protocols running in Docker.
• Idiomatic Libraries: Core libraries are hand-written in each language for the best developer experience, with constants generated automatically.

Getting Started

Key Resources

Documentation authority: /packages/docs in this repository is the canonical source, rendered at aid.agentcommunity.org/docs.

GitHub Repository: github.com/agentcommunity/agent-identity-discovery - Source code, issues, and community discussions.

Using the Libraries

Build AID-aware clients in your favorite language.

pnpm add @agentcommunity/aid

Node.js (uses native DNS):

import { discover, AidError } from '@agentcommunity/aid';

const { record, ttl } = await discover('supabase.agentcommunity.org');
console.log(`Found ${record.proto} agent at ${record.uri} (TTL: ${ttl}s)`);
//=> Found mcp agent at https://api.supabase.com/mcp (TTL: 60s)

Browser (uses DNS-over-HTTPS):

import { discover } from '@agentcommunity/aid/browser';

const { record } = await discover('supabase.agentcommunity.org');
console.log(`Found ${record.proto} agent at ${record.uri}`);

Advanced Usage: For building custom tools, use @agentcommunity/aid-engine - a pure, stateless library containing all AID business logic without CLI dependencies.

pip install aid-discovery

from aid_py import discover, AidError

try:
    result = discover("supabase.agentcommunity.org")
    print(f"Found {result.record.proto} agent at {result.record.uri}")
    #=> Found mcp agent at https://api.supabase.com/mcp
except AidError as e:
    print(f"AID Error ({e.code}): {e}")

# NOTE: The Python package is currently published at https://pypi.org/project/aid-discovery/ and is not yet community-owned. Community transfer is planned for a future release.

go get -u github.com/agentcommunity/agent-identity-discovery/aid-go

import (
	"fmt"
	"log"
	"github.com/agentcommunity/agent-identity-discovery/aid-go"
)

func main() {
	result, err := aid.Discover("supabase.agentcommunity.org")
	if err != nil {
		log.Fatalf("AID Error: %v", err)
	}
	fmt.Printf("Found %s agent at %s (TTL: %d)\n", result.Record.Proto, result.Record.URI, result.TTL)
    //=> Found mcp agent at https://api.supabase.com/mcp (TTL: 60)
}

Monorepo Overview

This repository uses a PNPM/Turborepo monorepo structure. It contains the full suite of libraries, tools, and documentation for the AID standard.

Packages

Project Structure

agent-identity-discovery/
├── protocol/                  # Protocol constants (YAML source of truth)
├── scripts/                   # Code generation and utility scripts
├── packages/
│   ├── aid/                   # Core TypeScript library (Node.js + Browser)
│   ├── aid-engine/            # Pure business logic library (stateless)
│   ├── aid-doctor/            # CLI tool (wraps aid-engine with side effects)
│   ├── aid-py/                # Python library
│   ├── aid-go/                # Go library
│   ├── aid-rs/                # Rust library (parser + discovery; handshake feature)
│   ├── aid-dotnet/            # .NET library (parser + discovery + PKA)
│   ├── aid-java/              # Java library (parser + discovery + PKA)
│   ├── docs/                  # Markdown documentation (rendered at /docs)
│   ├── web/                   # Next.js web workbench + docs renderer
│   ├── e2e-tests/             # End-to-end tests
│   └── (test-runners)/        # Internal test runners for Go/Python
├── tracking/                  # Development progress tracking (PHASE_*.md)
├── .github/ARCHITECTURE.md    # Comprehensive architecture documentation
├── tsconfig.base.json         # Shared TypeScript configuration
├── tsup.config.base.ts        # Shared build configuration
└── ...                        # Other configuration files

Architecture

This project follows a production-grade monorepo architecture designed for long-term maintainability and developer productivity. Our ARCHITECTURE.md provides comprehensive documentation covering:

• Build System Decisions: Why we chose Turbo + tsup over alternatives, with performance benchmarks
• Cross-Platform Compatibility: How we ensure consistent behavior across Windows, Mac, and Linux
• Package Organization: Clear separation of concerns between published libraries and internal tools
• Developer Experience: Standardized commands and hot reloading for rapid iteration

Why This Matters: Understanding our architectural decisions enables contributors to extend the project effectively and ensures consistent development practices as the team scales. Every choice prioritizes long-term project health over short-term convenience.

CLI Architecture

The AID CLI follows a clean architecture pattern with clear separation of concerns:

• @agentcommunity/aid-engine: Pure, stateless library containing all business logic (discovery, validation, PKA handshakes)
• @agentcommunity/aid-doctor: Thin CLI wrapper that handles user interaction, filesystem operations, and orchestrates the engine

Why This Separation:

• Testability: Pure functions in aid-engine are easily unit testable
• Reusability: Engine can be consumed by other tools without CLI dependencies
• Maintainability: Side effects are isolated in aid-doctor, business logic stays pure
• Performance: Engine can be used in server environments without CLI overhead

Constants generation

• Single command: pnpm gen reads protocol/constants.yml and writes language constants.
• Currently supported: TypeScript, Python, Go, and optional Rust/.NET/Java (generated only if their package paths exist).

Development

Prerequisites: Node.js (v18.17+), PNPM (v8+)

# 1. Clone the repository
git clone https://github.com/agentcommunity/agent-identity-discovery.git
cd agent-identity-discovery

# 2. Install dependencies
pnpm install

Core Monorepo Scripts

Thanks to Turborepo's intelligent caching, commands only rebuild what changed.

CI Notes

• Language CI workflows run on every PR and push because they are required checks.
• Security Scan uses diff mode on PRs and pushes. Scheduled or manual runs scan the full repo.

The Contract-First Workflow

The single source of truth for all protocol constants is protocol/constants.yml. To update them across all language packages, follow this process:

1. Edit the YAML file: Make your changes in protocol/constants.yml.
2. Run the generator: This command reads the YAML and updates the corresponding files in the TS, Go, and Python packages.

   pnpm gen
   

3. Verify and commit: Run the full test suite and build to ensure everything works.

   pnpm clean && pnpm build && pnpm test
   

   Commit the changes to protocol/constants.yml along with all the newly generated files. The CI pipeline will fail if they are not in sync.

v1.2 Release Status: ✅ READY

Implementation Complete - All v1.2 features implemented across 6+ languages with comprehensive testing. CLI enhanced with advanced features.

Ready for Release:

• ✅ All tests passing (70+ TypeScript tests + Python/Go parity tests)
• ✅ All builds successful (7/7 packages)
• ✅ Changesets prepared for version bumps
• ✅ Release workflow configured (npm + PyPI automation)
• ✅ Multi-language SDKs ready (TS, Python, Go, Rust, .NET, Java)
• ✅ Enhanced CLI with draft saving, standardized errors, and full test coverage

Next Step: Merge to main with chore(release) commit message to trigger automated release.

Development Environment

• Node.js: Version 18.17+ required (enforced via engines field and .nvmrc)
• PNPM: Version 8+ required for workspace support
• Cross-Platform: All scripts work identically on Windows, Mac, and Linux
• Hot Reloading: All packages support watch mode for rapid development
• Intelligent Caching: Turbo only rebuilds packages that actually changed, dramatically speeding up development cycles

Build Performance

Thanks to our production-grade setup:

• First build: ~15 seconds for all packages
• Incremental builds: ~1-3 seconds for most changes
• Test runs: Only affected packages run tests
• Cross-platform: Identical behavior on all operating systems

Community & Support

• For questions, ideas, and support, join our GitHub Discussions.
• Chat with us on Discord.
• To contribute, please see our Contributing Guide and Code of Conduct.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Built by the team at agentcommunity.org