CSE Roadmap

Common tier · about 6 hours · 10 parts

Part 3 of 10 · 5 min read

The Agent Card

A business card tells you what someone says they do. Anyone can print one, so you check before you trust it; nobody treats the card itself as proof.

In plain words: an Agent Card is a claim made by whoever served it, and the only part a client can actually verify is a signature made with a key the client already trusts.

An agent publishes a JSON Agent Card at /.well-known/agent-card.json. The one in the example is for a venue-finding agent:

{ "name": "Venue Finder", "version": "1.0.0",
  "supportedInterfaces": [
    {"url": "https://venue.example/a2a/v1", "protocolBinding": "JSONRPC",   "protocolVersion": "1.0"},
    {"url": "https://venue.example/rest",   "protocolBinding": "HTTP+JSON", "protocolVersion": "1.0"} ],
  "capabilities": {"streaming": true, "pushNotifications": true, "extendedAgentCard": true},
  "securitySchemes": {"bearer": {"httpAuthSecurityScheme": {"scheme": "Bearer"}}},
  "skills": [{"id": "find-venue", "name": "Find a venue", "description": "...", "examples": ["..."]}] }

Anyone can write JSON that looks exactly like this for an agent they do not run. The only thing that tells a signed card from a fabricated one is the signature itself. It is checked against a key the client collected in advance, never a key fetched from inside the card:

# from code/mini-a2a/card.py
def verify(card: dict, trusted_keys: dict, allowed_algs=("HS256",)) -> str:
    sigs = card.get("signatures") or []
    if not sigs:
        raise CardError("card is not signed")
    body = {k: v for k, v in card.items() if k != "signatures"}
    payload = _b64(canonical(body))
    last = "no signature could be checked"
    for s in sigs:
        try:
            hdr = json.loads(_unb64(s["protected"]))
        except (KeyError, ValueError):
            last = "malformed protected header"
            continue
        if hdr.get("alg") not in allowed_algs:
            last = f"algorithm {hdr.get('alg')!r} is not accepted"          # this is what stops the `alg: none` trick
            continue
        key = trusted_keys.get(hdr.get("kid"))
        if key is None:
            last = f"key {hdr.get('kid')!r} is not trusted"
            continue

Read it as: the function never fetches a key from the card itself. trusted_keys is the client's own store. So a forged card can sign itself with a key of its own. The verifier correctly reports that key as untrusted rather than accepting it.

Agent Card, signed card

An Agent Card is the public JSON document an agent serves describing its name, skills, interfaces and security schemes. A signed card adds a JWS signature over the card's contents, checked against keys the client provisioned in advance. Example: an attacker's card, signed with the attacker's own key, verifies successfully against the attacker's key but fails against the client's trusted-key store, which is the only check that matters.

Three more things to take from it. Discovery: the client fetches the card and checks that required fields are present. It picks the first interface in the card that it can speak. The specification gives that order to the agent, not the client. The choice: a card with no usable interface is an error that says so. It is not a silent fall-back to a default URL. Caching: a client that fetches the card before every call spends one request in two on something that rarely changes. With a cache and a conditional request (ETag, If-None-Match, answer 304), 20 calls cost 2 card requests, one full and one empty. Without them they cost 20 full ones.

What a client can do with 'trust'

The example builds a routing step, which picks the agent whose card best matches a request (words weighted by how rare they are across cards). Then it adds a rogue agent whose card claims to do everything.

Routing policy Requests that went to the rogue Requests routed correctly (of 6)
Trust any card 6 0
Only cards signed with a key the example provisioned 0 6
The same, but one honest agent's key was never provisioned 0 4 (2 had nowhere to go)

Two honest notes. The first rogue card, which only listed topics, won nothing: the router preferred the real agents. It won only after the honest agents' vocabulary was copied into its card, which costs an attacker nothing, so the result is what you should expect. And the third row is the price of the defence: refusing unsigned cards also refuses real agents whose keys you have not collected.

Treat card changes as events

A card's description is text that a language model may read. A card that gains a skill, or whose skill description is edited, can change what an agent is sent. The example's card_diff flags a new skill, a changed skill, a new endpoint or a changed security scheme, and a client should hold for review on any of them instead of following silently.

A client was written from an older draft of the protocol and run against the 1.0 server:

What the old description says What a 1.0 server did
Card at /.well-known/agent.json 404
Method sendTask -32601 (method not found)
(no version header at all) -32009 VersionNotSupported

upgrade_book_card converts an old card and returns notes about what it changed or could not carry over. This is the reason the module's date is in the title page: protocols that are this new drift, and a book is a snapshot.