Skip to main content

Traffic and revisions

Every change to an agent — new code, a secret, an env var, a config edit — creates a new immutable revision. Traffic can be split across revisions, which gives you canary rollouts and instant rollback. This page shows how.

What a revision is​

A revision is a frozen snapshot of your agent: the built image, plus the env vars, secrets, and compute config in force at that moment. Revisions never change after creation — that's what makes rollback trustworthy. A new revision is created by:

By default, all traffic moves to the newest revision once it is ready.

List revisions​

GET /v1/agents/{name}/revisions returns revisions newest first, each annotated with its live traffic share:

curl -s "$CAI_API/v1/agents/research-buddy/revisions" \
  -H "Authorization: Bearer $CAI_TOKEN"

You should see:

{
  "agent": "research-buddy",
  "revisions": [
    {
      "name": "research-buddy-00003",
      "generation": 3,
      "traffic_percent": 100,
      "created_at": "2026-08-11T10:00:00Z",
      "ready": "True",
      "replicas": 1
    },
    {
      "name": "research-buddy-00002",
      "generation": 2,
      "traffic_percent": 0,
      "created_at": "2026-08-10T09:12:00Z",
      "ready": "True",
      "replicas": 0
    }
  ]
}

ready is a string, not a boolean: it mirrors the underlying Ready condition status, so it is "True", "False", or "Unknown" while a revision is still rolling out. Compare it against "True" rather than testing it for truthiness. A revision also carries tag (its own addressable name) only when it has one — the field is omitted otherwise.

Move traffic​

POST /v1/agents/{name}/set-traffic takes the complete split — every entry you want serving, summing to exactly 100.

Canary a new revision​

Send 10% of requests to the new revision, keep 90% on the old one:

curl -s -X POST "$CAI_API/v1/agents/research-buddy/set-traffic" \
  -H "Authorization: Bearer $CAI_TOKEN" -H 'content-type: application/json' \
  -d '{"traffic": [
        {"revision_name": "research-buddy-00002", "percent": 90},
        {"revision_name": "research-buddy-00003", "percent": 10}
      ]}'

You should see (202):

{
  "agent": "research-buddy",
  "traffic": [
    {"revision_name": "research-buddy-00002", "percent": 90},
    {"revision_name": "research-buddy-00003", "percent": 10}
  ]
}

Watch logs and behavior on the canary, then widen the split — 50/50, then 100 — by posting a new complete split each time.

Roll back​

Something's wrong with the new revision? Point everything back at the last good one:

curl -s -X POST "$CAI_API/v1/agents/research-buddy/set-traffic" \
  -H "Authorization: Bearer $CAI_TOKEN" -H 'content-type: application/json' \
  -d '{"traffic": [{"revision_name": "research-buddy-00002", "percent": 100}]}'

Rollback is a routing change, not a rebuild — it takes effect as fast as the target revision can serve (it may cold-start if it had scaled to zero).

Errors​

CodeMessage
400traffic is required - send the complete split, e.g. [{"revision_name":"research-buddy-00002","percent":100}]
400revision research-buddy-00007 does not exist for this agent
Rollback moves traffic, not source

set-traffic changes which revision serves requests — nothing else. The agent's stored source files are unchanged, so the next redeploy builds forward from the latest source and supersedes your pin. If the source itself is bad, fix it (revert your code, redeploy), don't just re-route around it.

Revisions in the console​

The agent detail page's Revisions tab lists every revision with its traffic percentage. Rollback is one click: pick a revision and confirm the Send all traffic to <rev>? prompt. The tab repeats the caveat above — the pin is of serving, not source.

Compute config also rolls revisions​

PATCH /v1/agents/{name}/config edits scaling (min_scale, max_scale, container_concurrency), resources (CPU/memory requests and limits), and timeout_seconds. It's a sparse body — omitted fields keep their current values — and like every other change, it creates a new revision. max_scale: 0 means unbounded. In the console this is the Configure modal. Setting min_scale: 1 keeps one instance always warm — the standard fix for cold-start latency, at the cost of an always-on instance.

Quick reference​

QuestionAnswer
What creates a revision?Code deploys, secret/env changes, config changes
Can a revision change after creation?No — immutable by design
How do I canary?POST a split like 90/10 to set-traffic
How do I roll back?POST 100% to the last good revision
Does the split need to sum to 100?Yes, and it must be the complete split
Does rollback restore old source?No — serving traffic only