In production, you need to ship new agent versions without downtime. You need canary deployments where 5% of traffic hits the new version. You need A/B testing to compare model performance. You need blue-green rollouts where you instantly switch traffic.

Agentfield's multi-versioning makes this infrastructure-level. Register multiple versions of the same agent, and the control plane handles weighted traffic routing automatically.

How It Works

When an agent registers with a version field, Agentfield stores it with a composite key of (id, version). Multiple versions of the same logical agent coexist as separate rows, each with independent health status and traffic weight.

from agentfield import Agent

# Version 1 - the stable release
app = Agent(
    node_id="my-agent",
    version="1.0.0",
    description="Stable release"
)

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

import { Agent } from '@anthropic/agentfield';

const agent = new Agent({
  nodeId: 'my-agent',
  version: '2.0.0',
  description: 'New model release'
});

agent.reasoner('analyze', async (ctx) => {
  return ctx.ai('Analyze this text', ctx.input.text);
});

agentNode, _ := agent.New(agent.Config{
    NodeID:  "my-agent",
    Version: "1.0.0",
})

agentNode.RegisterReasoner("analyze", analyzeHandler)

# Send 90% to v1, 10% to v2 (canary)
curl -X PUT http://localhost:8080/connector/reasoners/my-agent/versions/1.0.0/weight \
  -H "Authorization: Bearer $CONNECTOR_TOKEN" \
  -d '{"weight": 900}'

curl -X PUT http://localhost:8080/connector/reasoners/my-agent/versions/2.0.0/weight \
  -H "Authorization: Bearer $CONNECTOR_TOKEN" \
  -d '{"weight": 100}'

Key Concepts

Group ID

Agents with the same id but different version values share a group_id (defaults to id). This groups versioned nodes logically so the control plane can discover all versions of an agent.

Traffic Weight

Each versioned node has a traffic_weight (0–10000, default 100) that controls the proportion of traffic it receives. The control plane uses weighted round-robin across healthy nodes in the same group.

Version-Aware Heartbeats

Each versioned agent includes its version in heartbeat payloads. The control plane tracks health independently per version — if v2 goes unhealthy, v1 continues serving all traffic automatically.

Deployment Patterns

Canary Deployment

Roll out a new version to a small percentage of traffic:

# Deploy v2 with low weight
# v1 is already running with weight 100

# Start with 5% canary
curl -X PUT .../versions/2.0.0/weight -d '{"weight": 5}'

# Monitor metrics, then increase
curl -X PUT .../versions/2.0.0/weight -d '{"weight": 50}'

# Full rollout
curl -X PUT .../versions/1.0.0/weight -d '{"weight": 0}'
curl -X PUT .../versions/2.0.0/weight -d '{"weight": 100}'

Blue-Green Rollout

Deploy the new version alongside the old, then switch instantly:

# Deploy v2 (green) with weight 0 — no traffic yet
# Verify v2 health in the UI

# Instant switch
curl -X PUT .../versions/1.0.0/weight -d '{"weight": 0}'
curl -X PUT .../versions/2.0.0/weight -d '{"weight": 100}'

# Rollback if needed
curl -X PUT .../versions/1.0.0/weight -d '{"weight": 100}'
curl -X PUT .../versions/2.0.0/weight -d '{"weight": 0}'

A/B Testing

Compare two model versions with equal traffic:

curl -X PUT .../versions/gpt4o/weight -d '{"weight": 500}'
curl -X PUT .../versions/claude/weight -d '{"weight": 500}'

Use the X-Routed-Version response header to track which version served each request in your analytics.

API Reference

List Versions

GET /connector/reasoners/:id/versions

Returns all registered versions of an agent with their health status and traffic weights.

Get Version

GET /connector/reasoners/:id/versions/:version

Returns details for a specific version.

Update Traffic Weight

PUT /connector/reasoners/:id/versions/:version/weight

Body:

{
  "weight": 500
}

Weight must be between 0 and 10000.

Restart Version

POST /connector/reasoners/:id/versions/:version/restart

Sends a restart signal to a specific versioned agent.

List Agent Groups

GET /api/v1/agents/groups

Returns all agent groups with summary information (version count, total traffic weight).

Next Steps

• Connector — Manage agents programmatically via the connector API
• Agent Discovery — Runtime discovery of versioned agents
• Deployment Overview — Production deployment patterns