What Is an Agent Directory?
What is an agent directory? An agent directory is a searchable public catalog that lists AI agents, owners, purposes, endpoints, manifests, proof links, statuses, and policies so humans and other agents can discover, inspect, compare, and verify agents before use.
An agent directory sits between search, identity, and review. Instead of treating an agent name as a loose label, the directory turns the name into a profile with fields. A useful entry names the operator, describes the agent purpose, publishes agent.json or a machine-readable manifest, exposes endpoint metadata, and shows proof links that a verifier can compare.
For human readers, the profile should explain what the agent does, who supports the agent, which policies apply, and whether the listing is active or retired.
For software, the profile should export predictable JSON so another agent can fetch capability, contact, authorization, and lifecycle fields without scraping prose.
A directory is different from a marketplace: the directory helps callers inspect trust signals, while the marketplace helps users install, buy, rate, or promote an agent. The strongest setup links both surfaces back to one canonical identity.
HeadlessDomains.com uses headless names, DNS metadata, public profiles, and API-friendly workflows so agents can resolve and use these records without relying on browser-native DNS. Security teams can review ownership, approval routes, payment policy, and incident contacts before granting access. Builders can publish one profile, then link that profile from docs, catalogs, A2A Agent Cards, MCP endpoints, and listings.
Directory, Marketplace, and Registry
| Surface | Primary job | Best use | Trust signal |
|---|---|---|---|
| Agent directory | Publish searchable public profiles with identity, operator, endpoints, proof links, and status. | Discovery, public inspection, partner review, and pre-call verification. | Canonical name, profile URL, manifest, proof links, and review date. |
| Agent marketplace | Package agents for installs, paid access, ratings, promotions, and platform placement. | Distribution, subscriptions, ranking, checkout, and in-platform support. | Platform policy checks, builder profile, listing history, and reviews. |
| Search index | Return names, pages, or descriptions that match a query. | Broad discovery before a verifier opens a profile. | Ranking signals and page snippets, not a full identity record. |
| Internal registry | Track company-owned agents, owners, permissions, audits, and lifecycle status. | Governance, access review, vendor review, and offboarding. | IAM records, approval logs, owner review, and public profile alignment. |
What Belongs in an Agent Directory Profile
Treat the directory page as an inspection record. Include the canonical name, display name, operator, purpose, status, profile URL, machine-readable manifest, SKILL.md, endpoint docs, auth model, payment policy, proof links, support URL, security contact, and last review date.
If the agent supports peer collaboration, the A2A specification describes Agent Cards for identity, skills, service endpoints, and authentication. If the agent exposes tools, MCP authorization metadata helps callers separate endpoint location from authorization context.
Implementation Checklist
- Choose one canonical public name for each production agent.
- Publish a directory profile with owner, purpose, status, support path, and security contact.
- Link agent.json, SKILL.md, Agent Card, OpenAPI, MCP, policy, payment, and proof URLs.
- Keep private tokens, secret keys, staging hosts, and customer data out of public fields.
- Expose a JSON export with predictable field names and stable URLs.
- Mark renamed, retired, paused, or compromised agents clearly.
- Review the profile after owner, endpoint, capability, payment, or policy changes.
- Link marketplace listings and docs back to the same canonical profile.
Sample JSON Export
A directory entry should be exportable as JSON so another agent can inspect the profile without scraping the page.
{"directory_entry_version":"public-agent-directory.v1","agent":{"canonical_name":"atlas.agent","display_name":"Atlas Procurement Agent","purpose":"Find approved suppliers and draft quote requests.","status":"active"},"operator":{"organization":"Atlas Research LLC","support_url":"https://atlas.example/support","security_contact":"security@atlas.example"},"records":{"profile_url":"https://headlessprofile.com/atlas.agent","agent_json":"https://atlas.agent/.well-known/agent.json","skill_md":"https://atlas.agent/SKILL.md","a2a_agent_card":"https://atlas.agent/.well-known/agent-card.json","mcp":"https://api.atlas.agent/mcp"},"proof":{"dns_txt":"_agent.atlas.agent","signed_manifest":"https://atlas.agent/.well-known/agent.json.jws","reviewed":"2026-05-21"}}Where HeadlessDomains.com Fits
HeadlessDomains.com gives an agent directory a persistent identity anchor. A Headless Domains name can connect the public profile, DNS TXT metadata, agent.json, SKILL.md, A2A Agent Card, MCP endpoint, payment policy, and marketplace listings so each surface points back to one verifiable record.
Start by registering a .agent identity, then list the same profile in the Headless Profile Directory.
Use the Agent Directory hub for the broader model behind profiles, records, endpoint links, and proof paths.
FAQ
Is an agent directory the same as an agent marketplace?
No. An agent directory focuses on discovery, public inspection, ownership, endpoints, and proof links. An agent marketplace focuses on installs, paid access, platform placement, ratings, and transaction flows.
What fields belong in an agent directory profile?
A profile should include canonical name, operator, purpose, status, manifest URLs, endpoint docs, auth model, policy links, proof links, support route, security contact, and review date.
What does the JSON export do?
The JSON export gives another agent a structured version of the same public profile. The export should preserve identity, owner, endpoint, proof, lifecycle, and contact fields with stable URLs.
How does Headless Profile Directory help?
Headless Profile Directory gives a .agent identity a public profile page that humans and compatible agents can inspect before a marketplace listing, partner integration, endpoint call, or payment route depends on the agent.