Skip to main content

Traffic and revisions

Every change to an agent creates a new immutable revision — new code, a secret, an env var, a config edit, any of them. You can split incoming requests across revisions by percentage. That is what gives you canary releases, where a small share of real traffic tries the new version first, and instant rollback. This page shows how to do both.

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. This is also the answer to "did my traffic change take effect yet?" — the traffic column is read from live routing, not from what you asked for.

platformctl agents revisions research-buddy

You should see:

NAME                  GENERATION  TRAFFIC  READY  REPLICAS
research-buddy-00003  3           100%     yes    1
research-buddy-00002  2           0%       yes    0

A revision serving no traffic with no replicas is the normal resting state on a scale-to-zero platform, not a fault. Add -o json for the fields the table leaves out — the state word behind that yes/no, the image, the revision's URL and tag, and any failure reason.

A revision reports readiness the same way everything else on the platform does: ready is a plain boolean, answering the one question "can this serve right now?", and it is the field to branch on. The three-way answer sits beside it in state, which reads "ready", "not_ready", or "unknown" — and those last two are genuinely different things. not_ready is a verdict someone reached about a revision that is rolling out or broken; unknown means nothing has reported on it yet. When a revision is not ready, reason and message carry the runtime's own words for why, which is what the console shows in the badge tooltip. If you have an older script that compares ready against the string "True", change it to a plain truth test — the string is gone.

A revision also carries a tag, its own addressable name, but only when it has one. The field is left out 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:

platformctl agents set-traffic research-buddy \
  research-buddy-00002=90 research-buddy-00003=10

You should see:

REVISION              PERCENT
research-buddy-00002  90%
research-buddy-00003  10%

latest is accepted in place of a revision name. It is not a revision but the "newest revision" target — a split that keeps following new deploys, which is the state a freshly deployed agent is in. latest=90 research-buddy-00006=10 canaries the other way round.

There is no Console tab here: the browser offers one-click rollback, not a percentage split. A canary is the CLI or the API.

Watch the logs and the behavior of the canary. When it looks right, widen the split to 50/50 and then to 100, sending a fresh complete split each time.

Roll back​

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

platformctl agents set-traffic research-buddy research-buddy-00002=100
platformctl agents revisions research-buddy    # where the live traffic answer shows up

Rollback is a routing change, not a rebuild. Nothing is compiled and nothing is pushed. It takes effect as soon as the target revision can serve, which may include a cold start if that revision had scaled to zero — the platform reprograms routing within a few seconds rather than instantly.

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.

Compute config also rolls revisions​

PATCH /v1/agents/{name}/config edits three groups of settings: scaling (min_scale, max_scale, container_concurrency), resources (CPU and memory requests and limits), and timeout_seconds.

The change is sparse everywhere: anything you leave out keeps its current value, which is what stops a scaling change from resetting your resources. Like every other change, a config edit creates a new revision. max_scale: 0 means no ceiling on how many copies may run at once.

platformctl agents config get research-buddy
platformctl agents config set research-buddy --min-scale 1 --max-scale 10
platformctl agents config set research-buddy --cpu 500m --memory 1Gi
platformctl agents config set research-buddy --timeout 600 --concurrency 8

config get on an agent that has never been configured prints no compute overrides - this agent runs on the platform defaults. Only the flags you actually pass are sent. Passing an empty value — --memory "" — removes that one entry rather than setting it to nothing.

Setting min_scale: 1 keeps one instance always running. That is the standard fix for cold-start delay, and the trade is that you pay for an instance that never sleeps.

Summary​

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

Next steps​