{"id":44358777,"url":"https://github.com/agentcommunity/agent-identity-discovery","last_synced_at":"2026-02-23T22:00:42.585Z","repository":{"id":303069717,"uuid":"1014307697","full_name":"agentcommunity/agent-identity-discovery","owner":"agentcommunity","description":"Agent Interface Discovery ","archived":false,"fork":false,"pushed_at":"2026-02-07T01:22:28.000Z","size":1415,"stargazers_count":13,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-07T12:54:35.997Z","etag":null,"topics":["a2a","agent","agent-discovery","discovery","dns","llm","llm-agent","mcp","ucp"],"latest_commit_sha":null,"homepage":"https://aid.agentcommunity.org/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agentcommunity.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING-spec.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-07-05T13:08:18.000Z","updated_at":"2026-02-07T01:22:30.000Z","dependencies_parsed_at":"2025-12-05T10:04:18.426Z","dependency_job_id":null,"html_url":"https://github.com/agentcommunity/agent-identity-discovery","commit_stats":null,"previous_names":["agentcommunity/agent-interface-discovery","agentcommunity/agent-identity-discovery"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/agentcommunity/agent-identity-discovery","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentcommunity%2Fagent-identity-discovery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentcommunity%2Fagent-identity-discovery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentcommunity%2Fagent-identity-discovery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentcommunity%2Fagent-identity-discovery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agentcommunity","download_url":"https://codeload.github.com/agentcommunity/agent-identity-discovery/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentcommunity%2Fagent-identity-discovery/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29626895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T18:02:07.722Z","status":"ssl_error","status_checked_at":"2026-02-19T18:01:46.144Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a","agent","agent-discovery","discovery","dns","llm","llm-agent","mcp","ucp"],"created_at":"2026-02-11T17:00:41.118Z","updated_at":"2026-02-23T22:00:42.578Z","avatar_url":"https://github.com/agentcommunity.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Agent Identity \u0026 Discovery (AID)\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e\u003cstrong\u003eDNS for Agents: Type a domain. Connect to its agent. Instantly.\u003c/strong\u003e\u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://github.com/agentcommunity/agent-identity-discovery/actions/workflows/ci.yml\"\u003e\n      \u003cimg src=\"https://github.com/agentcommunity/agent-identity-discovery/actions/workflows/ci.yml/badge.svg\" alt=\"Build Status\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://aid.agentcommunity.org/workbench\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/Demo-Try%20AID%20Workbench-brightgreen?style=flat\u0026logo=rocket\" alt=\"Demo AID Workbench\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://img.shields.io/github/package-json/v/agentcommunity/agent-identity-discovery?style=flat\u0026label=AID%20Version\u0026color=orange\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/package-json/v/agentcommunity/agent-identity-discovery?style=flat\u0026label=AID%20Version\u0026color=orange\" alt=\"AID Version\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://www.npmjs.com/package/@agentcommunity/aid\"\u003e\n      \u003cimg src=\"https://img.shields.io/npm/v/@agentcommunity/aid.svg?color=blue\" alt=\"npm version\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/aid-discovery/\"\u003e\n      \u003cimg src=\"https://img.shields.io/pypi/v/aid-discovery.svg?color=blue\" alt=\"PyPI version\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/agentcommunity/agent-identity-discovery/blob/main/LICENSE\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/orgs/agentcommunity/discussions\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/Community-Discussions-purple\" alt=\"GitHub Discussions\" /\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\nAID is a minimal, open standard that answers one question: **\"Given a domain name, where is its AI agent?\"**\n\nIt 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.\n\n**Built by the team at [agentcommunity.org](https://agentcommunity.org)**\n\n### v1.2 Highlights\n\n- ✅ **DNS-first discovery** with optional protocol-specific subdomains (`_agent._\u003cproto\u003e.\u003cdomain\u003e`)\n- ✅ **Well-known fallback** (HTTPS-only, JSON, ≤64KB, ~2s timeout, no redirects; TTL=300 on success)\n- ✅ **PKA endpoint proof** with Ed25519 HTTP Message Signatures (RFC 9421) and ±300s time windows\n- ✅ **Key aliases** for byte efficiency (single-letter keys: `v,p,u,s,a,d,e,k,i`)\n- ✅ **Metadata fields** (`docs` for documentation URLs, `dep` for deprecation timestamps)\n- ✅ **New protocols** (gRPC, GraphQL, WebSocket, Zeroconf)\n- ✅ **Multi-language parity** (TypeScript, Python, Go, Rust, .NET, Java)\n- ✅ **Enhanced CLI** with draft saving, standardized error messages, and comprehensive test coverage\n\n[AID website](https://aid.agentcommunity.org)\n\n## How It Works\n\nAID establishes a well-known location for agent discovery. The process is simple, secure, and built on the backbone of the internet.\n\n```mermaid\ngraph TD\n    A[User provides domain] --\u003e B[Query _agent.domain TXT record]\n    B --\u003e C{Record found?}\n    C --\u003e|No| D[Discovery fails]\n    C --\u003e|Yes| E[Parse record]\n    E --\u003e F{Valid format?}\n    F --\u003e|No| G[Invalid record error]\n    F --\u003e|Yes| H[Extract uri, proto, auth]\n    H --\u003e I[Connect to agent]\n    I --\u003e J[Use MCP/A2A/OpenAPI protocol]\n```\n\n\u003e Notes:\n\u003e\n\u003e - Canonical location is `_agent.\u003cdomain\u003e`. When a specific protocol is requested, clients may query `_agent._\u003cproto\u003e.\u003cdomain\u003e` then `_agent.\u003cproto\u003e.\u003cdomain\u003e` before the base record.\n\u003e - `.well-known` JSON fallback is allowed only on DNS failure (HTTPS-only, JSON content-type, ≤64KB, ~2s timeout, no redirects). On success, TTL=300.\n\u003e - If `pka`/`kid` are present, clients perform an Ed25519 HTTP Message Signatures handshake with exact covered fields and ±300s windows.\n\n## Guiding Principles\n\n- **Decentralized \u0026 Open:** No central registry, no vendor lock-in. If you control a domain, you can publish an AID record.\n- **Contract-First:** A language-agnostic [YAML file](./protocol/constants.yml) is the single source of truth for all protocol constants, ensuring cross-language consistency.\n- **Protocol-Agnostic:** Discover agents speaking MCP, A2A, OpenAPI, or even local protocols running in Docker.\n- **Idiomatic Libraries:** Core libraries are hand-written in each language for the best developer experience, with constants generated automatically.\n\n## Getting Started\n\n### Key Resources\n\n| Resource                   | Link                                                                   | Description                                                                                                                                                                    |\n| :------------------------- | :--------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Interactive Workbench**  | **[aid.agentcommunity.org](https://aid.agentcommunity.org)**           | The best way to see the protocol in action with a live resolver and generator.                                                                                                 |\n| **Official Documentation** | **[aid.agentcommunity.org/docs](https://aid.agentcommunity.org/docs)** | Specification, quick start guides, reference, and tooling docs.                                                                                                                |\n| **Command-Line Tool**      | `npm install -g @agentcommunity/aid-doctor`                            | The quickest way to check, validate, generate, and save AID records. Built on @agentcommunity/aid-engine with draft saving, PKA key generation, and comprehensive diagnostics. |\n| **Examples Guide**         | **[EXAMPLES.md](./EXAMPLES.md)**                                       | Complete guide to the examples system: how examples are defined, generated, and used across DNS, UI, and testing.                                                              |\n\n\u003e Documentation authority: `/packages/docs` in this repository is the canonical source, rendered at [aid.agentcommunity.org/docs](https://aid.agentcommunity.org/docs).\n\n**GitHub Repository**: [github.com/agentcommunity/agent-identity-discovery](https://github.com/agentcommunity/agent-identity-discovery) - Source code, issues, and community discussions.\n\n### Using the Libraries\n\nBuild AID-aware clients in your favorite language.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTypeScript (Node.js \u0026 Browser)\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\npnpm add @agentcommunity/aid\n```\n\n**Node.js (uses native DNS):**\n\n```typescript\nimport { discover, AidError } from '@agentcommunity/aid';\n\nconst { record, ttl } = await discover('supabase.agentcommunity.org');\nconsole.log(`Found ${record.proto} agent at ${record.uri} (TTL: ${ttl}s)`);\n//=\u003e Found mcp agent at https://api.supabase.com/mcp (TTL: 60s)\n```\n\n**Browser (uses DNS-over-HTTPS):**\n\n```typescript\nimport { discover } from '@agentcommunity/aid/browser';\n\nconst { record } = await discover('supabase.agentcommunity.org');\nconsole.log(`Found ${record.proto} agent at ${record.uri}`);\n```\n\n\u003e **Advanced Usage**: For building custom tools, use `@agentcommunity/aid-engine` - a pure, stateless library containing all AID business logic without CLI dependencies.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ePython\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\npip install aid-discovery\n```\n\n```python\nfrom aid_py import discover, AidError\n\ntry:\n    result = discover(\"supabase.agentcommunity.org\")\n    print(f\"Found {result.record.proto} agent at {result.record.uri}\")\n    #=\u003e Found mcp agent at https://api.supabase.com/mcp\nexcept AidError as e:\n    print(f\"AID Error ({e.code}): {e}\")\n\n# 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.\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eGo\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\ngo get -u github.com/agentcommunity/agent-identity-discovery/aid-go\n```\n\n```go\nimport (\n\t\"fmt\"\n\t\"log\"\n\t\"github.com/agentcommunity/agent-identity-discovery/aid-go\"\n)\n\nfunc main() {\n\tresult, err := aid.Discover(\"supabase.agentcommunity.org\")\n\tif err != nil {\n\t\tlog.Fatalf(\"AID Error: %v\", err)\n\t}\n\tfmt.Printf(\"Found %s agent at %s (TTL: %d)\\n\", result.Record.Proto, result.Record.URI, result.TTL)\n    //=\u003e Found mcp agent at https://api.supabase.com/mcp (TTL: 60)\n}\n```\n\n\u003c/details\u003e\n\n## Monorepo Overview\n\nThis repository uses a PNPM/Turborepo monorepo structure. It contains the full suite of libraries, tools, and documentation for the AID standard.\n\n### Packages\n\n| Package                                                                                              | Status  | Description                                                                          |\n| :--------------------------------------------------------------------------------------------------- | :------ | :----------------------------------------------------------------------------------- |\n| [**@agentcommunity/aid**](https://www.npmjs.com/package/@agentcommunity/aid)                         | Public  | Core TypeScript library for Node.js and Browsers                                     |\n| [**@agentcommunity/aid-engine**](https://www.npmjs.com/package/@agentcommunity/aid-engine)           | Public  | Pure business logic library (discovery, validation, PKA)                             |\n| [**@agentcommunity/aid-doctor**](https://www.npmjs.com/package/@agentcommunity/aid-doctor)           | Public  | Official CLI for checking, validating, and generating AID records (wraps aid-engine) |\n| [**@agentcommunity/aid-conformance**](https://www.npmjs.com/package/@agentcommunity/aid-conformance) | Public  | Conformance suite exporting fixtures and a CLI runner                                |\n| [**aid-discovery (Python)**](https://pypi.org/project/aid-discovery/)                                | Public  | Official Python library                                                              |\n| [**aid-go**](https://pkg.go.dev/github.com/agentcommunity/agent-identity-discovery/aid-go)           | Public  | Official Go library                                                                  |\n| [**aid-rs (Rust)**](./packages/aid-rs)                                                               | Public  | Parser + discovery (handshake behind feature flag)                                   |\n| [**aid-dotnet (.NET)**](./packages/aid-dotnet)                                                       | Public  | Parser + discovery + PKA + well-known                                                |\n| [**aid-java (Java)**](./packages/aid-java)                                                           | Public  | Parser + discovery + PKA + well-known                                                |\n| [**@agentcommunity/aid-web**](./packages/web)                                                        | Private | The Next.js app for the website and workbench                                        |\n| **@agentcommunity/e2e-tests**                                                                        | Private | E2E tests validating our live showcase domains                                       |\n| **(test runners)**                                                                                   | Private | Internal packages for orchestrating Python and Go tests via Turbo                    |\n\n### Project Structure\n\n```\nagent-identity-discovery/\n├── protocol/                  # Protocol constants (YAML source of truth)\n├── scripts/                   # Code generation and utility scripts\n├── packages/\n│   ├── aid/                   # Core TypeScript library (Node.js + Browser)\n│   ├── aid-engine/            # Pure business logic library (stateless)\n│   ├── aid-doctor/            # CLI tool (wraps aid-engine with side effects)\n│   ├── aid-py/                # Python library\n│   ├── aid-go/                # Go library\n│   ├── aid-rs/                # Rust library (parser + discovery; handshake feature)\n│   ├── aid-dotnet/            # .NET library (parser + discovery + PKA)\n│   ├── aid-java/              # Java library (parser + discovery + PKA)\n│   ├── docs/                  # Markdown documentation (rendered at /docs)\n│   ├── web/                   # Next.js web workbench + docs renderer\n│   ├── e2e-tests/             # End-to-end tests\n│   └── (test-runners)/        # Internal test runners for Go/Python\n├── tracking/                  # Development progress tracking (PHASE_*.md)\n├── .github/ARCHITECTURE.md    # Comprehensive architecture documentation\n├── tsconfig.base.json         # Shared TypeScript configuration\n├── tsup.config.base.ts        # Shared build configuration\n└── ...                        # Other configuration files\n```\n\n## Architecture\n\nThis project follows a **production-grade monorepo architecture** designed for long-term maintainability and developer productivity. Our [`ARCHITECTURE.md`](.github/ARCHITECTURE.md) provides comprehensive documentation covering:\n\n- **Build System Decisions**: Why we chose Turbo + tsup over alternatives, with performance benchmarks\n- **Cross-Platform Compatibility**: How we ensure consistent behavior across Windows, Mac, and Linux\n- **Package Organization**: Clear separation of concerns between published libraries and internal tools\n- **Developer Experience**: Standardized commands and hot reloading for rapid iteration\n\n**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.\n\n### CLI Architecture\n\nThe AID CLI follows a **clean architecture pattern** with clear separation of concerns:\n\n- **`@agentcommunity/aid-engine`**: Pure, stateless library containing all business logic (discovery, validation, PKA handshakes)\n- **`@agentcommunity/aid-doctor`**: Thin CLI wrapper that handles user interaction, filesystem operations, and orchestrates the engine\n\n**Why This Separation**:\n\n- **Testability**: Pure functions in aid-engine are easily unit testable\n- **Reusability**: Engine can be consumed by other tools without CLI dependencies\n- **Maintainability**: Side effects are isolated in aid-doctor, business logic stays pure\n- **Performance**: Engine can be used in server environments without CLI overhead\n\n### Constants generation\n\n- Single command: `pnpm gen` reads `protocol/constants.yml` and writes language constants.\n- Currently supported: TypeScript, Python, Go, and optional Rust/.NET/Java (generated only if their package paths exist).\n\n## Development\n\n**Prerequisites:** Node.js (v18.17+), PNPM (v8+)\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/agentcommunity/agent-identity-discovery.git\ncd agent-identity-discovery\n\n# 2. Install dependencies\npnpm install\n```\n\n### Core Monorepo Scripts\n\nThanks to Turborepo's intelligent caching, commands only rebuild what changed.\n\n| Command         | Description                                                      |\n| :-------------- | :--------------------------------------------------------------- |\n| `pnpm dev`      | Start all packages in development/watch mode.                    |\n| `pnpm dev:core` | Start only core libraries (aid + aid-doctor) for focused work.   |\n| `pnpm dev:web`  | Start web interface and its dependencies.                        |\n| `pnpm build`    | Build all packages for production (with intelligent caching).    |\n| `pnpm test`     | Run the entire test suite across all languages (TS, Python, Go). |\n| `pnpm lint`     | Lint and format all code.                                        |\n| `pnpm e2e`      | Run end-to-end tests against the live showcase records.          |\n| `pnpm gen`      | Regenerate constant files from the YAML contract.                |\n| `pnpm clean`    | Remove all build artifacts (`dist`, `.turbo`, etc.).             |\n\n### CI Notes\n\n- Language CI workflows run on every PR and push because they are required checks.\n- Security Scan uses diff mode on PRs and pushes. Scheduled or manual runs scan the full repo.\n\n### The Contract-First Workflow\n\nThe single source of truth for all protocol constants is `protocol/constants.yml`. To update them across all language packages, follow this process:\n\n1.  **Edit the YAML file:** Make your changes in `protocol/constants.yml`.\n2.  **Run the generator:** This command reads the YAML and updates the corresponding files in the TS, Go, and Python packages.\n    ```bash\n    pnpm gen\n    ```\n3.  **Verify and commit:** Run the full test suite and build to ensure everything works.\n    ```bash\n    pnpm clean \u0026\u0026 pnpm build \u0026\u0026 pnpm test\n    ```\n    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.\n\n### v1.2 Release Status: ✅ READY\n\n**Implementation Complete** - All v1.2 features implemented across 6+ languages with comprehensive testing. CLI enhanced with advanced features.\n\n**Ready for Release:**\n\n- ✅ All tests passing (70+ TypeScript tests + Python/Go parity tests)\n- ✅ All builds successful (7/7 packages)\n- ✅ Changesets prepared for version bumps\n- ✅ Release workflow configured (npm + PyPI automation)\n- ✅ Multi-language SDKs ready (TS, Python, Go, Rust, .NET, Java)\n- ✅ Enhanced CLI with draft saving, standardized errors, and full test coverage\n\n**Next Step:** Merge to `main` with `chore(release)` commit message to trigger automated release.\n\n### Development Environment\n\n- **Node.js**: Version 18.17+ required (enforced via `engines` field and `.nvmrc`)\n- **PNPM**: Version 8+ required for workspace support\n- **Cross-Platform**: All scripts work identically on Windows, Mac, and Linux\n- **Hot Reloading**: All packages support watch mode for rapid development\n- **Intelligent Caching**: Turbo only rebuilds packages that actually changed, dramatically speeding up development cycles\n\n### Build Performance\n\nThanks to our production-grade setup:\n\n- **First build**: ~15 seconds for all packages\n- **Incremental builds**: ~1-3 seconds for most changes\n- **Test runs**: Only affected packages run tests\n- **Cross-platform**: Identical behavior on all operating systems\n\n## Community \u0026 Support\n\n- For questions, ideas, and support, join our **[GitHub Discussions](https://github.com/orgs/agentcommunity/discussions)**.\n- Chat with us on **[Discord](https://discord.gg/S5XqVHrj)**.\n- To contribute, please see our **[Contributing Guide](./CONTRIBUTING.md)** and **[Code of Conduct](./CODE_OF_CONDUCT.md)**.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.\n\n**Built by the team at [agentcommunity.org](https://agentcommunity.org)**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentcommunity%2Fagent-identity-discovery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentcommunity%2Fagent-identity-discovery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentcommunity%2Fagent-identity-discovery/lists"}