Skip to main content
Every agent has two faces: the draft you are editing and the published version your customers reach. Understanding which one runs where is the difference between “it works in the tester but fails on the phone” and a clean launch.

​
The three states

Draft

Your live working copy. Every edit — knowledge, skills, guardrails, playbooks — changes the draft. It is never billed and never frozen.

Published

A frozen snapshot of the draft, taken at publish time. Phone calls and chat sessions serve the last published version, not your draft.

Sandbox

A way to run the draft on demand — the tester and draftMode: true chat sessions compile the draft ephemerally so you can try changes before they go live.

​
How traffic is routed

  • The tester runs the draft. It compiles your current draft on the fly, so it always reflects your latest unsaved-to-live changes.
  • Phone & chat serve the last published version. Until you publish, callers and the public chat endpoint keep getting the old behavior.
  • Publishing freezes a version. A publish takes your draft, compiles it, and stores it as an immutable, numbered version. That snapshot is what goes live.
  • Rollback restores a version. If a new publish misbehaves, repoint “published” at any earlier version — no re-editing required.
This is the most common gotcha: you edit, the tester looks perfect, but the phone still does the old thing. Editing changes the draft; only publishing moves it to live.

​
Why your first live call returns 409

A chat session (and any non-draft channel) needs a published version to serve. If an agent has never been published, a non-draft chat session responds 409 with the problem code no_published_version. The fix is always the same: publish first. 
// POST /chat/sessions with draftMode:false on an unpublished agent
{ "type": "...", "title": "Conflict", "detail": "no_published_version" }
Testing the draft directly? Set draftMode: true when you create a chat session, or use the in-dashboard tester. Draft sessions compile your draft ephemerally and are not billed.

​
A clean release flow

1

Edit the draft

Make your changes. Add knowledge, wire skills, tune guardrails.
2

Test against the draft

Use the tester or a draftMode: true chat session to confirm behavior.
3

Review what will change

Pull the pre-publish diff and report to see exactly what is about to go live.
4

Publish

Freeze the draft into a new numbered version. Phone & chat now serve it.
5

Roll back if needed

Repoint published to a known-good version in one call.

​
In the API

ActionEndpointScope
Publish (freeze a version)POST /agents/{id}/publishagents:write
Roll back to a versionPOST /agents/{id}/rollbackagents:write
List version historyGET /agents/{id}/versionsagents:read
Pre-publish what-changed diffGET /agents/{id}/versions/{versionId}/diffagents:read
Pre-publish reportGET /agents/{id}/prepublish-reportagents:read
Authenticate every call with Authorization: Bearer flowyte_sk_…. A successful publish returns 201 with the new frozen version; 409 signals a publish race or version mismatch. See Agents and Channels for what each version actually serves.