Shipping a new agent version in production means risk. What if the new model hallucinates? What if the updated prompt produces worse results? What if latency spikes?

Traditional approaches force you to choose: deploy and hope, or build your own traffic splitting infrastructure. Feature flags, load balancer rules, custom routing logic — weeks of work before you can safely test a new version.

Agentfield makes versioning infrastructure. Register multiple versions of the same agent, and the control plane routes traffic with weighted round-robin. Canary deployments, A/B testing, and instant rollbacks with zero custom code.

What You'd Otherwise Build

Traditional Versioning

What you build:

Feature flag system for agent selection
Load balancer configuration for traffic splitting
Health check integration per version
Metrics pipeline to compare versions
Rollback scripts and runbooks
Version registry and tracking

Then you write business logic.

Agentfield Versioning

What you write:

app = Agent(
    node_id="my-agent",
    version="2.0.0"
)

Agentfield provides:

Weighted traffic routing
Per-version health tracking
Automatic failover
Instant weight adjustment
X-Routed-Version tracking
Zero-downtime rollouts

How It Works

When you deploy an agent with a version field, Agentfield stores it with a composite key (id, version). Multiple versions of the same agent coexist independently — each with its own health status, heartbeat, and traffic weight.

from agentfield import Agent

# Deploy v1.0.0 — the stable version
app_v1 = Agent(node_id="my-agent", version="1.0.0")

@app_v1.reasoner()
async def analyze(text: str) -> dict:
    return await app_v1.ai("Analyze using GPT-4o", text)

# Deploy v2.0.0 — the canary
app_v2 = Agent(node_id="my-agent", version="2.0.0")

@app_v2.reasoner()
async def analyze(text: str) -> dict:
    return await app_v2.ai("Analyze using Claude", text)

// v1.0.0 — stable
agentV1, _ := agent.New(agent.Config{
    NodeID:  "my-agent",
    Version: "1.0.0",
})

// v2.0.0 — canary
agentV2, _ := agent.New(agent.Config{
    NodeID:  "my-agent",
    Version: "2.0.0",
})

// v1.0.0 — stable
const v1 = new Agent({ nodeId: 'my-agent', version: '1.0.0' });

// v2.0.0 — canary
const v2 = new Agent({ nodeId: 'my-agent', version: '2.0.0' });

Callers don't change. A request to my-agent.analyze is routed by the control plane to a healthy version based on traffic weights. The X-Routed-Version response header tells you which version handled the request.

Traffic Routing

The control plane selects versions using weighted round-robin:

Scenario	v1 Weight	v2 Weight	Traffic Split
Equal traffic	100	100	50% / 50%
Canary (10%)	900	100	90% / 10%
Full cutover	0	100	0% / 100%

If a version becomes unhealthy, the control plane automatically routes all traffic to healthy versions. No manual intervention needed.

Deployment Patterns

Canary: Start at 5%, monitor metrics, gradually increase to 100%.

Blue-Green: Deploy new version with weight 0, verify health, then instantly switch weights.

A/B Testing: Run two versions at 50/50 and compare performance using the X-Routed-Version header in your analytics.

See the Multi-Versioning Guide for detailed examples and API reference.

Next Steps

Multi-Versioning Guide — Detailed setup, API reference, and deployment patterns
Connector API — Manage traffic weights programmatically
Cross-Agent Communication — How agents discover and call each other

Agent Versioning