Why AI Agent APIs Need Semantic Versioning

Schema versioning is one of the most important and most overlooked aspects of building an AI agent API. Without it, a small change to your agent's input format silently breaks every consumer who has integrated against it.

The Problem

Say you build a code review agent. Your initial input schema:

{
  "type": "object",
  "properties": {
    "code": { "type": "string" }
  },
  "required": ["code"]
}

Three months later you want to accept a diff format instead of raw code, and you rename the field:

{
  "type": "object",
  "properties": {
    "diff": { "type": "string" }
  },
  "required": ["diff"]
}

Every consumer who was passing code now silently fails. Their code still runs. The API still accepts the request. But the agent returns garbage output because it got an unexpected input shape.

This is a breaking change — and without versioning, there's no way for consumers to know it happened or pin to the old schema.

The Versioning Pattern

Runcept supports slug@version routing:

agent: "code-reviewer@1"   → your v1 schema
agent: "code-reviewer@2"   → your v2 schema
agent: "code-reviewer"     → latest (always current major)

When you publish a breaking schema change, bump the version. Old consumers continue working against @1. New consumers use @2. You notify consumers to migrate, set a deprecation timeline, then eventually sunset the old version.

What Counts as a Breaking Change

Breaking (bump major version):

• Removing a field
• Renaming a field
• Changing a field's type
• Adding a required field

Non-breaking (no version bump needed):

• Adding an optional field to input schema
• Adding fields to output schema
• Changing how the agent processes input internally
• Updating the model it uses

Implementation for Builders

When you register an agent on Runcept, include a version in your slug:

Initial registration: slug "code-reviewer@1"
After breaking change: register "code-reviewer@2"

Keep @1 running until you're confident consumers have migrated. Set a deprecation date in the agent description.

Consumer-Side Versioning

Pin to a specific version in your code:

// Explicit version pin — safe from breaking changes
const result = await runAgent('code-reviewer@1', { code: diff })

// No version pin — gets the latest, may break
const result = await runAgent('code-reviewer', { code: diff })

When you're ready to upgrade:

1. Read the v2 changelog on the agent's marketplace page
2. Update your input to match the v2 schema
3. Update the agent call to @2
4. Test
5. Deploy

The Deprecation Lifecycle

Week 0:  v2 published, v1 still active
Week 2:  Email to consumers using v1
Week 6:  v1 marked deprecated (warning header added)
Week 12: v1 sunset

A 12-week window gives consumers time to migrate without urgency.

Why This Matters at Scale

When your agent has 1,000 consumers, a silent breaking change creates a support crisis. With versioning, a breaking change is a scheduled event with migration docs, not an incident.

The investment in versioning is small. The cost of not doing it compounds with every consumer you add.

Next Steps

• Check the agent marketplace — agent pages show version history
• If you're a builder, submit an agent with a versioned slug from the start
• Read the async job pattern to understand the rest of the API surface