Skip to main content
Every time you save an agent, Guild creates a new version. Versions let you iterate on agent code while keeping previous versions available.

​
Version lifecycle

--publish implies --wait, so it always waits for validation and publish to finish before reporting success. --timeout <seconds> bounds that wait; the default is 300. If validation is still running when the timeout elapses, finish the job with guild agent publish <agent-id> --wait.

​
Version states

​
Version numbers and bump levels

When you publish with guild agent save --publish, Guild derives the next version number from the latest published version. Use --bump to choose which part of the semantic version increments: Non-TypeScript agents (GUILD_NATIVE, GOOSE, and OPENCLAW) honor the requested --bump level when deriving their publish version. When nothing has been published yet, the first version is 1.0.0 regardless of bump level. To set an exact version instead of deriving one, pass --version-number <semver>.
When you use -A/--all without --message, non-TypeScript agents whose version bump is skipped default the commit message to "Update agent" instead of failing. Combining -A with --no-bump and no --message still fails with an error.

​
Tool and dependency validation

When you save an agent with guild agent save, Guild validates the tools and dependencies declared in the build before persisting the version. If a declared dependency is broken or violates visibility rules, Guild rejects the build with a 400 BadRequest error and lists the specific validation failures. Guild rejects the build when your agent depends on:
  • A private sub-agent or integration owned by another account.
  • A private sub-agent or integration owned by the same account when the agent itself is public.
  • A sub-agent that has been archived.
Resolve the reported dependencies and save again to build a valid version.

​
Testing before publishing

Use guild agent test to create a temporary version for testing without saving:
Ephemeral versions are created automatically when testing from a local agent directory and don’t appear in your version history.
Ephemeral versions include only files tracked by Git. Files that are already committed or staged with git add are uploaded. New untracked files are ignored until you stage them with git add. Modified tracked files still upload their working-tree content, so you can test uncommitted changes to existing files without committing them first.

​
Listing versions

​
Publishing

Publishing makes a validated version available to your organization. Other team members can install published agents into their workspaces.