An agent discovering Connect

The card, and what it commits to#

Discovery is deliberately boring: one GET of /.well-known/agent-card.json, no negotiation, no registration. The card names the agent, gives a version, lists the skills, and declares the input modes it accepts. It also declares what it does not do — streaming and push notifications are both false — because an unstated capability is a capability a caller will try.

Discovery to answer, stage by stage#

1. Trigger — an agent is asked about Connect, or is told to find a service that handles business communication.
2. External event — the agent fetches the Agent Card over HTTPS from the well-known path.
3. Authentication and workspace resolution — none. The card and the public skills are open, and no workspace is addressable through them.
4. Request — the caller sends a message naming a skill. A caller that names no skill is routed by the shape of its question rather than refused.
5. Canonical record — nothing is written. Discovery leaves no row.
6. Classification — the routing step: a question about availability goes to capability status, one about a process goes to the workflow skill, one mentioning a protocol or a key goes to integration.
7. Knowledge, memory and rules — the published documentation and the capability registry, which is the only place status words come from.
8. Autonomy and approval — not applicable. No public skill can act.
9. Action — the skill reads generated pages and assembles a reply.
10. Result — a text part with the answer, plus a data part carrying the page URL, its status and any near matches, so a machine does not have to parse prose.
11. Relationship, timeline and memory — none. The calling agent is not a contact.
12. Audit, usage and Needs You — operational logging only; no workspace ledger and no queued item.

The routing step is worth understanding rather than working around. An agent that discovered the card from a well-known URI frequently sends its first question without reading the skill list, and refusing that is worse for both sides than picking the closest skill and saying which one answered.

What an integrating agent should rely on#

• The well-known path. It is stable, and it is the only entry point that needs to be configured.
• The declared capability flags. If the card says streaming is unsupported, no amount of retrying produces a stream.
• The data part of a reply, rather than the text, when a machine is consuming the answer. The page URL and the status word are there in a fixed shape.
• The status vocabulary. Available, foundation and not-yet are distinct claims, and an agent that flattens them into supported will mislead its user.

When discovery fails#

The card is unreachable

Usually an edge rule rather than the application: a bot filter or a challenge page in front of the site answers a machine differently from a browser. Fetching as the exact user agent is the only way to see it.

The card parses but names no skill you wanted

That is the honest state of the public surface. The workspace surfaces are reached with a key, not by asking the card for more.

A skill answers that nothing matches

The corpus has no page on that subject. Treat it as undocumented rather than as unsupported — they are different, and the capability status tool distinguishes them.

A reply looks stale

Every page carries the date its claims were verified. Compare that rather than assuming the newest answer is current.

Questions#

Related#

• The Connect Agent Card
• Interoperating over A2A
• An AI client searching the public documentation
• Protocol reference
• The machine-readable documentation
• Verifying a bot is who it claims