> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Versions

> Manage agent versions as you develop, test, and publish.

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

```bash theme={null}
# Save a new version
guild agent save --message "Add error handling"

# Save and wait for validation
guild agent save --message "Add error handling" --wait

# Save, validate, and publish in one step
guild agent save --message "Add error handling" --wait --publish
```

## Version states

| State         | Description                                                       |
| ------------- | ----------------------------------------------------------------- |
| **Saved**     | Code is uploaded and stored                                       |
| **Validated** | Runtime has verified the agent builds and conforms to its schemas |
| **Published** | Available to your organization for installation                   |

## 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:

```bash theme={null}
guild agent test
```

Ephemeral versions are created automatically when testing from a local agent directory and don't appear in your version history.

<Note>
  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.
</Note>

## Listing versions

```bash theme={null}
# List all versions of an agent
guild agent versions
```

## Publishing

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

```bash theme={null}
# Publish the latest validated version
guild agent publish
```