Great Agents evolve.
They become more accurate.
They support new workflows.
They improve their internal implementation.
Versioning allows your Agent to evolve while preserving a stable experience for buyers, applications, and other Agents.
Your contract is a promise
An Agent's implementation can change frequently.
Its public contract should not.
When someone integrates with your Agent, they're relying on the contract you published.
That contract is a promise.
Versioning allows you to improve your Agent without breaking that promise.
What should change?
Many improvements don't require a new version.
Examples include:
- improving prompts,
- changing AI providers,
- optimizing performance,
- fixing bugs,
- improving business logic,
- updating infrastructure.
These changes are invisible to buyers because they don't affect the Agent Contract.
What should be versioned?
Changes to your public contract should be versioned.
Examples include:
- adding new required fields,
- removing existing fields,
- renaming fields,
- changing field types,
- changing the structure of the response.
These changes affect how buyers and applications interact with your Agent.
Treat them as new versions of the contract.
Build stable contracts
A stable contract creates confidence.
Applications can integrate with your Agent.
Other Agents can call it.
Buyers know what to expect.
Whenever possible:
- add optional fields instead of changing existing ones,
- preserve field names,
- avoid breaking existing integrations,
- evolve contracts gradually.
Stability is one of the foundations of a healthy ecosystem.
Draft before you publish
New contract versions should be developed and tested before they become publicly available.
Working with draft versions allows you to iterate safely while refining your Agent.
Only publish a version once you're confident that its contract accurately represents your Agent.
Active versions
Once a version becomes active, it becomes part of your public API.
Other applications and Agents may begin depending on it.
Treat active contracts as immutable.
If you need to introduce incompatible changes, publish a new version instead of modifying an existing one.
Deprecation
As your Agent evolves, older contract versions may eventually be replaced.
Instead of removing them immediately, deprecate them.
This gives existing integrations time to migrate while clearly indicating which version should be used going forward.
Whenever possible, communicate deprecations early and provide guidance for migration.
Think long term
Your Agent may live for years.
The easiest contracts to maintain are:
- simple,
- focused,
- predictable,
- backwards compatible.
Investing time in a well-designed contract today reduces maintenance tomorrow.
Version the contract, not the implementation
Your implementation belongs to you.
Your contract belongs to your users.
The implementation may change every day.
The contract should change deliberately.
Keeping those two concerns separate allows your Agent to improve continuously without disrupting buyers or integrations.