# A2A agent discovery A2A describes three discovery strategies: fetch a card from a well-known URI on a known domain, look the agent up in a curated registry, or be configured with its address directly. They differ in who vouches for the agent. Connect supports the first, serving its card at `/.well-known/agent-card.json`. - **Status:** Reference - **Audience:** developer - **Last verified:** 2026-09-10 - **Canonical:** https://connectbyjbrh.com/docs/protocols/a2a-discovery/ ## The three strategies | Strategy | You start with | Who vouches for the agent | |---|---|---| | Well-known URI | A domain name | The domain — DNS and its certificate | | Curated registry | A registry you already trust | Whoever operates the registry | | Direct configuration | A URL somebody gave you | The person or process that configured it | The differences are about trust rather than mechanics. All three end with the same JSON document and the same `message/send` call; what changes is what your confidence in it rests on. **Well-known URI** — You know a company and want to know whether it has an agent. Fetch `https:///.well-known/agent-card.json`. Because the path is fixed by convention, no prior arrangement is needed — the domain's own TLS certificate is the evidence that the card belongs to that organisation. **Curated registry** — You do not know who can answer, and you want candidates. A registry — an enterprise catalogue, a marketplace — holds cards and lets you search them. Convenient, and it moves the trust decision to the registry operator's admission policy. **Direct configuration** — You already know the agent, usually because it is yours or a partner's. The URL is in configuration, sometimes with a private card that is never published. This is the common case inside one organisation and the least interesting one to standardise. ## Why the well-known path is the one that scales A registry requires an operator, an admission policy and a reason for everyone to agree on the same registry. Direct configuration requires a human on both sides. The well-known URI requires nothing but the domain you already have, which is why it is the strategy an agent can attempt against any organisation it hears about. It also fails cleanly. A domain with no agent returns `404` and the caller learns something definite in one request. What it cannot do is tell you an agent is *good* — the certificate proves the document came from that domain, not that the skills work. That is what a small first message to a cheap skill is for. > **Note** Discovery is not authorisation. Finding one tells you where to send a message; it says nothing about what the agent will let you do. Connect's card describes five read-only documentation skills and no credential unlocks anything beyond them. ## Does Connect use these discovery strategies? One of the three, as a publisher. Connect serves its card at `/.well-known/agent-card.json`, so any agent that knows the domain can find it without prior arrangement. The response carries `Access-Control-Allow-Origin: *` and a five-minute cache directive, so a browser-based agent can read it too. The earlier draft path `/.well-known/agent.json` also answers, with a `Link` header naming the current path as canonical, so an agent built against that draft finds Connect rather than concluding it speaks no A2A. Connect does not publish to a registry, does not operate one, and does not perform discovery itself — it is a server on this protocol, not a client, so it never goes looking for other agents' cards. If a registry you use lists Connect, the listing was made by whoever runs that registry. There is no private or authenticated variant to discover. The card declares `supportsAuthenticatedExtendedCard: false`, so the public card is the entire advertised surface — see [The A2A Agent Card](/docs/protocols/agent-card/). ## Discovering Connect, step by step 1. `GET https://connectbyjbrh.com/.well-known/agent-card.json`. - Result: The document, as `application/json`, cacheable for five minutes. 2. Read `url` and `skills` from it. - Result: You have the endpoint and the five skill ids you may name. 3. Send one `message/send` with a short question. - Result: A reply of kind `message`. If this fails, the card is describing something that is not currently answering, which is worth knowing before you build on it. Two failure modes are worth anticipating. A cached copy can outlive a change, so a `-32004` naming skills you do not recognise means re-fetch rather than retry. And one served from a domain you reached over plain HTTP proves nothing at all — the trust in this strategy is entirely in the certificate. ## Questions ### Does Connect appear in any agent registry? Not through anything Connect publishes. The card at the well-known URI is the only discovery surface Connect operates. A third-party registry may list it; that listing is the registry's, and its accuracy is the registry's responsibility. ### Can I discover an agent from an email address or a company name? Only by turning it into a domain first and trying the well-known path. There is no directory lookup in the protocol itself, which is exactly why the registry strategy exists as an alternative. ### Is the well-known path guaranteed to be the same on every agent? For A2A 1.0.0 the path is `/.well-known/agent-card.json`. Some agents built against the earlier draft still serve `/.well-known/agent.json`; Connect answers both, but a caller should try the current path first. ## Related - [The A2A Agent Card](https://connectbyjbrh.com/docs/protocols/agent-card/) - [A2A — the Agent2Agent protocol](https://connectbyjbrh.com/docs/protocols/a2a/) - [Well-known URIs](https://connectbyjbrh.com/docs/protocols/well-known-uris/) - [Interoperating over A2A](https://connectbyjbrh.com/developers/a2a-integration/) - [Verifying a bot is who it claims](https://connectbyjbrh.com/developers/bot-verification/) ## What this page is based on - https://a2a-protocol.org/latest/specification/ - `backend/app/a2a_server.py` — the well-known routes, headers and legacy alias - `docs-source/facts.py` — PROTOCOLS['a2a']