{"id":29949728,"url":"https://github.com/agentcommunity/agent-interface-discovery","last_synced_at":"2025-08-03T10:05:07.568Z","repository":{"id":303069717,"uuid":"1014307697","full_name":"agentcommunity/agent-interface-discovery","owner":"agentcommunity","description":"Agent Interface Discovery ","archived":false,"fork":false,"pushed_at":"2025-07-21T09:30:16.000Z","size":576,"stargazers_count":3,"open_issues_count":11,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-01T12:42:54.038Z","etag":null,"topics":["a2a","agent","llm","llm-agent","mcp"],"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}},"created_at":"2025-07-05T13:08:18.000Z","updated_at":"2025-07-17T15:05:28.000Z","dependencies_parsed_at":"2025-07-05T14:29:47.840Z","dependency_job_id":"88df392f-c69d-47d3-b7a3-54680ef18ed2","html_url":"https://github.com/agentcommunity/agent-interface-discovery","commit_stats":null,"previous_names":["agentcommunity/agent-interface-discovery"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/agentcommunity/agent-interface-discovery","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentcommunity%2Fagent-interface-discovery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentcommunity%2Fagent-interface-discovery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentcommunity%2Fagent-interface-discovery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentcommunity%2Fagent-interface-discovery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agentcommunity","download_url":"https://codeload.github.com/agentcommunity/agent-interface-discovery/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentcommunity%2Fagent-interface-discovery/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268525073,"owners_count":24264095,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-03T02:00:12.545Z","response_time":2577,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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","llm","llm-agent","mcp"],"created_at":"2025-08-03T10:02:28.077Z","updated_at":"2025-08-03T10:05:07.560Z","avatar_url":"https://github.com/agentcommunity.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Agent Interface 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/agent-community/agent-interface-discovery/actions/workflows/ci.yml\"\u003e\n      \u003cimg src=\"https://github.com/agent-community/agent-interface-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-interface-discovery?style=flat\u0026label=AID%20Version\u0026color=orange\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/package-json/v/agentcommunity/agent-interface-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/agent-community/agent-interface-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[AID website](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## 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** | **[docs.agentcommunity.org/aid](https://docs.agentcommunity.org/aid)** | Read the full specification, guides, and API reference.                        |\n| **Command-Line Tool**      | `npm install -g @agentcommunity/aid-doctor`                            | The quickest way to check and generate AID records from your terminal.         |\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\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-interface-discovery/aid-go\n```\n\n```go\nimport (\n\t\"fmt\"\n\t\"log\"\n\t\"github.com/agentcommunity/agent-interface-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-doctor**](https://www.npmjs.com/package/@agentcommunity/aid-doctor)  | Public  | Official CLI for checking, validating, and generating AID records |\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-interface-discovery/aid-go) | Public  | Official Go library                                               |\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-interface-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-doctor/            # CLI tool\n│   ├── aid-py/                # Python library\n│   ├── aid-go/                # Go library\n│   ├── web/                   # Next.js web workbench\n│   ├── e2e-tests/             # End-to-end tests\n│   └── (test-runners)/        # Internal test runners for Go/Python\n├── tracking/                  # Development progress tracking (PHASE_*.md)\n├── 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`](./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## 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-interface-discovery.git\ncd agent-interface-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### 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### 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentcommunity%2Fagent-interface-discovery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentcommunity%2Fagent-interface-discovery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentcommunity%2Fagent-interface-discovery/lists"}