A2A DISCOVERY · CARDS CHANGE
Agent Card discovery: trace changes over time
A remote agent changes its Agent Card three times in 45 minutes; follow five client calls through a cached card and see which ones go stale.
Your experiment
The client calls lookup at 5, 22 and 45 minutes and refund at 12 and 31 minutes. The card gains a refund skill and a new endpoint at 10 minutes, the old endpoint is switched off at 20, and OAuth 2.0 replaces the API key at 30. Start with a 30-minute cache and no refetch.
Play replays the computed run over sixty inspection seconds; Next event steps, Restart rewinds, Speed changes the pace and Inspection time scrubs. Any input change recomputes the run and rewinds it without autoplay.
Event trace
Computed data
Final metrics
Timeline model with a fictional agent at agents.example. Revalidation sends the stored ETag and receives 304 Not Modified when the card is unchanged. A skill missing from the cached card is not an error the client sees, so refetch-on-error cannot help it. No network request is made.
A card is a snapshot
The remote agent publishes its Agent Card at /.well-known/agent-card.json. At 10 minutes card v2 adds a refund skill and moves the endpoint; at 20 minutes the old endpoint is switched off; at 30 minutes card v3 requires OAuth 2.0 instead of an API key. The client calls lookup at 5, 22 and 45 minutes and refund at 12 and 31. With a 30-minute cache it keeps the v1 card until 45 minutes: the 12-minute refund call thinks the skill does not exist, the 22-minute call hits the switched-off endpoint, and the 31-minute refund call again sees no refund skill: STALE CARD, 2 of 5 calls succeed.
Shorter lifetimes follow the changes
Set Client card cache lifetime to 10 minutes: the card is refreshed at 22 minutes, so lookup works, but the 31-minute call still uses v2 and is rejected with 401 because auth changed: 3 of 5. At 5 minutes, or with Use the server’s Cache-Control max-age instead checked, the client revalidates before every call and all 5 succeed with 5 fetches, 2 of them answered 304 Not Modified. At 60 minutes only the first call succeeds.
Refetch on error is a partial fix
With the 30-minute cache, check Refetch the card after a connection or auth error. The 22-minute connection failure triggers a refetch to v2 and a successful retry; the 31-minute 401 triggers a refetch to v3 and succeeds too: 4 of 5. The 12-minute refund call still fails, because a skill missing from a stale card is not an error the client sees; it simply routes the request elsewhere.
Let the server set the lifetime
The publisher knows how often its card changes and says so with max-age and an ETag. Revalidating with If-None-Match costs a small request that usually returns 304, so honouring a short max-age is cheap. Combine it with refetch on connection and authentication errors for changes that happen between revalidations.
Reading the run and its limits
Play, Next event, Restart, Speed and Inspection time step through every card fetch and call across sixty seconds, with the simulated minute as each event’s stage; the table shows the live card and the card the client actually used for each call. The agent, URLs and timeline are fictional, the network never fails and card signatures are not modelled.