Skip to content

Chapter 7.5 — Communicating breaking changes

🎯 Objective

Treat breaking-change communication as an engineering discipline, not a late email. In AI, a breaking change hits not only external customers: agents, MCP servers, A2A peers and internal teams also suffer.

🛡️ Best practices

  • A public changelog with semver respected.
  • Clear release notes describing what changes, why, and what the alternative is.
  • A migration guide with before/after examples.
  • A minimum announced window (4–12 weeks, depending on impact).
  • Support for previous versions for a defined time (not "indefinitely").
  • Alerts for consumers still on the old version: email, Slack, dashboard, or — in internal systems — a runtime warning.
  • Progressive blocking for new consumers before total shutdown (see Ch. 3.7.3 and 7.4).
  • A public ADR documenting the decision and the path.

🧠 Particularities in agent systems

  • When a tool changes, all agents that use it must be re-evaluated, not just the "target" agent.
  • When an output schema changes, all downstream consumers depend on dual-support while they migrate.
  • When an MCP server changes capabilities, agents that depended on them may fail silently — it needs per-agent regression eval.
  • When an A2A Agent Card changes the contract, peers need a minimum window and explicit versioned capabilities.