Product guide · Browse & search
Publishing and versions
Move from an editable draft to a version you can run, and update the places that depend on it.
Drafts let you edit a definition. Publishing creates an immutable version that runs and other definitions can reference. Changing a draft does not rewrite a version already published.
Prepare and publish
- Review the objective, input/output contract, model, capabilities, and limits. For workflows, check the start step, mappings, and every branch.
- Save the draft. Workflow edits save automatically; confirm the save status and resolve conflicts before publishing.
- Choose Publish…. Review the model and dependency readiness, bind required knowledge slots, and choose a queue if needed.
- Confirm publication and inspect the new entry under Versions.
- Check Access, then run representative inputs against that version. Include the failure, rejection, and waiting paths that matter for your process.
The current agent Test panel validates draft input. It does not execute an unpublished agent against a model. Publish and run a version to test real behavior.
Know which references move
| Consumer | What happens when you publish a new version |
|---|---|
| Existing run | Keeps the definition it started with. |
| Schedule | Continues targeting its selected published version until changed. |
| Event trigger | Continues using its configured version until moved. Already accepted work keeps its target. |
| Agent used as a subagent | The parent's published definition retains the selected version. Update and republish the parent to change it. |
| Agent or workflow step inside a workflow | Retains the selected published reference. Update the draft and publish the containing workflow. |
| Named Client apps target | Resolves to the latest published version of that agent or workflow. Test contract compatibility before publishing. |
| Queue assignment | Can be changed on a published target; new versions inherit the queue unless another is chosen. |
Publishing and rollout are therefore related but separate decisions. Check every entry point that should use the change rather than assuming all consumers update together.
Make a safe revision
Change the draft and publish another version. Compare both versions with the same representative input. For a workflow, test branches independently: a successful approved run does not exercise rejection or timeout behavior.
When changing an input or output schema, update dependent data mappings and application forms. For named client targets that follow the latest version, coordinate incompatible changes with the consuming application.
Use separate environments for development and live use. Connections, credentials, grants, collections, and execution policy are environment configuration; copying a portable definition does not grant access in the destination. Advanced promotion and definition operations are covered in the developer configuration guide.
Retire an old version
Retirement prevents new work from using the retired target while preserving historical records and allowing already-admitted work to finish. Review schedules, triggers, parent agents, and workflows before retiring a version they still reference.
If a change behaves unexpectedly, inspect the version actually used by the run first. Fix the draft, publish, and deliberately update affected references. Do not use retirement as a substitute for canceling an active run or undoing an external action.