A second business unit at the insurer has built its own agents. Its intake agent needs a roof assessment for a submission, and it knows that "some agent in the underwriting department" collects evidence. It does not know that agent's address, which requests it accepts, whether it can stream updates, or what token it expects. Today someone answers those questions by sending a message in a chat channel, and someone else pastes a URL into a configuration file.
That works for one pair of agents. It does not work for twenty, and it fails quietly when the evidence agent moves to a new address or starts requiring a different scope. The first business unit's configuration still points at the old URL, and every request now ends in a connection error with no explanation.
Before an agent can ask, it must find whom to ask and learn what that agent accepts. This page is about how agents describe themselves so that others can find them, and about the gap between a description and the truth.
Discovery in plain words#
Discovery is how a caller finds an agent that can do a piece of work, and learns how to reach it. For example, the caller has the need "roof assessment" and ends up with the address https://agents.insurer.example/assessment and the scope evidence:read.
An Agent Card is the document in which an agent says who it is, where it lives, what skills it offers and how to authenticate. The name is the A2A protocol's; the idea is older. For example, the assessment agent's card in the example says its name, a description, one interface URL, its security scheme and one skill.
A skill is one capability an agent advertises in its Agent Card, with an id, a name, a description, tags and examples. For example, the skill collect-evidence, tagged evidence, roof_assessment, guidance, similar_decisions, underwriting. A skill is a promise about the kind of request the agent accepts; it is not a function you call.
A capability, in an Agent Card, is a protocol feature the agent supports, as opposed to a skill it offers. For example, "this agent can stream updates" or "this agent can send push notifications". Skills say what work; capabilities say how the exchange can run.
Plain English. An Agent Card is a business card with a menu on the back. The front says who the agent is, where to find it and which badge you need at the door. The menu lists what it cooks. Nobody has tasted the food yet.
The smallest primitive: a card at a known address#
The smallest discovery mechanism is a document each agent publishes at an address everyone can compute. A well-known URI is such an address: a fixed path under a domain, defined by a standard, so that a client can find a document without being told where it is. The A2A specification, read today, puts the Agent Card at https://{agent-server-domain}/.well-known/agent-card.json.
The A2A documentation describes three ways to find a card. The well-known URI suits public agents and broad discovery inside a domain. A registry is a central catalog that holds Agent Cards and lets clients search them, for example by skill or tag; the documentation notes that the current specification does not define a standard registry API. And direct configuration means the client is given the card or its URL in a file or a setting, which suits a small, stable system but needs reconfiguring whenever a card changes.
These are the three cards of the example, matched against a need by cards.py:find_agent. The rule is simple: the skill whose tags share the most words with the need wins; ties go to the first card by name.
Diagram: From a need to an address · discovery in three steps
Read left to right. The caller has a need. It reads the Agent Cards it may use, from a well-known address, a registry or its configuration. It matches the need against the skills the cards claim and gets an address and a security scheme. Only the request itself shows whether the claim is true.
- The caller's need
- roof_assessment: The work the caller wants done, in words the cards can be matched against.
- Where cards come from
- Well-known address: A fixed path under the agent's domain, defined by the A2A specification. Suits public agents and discovery inside a domain.
- Registry: A central catalog searched by skill or tag. The A2A documentation read today says no standard registry API is defined.
- Configuration: The card or its address in a file or setting. Simple and static; every change needs reconfiguring.
- Match
- Skill tags: Each skill's tags are compared with the words of the need; the best match gives the agent, its skill and its address.
- Honored?: Whether the agent's code really serves the matched tags (cards.py:HONORS). The card cannot tell you; a request can.
The insurance example: the three cards#
The example's cards are in examples/uw-agents/cards/. Their top-level fields follow the names of AgentCard and AgentSkill in the A2A specification, version 1.0.0; the nested shapes inside the interfaces and security fields are simplified, and the cards are not validated against an official schema. This is the skill block of the assessment agent's card, verbatim:
{
"id": "collect-evidence",
"name": "Collect evidence",
"description": "Calls the roof-data provider, the guidance index and the past-decisions store, and returns one evidence artifact (evidence.artifact/v1) with gaps named.",
"tags": ["evidence", "roof_assessment", "guidance", "similar_decisions", "underwriting"],
"examples": ["Collect the evidence for SUB-1004: roof_assessment, guidance, similar_decisions"]
}
The card also declares one interface (https://agents.insurer.example/assessment, JSON-RPC), the capabilities streaming: false and pushNotifications: false, an OAuth 2 client-credentials scheme with the scope evidence:read (illustrative: no identity provider exists in the example), and JSON as its input and output mode.
An executable demonstration: a claim the agent cannot honor#
The example records, next to the cards, what each agent's code really serves (cards.py:HONORS). That lets it show the gap this page is about. The script below, run from the example folder, checks the cards, matches three needs, then edits the underwriting agent's card to claim a tag its code does not serve:
import copy
from cards import load_cards, find_agent, card_problems
cards = load_cards()
for name, card in cards.items():
print(name, [s["id"] for s in card["skills"]], "problems:", card_problems(card))
for need in ("roof_assessment", "recommendation", "pricing"):
print(need, "->", find_agent(need, cards))
edited = copy.deepcopy(cards)
edited["underwriting-agent"]["skills"][0]["tags"] += ["pricing"]
print("edited: pricing ->", find_agent("pricing", edited))
assessment-agent ['collect-evidence'] problems: []
intake-agent ['take-submission'] problems: []
underwriting-agent ['write-recommendation'] problems: []
roof_assessment -> {'agent': 'assessment-agent', 'skill': 'collect-evidence', 'matched_tags': ['roof_assessment'], 'url': 'https://agents.insurer.example/assessment', 'honored': True}
recommendation -> {'agent': 'underwriting-agent', 'skill': 'write-recommendation', 'matched_tags': ['recommendation'], 'url': 'https://agents.insurer.example/underwriting', 'honored': True}
pricing -> None
edited: pricing -> {'agent': 'underwriting-agent', 'skill': 'write-recommendation', 'matched_tags': ['pricing'], 'url': 'https://agents.insurer.example/underwriting', 'honored': False}
Before the edit, nobody claims pricing, and discovery fails early and cheaply: the caller learns before sending anything that no agent offers it. After the edit, discovery succeeds, the caller gets an address, and the request would go to an agent whose code has no idea what to do with it. The card was well formed (card_problems found nothing). It was simply wrong. A description is a claim, not a guarantee.
Try it in the lab: pick a need, read which card matches and whether its code honors it, then switch on the edited card.
| Need | Matched agent and skill | Honored by its code? |
|---|---|---|
roof_assessment | assessment-agent, collect-evidence | yes |
guidance, similar_decisions | assessment-agent, collect-evidence | yes |
recommendation, eligibility, escalation | underwriting-agent, write-recommendation | yes |
intake | intake-agent, take-submission | yes |
pricing, translation | no card | no request is sent |
pricing, with the edited card | underwriting-agent, write-recommendation | no: the claim is false |
A failure mode: trusting the menu#
There are three ways a card misleads, and each needs a different defense.
A stale card describes an agent as it was. The skill was removed in the last release, or the address moved, but the card was not regenerated. Defense: generate the card from the same code and configuration that serve requests, and version it.
An optimistic card describes what the team hopes the agent can do. The tags were written by a person, broadly, to be found. Defense: test each advertised skill with a real request in CI, the way the example compares HONORS with the tags.
A hostile card describes an agent that wants to receive requests it should not: it claims every skill, so that callers send it their submissions. Defense: do not let anyone publish a card into a place where your agents will trust it. A card says what an agent claims; who is allowed to publish, and whether the card is signed by someone you trust, decides whether you believe it.
Production pitfall. A registry that ranks agents by matching their descriptions with a model is a search engine over self-written text. It inherits every weakness of search engines, including descriptions written to be found. Allow-list the agents a caller may use, then let discovery choose among them.
Before AI. Service discovery is old: DNS SRV records, a Consul or Eureka registry, a Kubernetes Service name, an OpenAPI document at a known path. Agent Cards combine two things those systems kept apart: where a service is (the registry's job) and what it does (the API description's job). The same lesson applies: the registry entry is only as true as the process that writes it.
How the A2A protocol defines Agent Cards#
The A2A specification, version 1.0.0, read today, defines an AgentCard with the required fields name, description, supportedInterfaces (an ordered list; the first entry is preferred), version, capabilities, defaultInputModes, defaultOutputModes and skills, and the optional fields provider, documentationUrl, securitySchemes, securityRequirements, signatures and iconUrl. An AgentSkill requires id, name, description and tags, and may have examples, inputModes, outputModes and securityRequirements. AgentCapabilities holds streaming, pushNotifications, extensions and extendedAgentCard.
Two parts of the specification address the trust problem. Cards can be signed with JSON Web Signature (RFC 7515) over a canonical form of the card (RFC 8785, with the signatures field excluded); clients must canonicalize and verify, and should verify at least one signature before trusting a card. And an agent can offer an extended Agent Card to authenticated clients (GetExtendedAgentCard), so the public card need not reveal sensitive skills or URLs. A signature proves who published the card and that it was not altered; it does not prove that the agent honors it. The protocol's other parts are on A2A.
What this is not. Discovery finds an agent and its contract. Describing a single callable function for a model, the tool schema, is a different document and belongs to tools.sammuthu.com. How the model decides which tool or agent to use from those descriptions is a question of context and instructions, owned by context.sammuthu.com and prompt.sammuthu.com.
Checklist: a card review#
- Is every card generated from the code and configuration that serve requests, and versioned?
- Does each advertised skill have a test that sends a real request and checks the result?
- Are the card's address, security scheme and scopes the ones the agent enforces?
- Who may publish a card where your callers look, and do callers verify a signature?
- Do callers allow-list the agents they may use, and let discovery choose only among them?
- Do sensitive skills appear only in an extended card behind authentication?
- Do clients cache cards and revalidate them, so an address change propagates?
The same idea for a coding agent. A planning agent looks for "an agent that can run the integration tests". Two cards claim the skill: the test agent, and a new agent from another team that in fact runs only unit tests. The planning agent picks the second, gets a green result, and the pull request is merged with a broken integration. A skill test in CI ("send it an integration-test request and check that the integration suite ran") would have caught the claim. The runtime of each agent is the subject of harness.sammuthu.com.
Matching by tags, by description, or by contractThree matchers and what each can be fooled by
The example matches by tags: exact words, counted. It is predictable, testable and easy to fool by adding tags. Matching by description with a model handles synonyms and vague needs, and is harder to test and easier to game with persuasive text. Matching by contract, "which agents accept evidence.request/v1 and return evidence.artifact/v1", is the strictest and the most useful for automation, because the request a caller sends must fit a schema anyway.
A layered design uses all three: an allow-list decides who may be called at all, the contract narrows to agents that accept the request schema, and tags or descriptions break ties. The weakest layer then only chooses among candidates that the stronger layers already accepted.
What a signature does and does not proveAuthenticity of the document, not truth of its claims
A signed card answers: who published this, and has it changed since? That closes the hostile-card attack where a third party publishes a card in someone else's name, and the tampering attack on a card in transit or in a cache. It does not answer: does this agent do what the card says? A signature by a team that writes optimistic cards proves only that the optimism is authentic.
So a trust decision has two parts. Trust in the publisher (a key you hold, a key served from a domain you trust, a key pinned in configuration), and evidence about the agent (skill tests, past behavior, an evaluation). The second is measurement and belongs to eval.sammuthu.com.
Caching cardsFresh enough to follow a move, cheap enough to read often
A caller that fetches a card before every request doubles its traffic; one that fetches it once at start never notices a move. The A2A documentation read today recommends that servers send Cache-Control with a max-age and an ETag derived from the card's version or a content hash, and that clients revalidate with conditional requests when the cache expires. A sensible addition is to refetch the card when a request fails in a way that suggests the card is stale: a connection error to the advertised address, or an authentication error with the advertised scheme.
In one breath#
Discovery is how a caller finds an agent and learns how to reach it. An Agent Card describes an agent: identity, address, skills, capabilities and security, published at a well-known address, in a registry, or by configuration. A card can be stale, optimistic or hostile; a signature proves who published it, and only tests prove what the agent does. A description is a claim, not a guarantee.
Next: the last five pages used generic words, task, card, artifact, and pointed to one standard that writes them down. A2A reads that standard on its own specification: its history, data model, operations, bindings and what interoperability does and does not give.