Agent Version States (Saved / Validated / Published)

• Every Guild agent version passes through three lifecycle states: Saved, Validated, and Published.
• Saved means the code is uploaded and stored. Validated means Guild's runtime verified the agent builds and conforms to its schemas. Published means the version is available for teammates in your organization to install.
• You can save without validating and without publishing, and you can wait for validation with --wait or save-validate-publish in one command with --wait --publish.
• An agent has to be Published before other members of your organization can install and use it.

Guild treats every agent version as an object with a lifecycle, not just a file blob. When you save a version, Guild moves it through a defined sequence of states, and each transition is meaningful. Saved says the code arrived. Validated says the code is well-formed and safe to run. Published says the version is now real for the rest of your organization.

The states matter because they map onto operational questions people actually ask. "Is my change uploaded?" is Saved. "Does it actually work?" is Validated. "Can my teammates use it?" is Published. Each state answers exactly one of those questions and none of the others.

Saved: code is uploaded and stored

Saved is the first state after guild agent save. The version's files are uploaded to Guild and persisted. From Guild's point of view, the version exists — but nothing has been verified yet, and no one else can use it.

Validated: build passed and schemas conform

Validated means Guild's runtime built the agent successfully and confirmed it conforms to its declared schemas. For TypeScript agents, the build step compiles the code and validates that inputSchema and outputSchema are structured the way LLM providers require. For Guild Native and Goose agents, there is no build to run, so they skip straight to Validated. If validation fails, Guild returns a 400 BadRequest error listing the specific problems.

Published: available to the org

Published is the terminal state. A published version is what teammates see and install. Until a version is published, it exists only in your account's version history.

Save is default and asynchronous

guild agent save --message "Add error handling"

Uploads the version and returns immediately. Validation runs in the background. If you want to see the outcome, either poll or use --wait.

Wait for validation to finish

guild agent save --message "Add error handling" --wait

Blocks until validation completes and reports success or the specific errors. Useful when you're iterating and want to know immediately whether the change built.

Save, validate, and publish in one command

guild agent save --message "Add error handling" --wait --publish

For confident changes, this collapses the whole lifecycle into a single command: upload, validate, and publish. If validation fails, publish does not run.

Publish an already-validated version separately

guild agent publish

Publishes the latest Validated version if you saved without --publish. This is common when a save should validate but not immediately go live for the org.

Tool and dependency validation happens at Save

Guild rejects a save if the agent declares a broken or invalid dependency: a private sub-agent or integration owned by another account, a private dependency in a public agent, an archived sub-agent. Resolve the dependency, save again, and Guild will re-validate.

The distinction between Saved and Validated is a safety line

Save is fast because it just uploads bytes. Validation is where Guild actually checks that the code works. Keeping the two separated means a developer can save frequently as a checkpoint without every save blocking on a full build.

The distinction between Validated and Published is a governance line

A version that builds does not necessarily need to be visible to the org. Publish is a separate act, and it's the moment the version becomes something teammates might install. That gap is what makes Guild's agents governable — publishing is a decision, not a side effect.

Explicit publish protects against accidental rollouts

If publish were automatic on every save, every experimental version would get installed by anyone with an install-latest button. The default behavior — save does not publish — is the safe default. Add --publish only when you mean it.

Use --message to explain changes

Every save creates a version. Every version shows up in guild agent versions with its message. Descriptive messages are your changelog for the agent.

Publishing is irreversible from a discoverability standpoint

Once a version is Published, teammates who have already installed the agent will see it available as an upgrade. Yanking a Published version is not the same as never publishing it. Prefer --wait to catch problems before publish.

Ephemeral builds are outside this lifecycle

Ephemeral builds created during guild agent test or guild agent chat do not become versions and do not enter the Saved / Validated / Published lifecycle. They are for local iteration only.

Every version is inspectable

guild agent versions lists every saved version, guild agent get shows details for a specific one. The lifecycle is transparent and auditable, which matters for regulated environments.

Guild is a control plane for AI agents, a place to build, deploy, and govern the agents your teams run in production. The Saved / Validated / Published lifecycle is what makes agent releases first-class events rather than accidental side effects of hitting save.

• The versions guide walks through the full save, validate, and publish cycle end to end.
• Ephemeral builds are the local iteration mechanism that sits outside this lifecycle.
• Sign in at app.guild.ai to build and publish your first agent version.