Versions and publishing

An agent has a draft — mutable, autosaved as you edit on the canvas — and zero or more versions — immutable, cut from the draft by publishing. Deployed apps, schedules, and pinned clients run versions; the draft is yours to break.

Publish your first version

Start with approved access and a workspace key. In the dashboard, select that workspace and open Agents. Create or open the agent on the canvas, configure a model available in the deployment, and test the draft with the run panel. Draft runs are for authoring, not a promise that the graph is ready for your users.

Click Publish to save the draft and cut an immutable version. Confirm the published version in the canvas status control, and record both the agent UUID and version number. API callers receive agent_id and version from the publish response. Use the version history to inspect prior versions or roll back; publishing again is an explicit release decision, not autosave.

Next, install the SDK and mint a session. You can integrate with the generic hook first, then optionally generate a pinned client. Publishing does not install packages or generate code in your app.

The lifecycle

All of these are management-tier — an operator api-key or the dashboard. A customer session cannot move your graphs.

What runs when

Three rules, in precedence order:

1. version: N — an explicit pin runs that immutable version. Wins over everything.
2. use_draft — runs the mutable draft (the canvas run panel does this). Draft runs pin a sentinel version and snapshot the graph onto the conversation, so a paused draft run resumes against the graph it started with, not whatever you've edited since.
3. Default — external runs execute the published version. (A never-published agent falls back to its latest saved graph.)

The punchline for production: publishing a new version does not move pinned consumers — and editing a draft moves nobody.

Publishing is a gate

Publish is where the strict checks live (drafts are deliberately tolerant so you can save work in progress):

• Every subagent attachment must resolve and build clean, pinned to a version — a dangling or unpinned subagent is a 422 at publish, not a failure mid-run.
• Each publish records who did it.

Retrieval evaluation is a separate corpus-publication gate, not a check that every agent publish automatically runs. Installing an eval pack protects that index's corpus publication; it does not evaluate all behavior of an agent that uses the index. See Retrieval.

Pins, from the consumer side

• Generated clients bake AGENT = { id, version } in: every run sends the pinned version. A check with the same --agent, --version, --name, and --out, plus --check, detects a changed generated artifact in CI. Re-run codegen to move. Typed clients has the exact sequence; --check requires --version.
• Schedules and run-as take an optional version pin — absent means "track whatever is published". Schedules covers the tri-state.

One loose end: model: "any"

A graph node can name model: "any" — a deferred choice resolved at run time to the deployment's default model (the operator's provider config). Pin an explicit model id for reproducibility; use "any" when you'd rather inherit the deployment's current default — knowing the operator can change it between publishes, under the same version number.

Next

Quickstart continues with installation and session minting. Server tools covers what the platform gives the agent to call.